---
title: "How to Build a Better Cron for the Cloud | DBOS"
description: "Learn how to use the DBOS Transact durable execution library to build reliable scheduled workflows in the cloud, with exactly-once transactional execution."
url: "https://www.dbos.dev/blog/how-to-build-cloud-cron-jobs"
---

# Building a Better Cron for the Cloud

Chuck Bear

July 1, 2024

How To

## Introduction

Do you want your code to run at a certain time, once or on a repeating schedule?  You wouldn’t be the first application developer to need such a utility; Unix systems have offered \`cron\` for 45 years, and \`cron\` was far from the first tool with similar scheduling features.  Subsequently, other on-premises solutions such as \`Quartz\` for Java, or \`CronJobs\` for Kubernetes provided deeper integration with their respective application development environments.

But what if you want scheduling built into your application, without a separate server to manage? Better still, what if this scheduler ensured that your jobs completed exactly once?  (Not just started exactly once, but completed exactly once?)

Scheduled Workflows are a simple solution, combining the familiarity of \`cron\`-like scheduling with the execution guarantees of DBOS Transact. It’s like \`cron\` built into your application, but with unmatched execution guarantees.

In this blog post, we’ll:

1.  Use the DBOS Transact open source durable execution library ([Python](https://github.com/dbos-inc/dbos-transact-py) and [TypeScript](https://github.com/dbos-inc/dbos-transact-ts)) to write and schedule a workflow
2.  Review the DBOS Transact processing guarantees, which ensure that scheduled operations execute exactly one time, regardless of interruptions, crashes, or failures

## Writing a Scheduled Workflow

For illustrative purposes, let’s write a workflow that sends out a nightly summary email to the manager of a widget store. We will use a simple workflow that first counts up sales from the day before, and then sends an email using [Amazon SES](https://www.npmjs.com/package/@dbos-inc/communicator-email-ses).

Our DBOS Code may be written as:

```typescript
const reportSes = configureInstance(SendEmailCommunicator, 'reportSES', {awscfgname: 'aws_config'});

interface SalesSummary {
  order_count: number;
  product_count: number;
  total_price: number;
}

class ShopUtilities {  
  @Workflow()  
  static async nightlyReport(ctx: WorkflowContext) {
    // We will get the real date once we start scheduling...
    const yesterday = new Date("2024-06-25");
    yesterday.setDate(yesterday.getDate() - 1);

    const sales = await ctx.invoke(ShopUtilities).getDailySales(yesterday);
    await ShopUtilities.sendStatusEmail(ctx, yesterday, sales);  
  }

  @Transaction({readOnly: true})
  static async getDailySales(ctx: KnexTransactionContext, day: Date) {
    const startOfDay = new Date(day.setHours(0, 0, 0, 0));
    const endOfDay = new Date(day.setHours(23, 59, 59, 999));

    const result = await ctx.client('orders')      
      .join('products', 'orders.product_id', 'products.product_id')      
      .whereBetween('orders.last_update_time', [startOfDay, endOfDay])
      .select(ctx.client.raw('COUNT(DISTINCT orders.order_id) as order_count'))
      .select(ctx.client.raw('COUNT(orders.product_id) as product_count'))
      .select(ctx.client.raw('SUM(products.price) as total_price'));

    return result[0] as SalesSummary;
  }

  static async sendStatusEmail(ctx: WorkflowContext, yd: Date, sales: SalesSummary) {
    await ctx.invoke(reportSes).sendEmail({  
      to: ['manager@widgetstore.dbos.dev'],  
      from: 'reportbot@widgetstore.dbos.dev',  
      subject: `Daily report for ${yd.toDateString()}`,  
      bodyText: `Yesterday we had ${sales.order_count} orders, selling ${sales.product_count} units, for a total of ${sales.total_price} dollars`,
    });    
  }
}
```

‍

Note that in the above code, we’ve temporarily used the current time (via \`new Date()\`) as the basis for the report. We will fix that as we schedule the reporting workflow.

Scheduling the report to be generated at midnight is straightforward, we just apply the \`@Scheduled\` decorator to the workflow. The signature of the scheduled workflow function must be adjusted to accept two date parameters, the scheduled time and the current time. We will pass the date provided by the scheduler to the reporting query, thus ensuring that the correct report is generated, even in the unlikely event that the workflow is significantly delayed.

The completed workflow function is shown below:

```typescript
@Scheduled({crontab: '0 0 * * *'}) // Every midnight  
@Workflow()
static async nightlyReport(ctx: WorkflowContext, schedDate: Date, _curdate: Date)
{
  const yesterday = schedDate;
  yesterday.setDate(yesterday.getDate() - 1);

  const sales = await ctx.invoke(ShopUtilities).getDailySales(yesterday);
  await ShopUtilities.sendStatusEmail(ctx, yesterday, sales);  
}
```

‍

## Execution Guarantees

DBOS Transact will guarantee that a report is generated and forwarded to the email service exactly once for each night:

-   DBOS Transact uses its system database to keep durable records of the workflow schedule. DBOS Transact uses these records to ensure that workflows are initiated _at least once_. The scheduler assigns a unique key to the workflow, based on the function name and scheduled date and time. The key is used to deduplicate the workflow runs, resulting in _exactly once_ workflow initiation.
-   DBOS Workflows (and associated Transactions) run to completion _exactly once_.  Workflows that are interrupted (for example due to a hardware failure) are restarted transparently.
-   DBOS Communicators can easily calculate an _idempotency key_ so that their work is completed exactly once.

## Deploying Scheduled Workflows

The open source DBOS Transact durable execution library can only provide its execution guarantees when running in a deployment environment that:

1.  Provides a reliable system database
2.  Automatically restarts the cron job and initiates workflow recovery in the event of any system failures

DBOS Transact stores workflow state in Postgres, so you can deploy your application wherever you already run code, with a Postgres database as its system database. When a process restarts after a failure, DBOS recovers its interrupted workflows. To monitor and manage your scheduled workflows in production, connect your application to [DBOS Conductor](https://www.dbos.dev/dbos-conductor).

If you are using the code above, you’ll need to be set up to use the [AWS SES service](https://aws.amazon.com/ses/):

-   Get an access key and secret from the AWS console
-   Put an AWS configuration in dbos-config.yaml as follows

```javascript
application:
  aws_config:
    aws_region: ${AWS_REGION}
    aws_access_key_id: ${AWS_ACCESS_KEY_ID}
    aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}
```

-   Ensure the referenced environment variables (AWS\_REGION, AWS\_ACCESS\_KEY\_ID, AWS\_SECRET\_ACCESS\_KEY) are set during application deployment

‍

## Summary

DBOS Transact provides an elegant Typescript development environment with exactly-once execution guarantees. Scheduled Workflows add one more tool to the library, a straightforward scheduling service that ensures jobs are executed to completion exactly once.

‍

## Further Information

-   Ask questions in the DBOS community on [Discord](https://discord.gg/jsmC6pXGgX).
-   Check out DBOS Transact open source code, star our repository, or contribute [on GitHub](https://github.com/dbos-inc/dbos-transact).
-   DBOS Transact, check out the [quickstart](https://docs.dbos.dev/getting-started/quickstart) and [docs](https://docs.dbos.dev/).
-   Using [Scheduled Workflows in DBOS Transact](https://docs.dbos.dev/tutorials/scheduled-workflows)
-   More information on sending emails: [AWS SES service](https://aws.amazon.com/ses/).
-   Watch an in-depth explanation of [DBOS Transact’s execution guarantees](https://www.dbos.dev/webcast/stonebraker-increase-software-engineering-productivity) from DBOS co-founder Mike Stonebraker.

‍
