Where does DBOS store scheduled workflows?#

DBOS stores scheduled workflows in the system database. Each schedule is represented as a record in the workflow_schedules table. This table includes the following fields:

• schedule_id: Unique identifier for the schedule
• schedule_name: The name of the schedule (must be unique)
• workflow_name: The fully-qualified name of the workflow function to invoke
• workflow_class_name: The fully-qualified class name if the workflow is a static class method, or None for module-level functions
• schedule: The cron expression specifying when the workflow should run (supports seconds with 6 fields)
• status: The current status of the schedule (e.g., ACTIVE)
• context: A serialized context object passed to each workflow invocation
• last_fired_at: Timestamp of when this schedule last executed successfully. Tracks execution history and enables automatic backfill functionality
• automatic_backfill: Boolean indicating whether to automatically backfill missed executions on startup. When true, the scheduler executes missed schedule instances on startup
• cron_timezone: IANA timezone name for evaluating the cron expression (e.g., "America/New_York"), or None for UTC. Allows schedules to be evaluated in specific timezones instead of UTC
• queue_name: Optional name of the declared queue to enqueue scheduled workflows to. If None, scheduled workflows use the internal queue (_dbos_sys_internal). This field enables concurrency management by allowing scheduled workflows to be directed to specific declared queues

This schema allows DBOS to support both module-level workflows and static class method workflows. When you schedule a static class method, the workflow_class_name field is set to the registered class name. For module-level workflows, this field is None. Instance methods (such as those on DBOSConfiguredInstance classes) cannot be scheduled; attempting to do so will raise an error.

Schedules are persistent and survive application restarts. You can create, query, update, or delete schedules at runtime using DBOS.create_schedule, DBOS.delete_schedule, or the client API. DBOS periodically polls the database for new or updated schedules, and each schedule is managed by a dedicated thread that triggers the workflow at the specified times. Changes to schedules are immediately reflected across all workers.

To remove a schedule, use DBOS.delete_schedule or set it to None in DBOS.apply_schedules. This will stop scheduling and executing that workflow. Schedules are managed as persistent database records and are no longer solely determined by the presence of the @DBOS.scheduled decorator in your code. Removing the decorator only affects statically scheduled workflows; dynamically scheduled workflows remain active until explicitly deleted from the database.

For more details, see the dynamic scheduling API documentation. The relevant database schema and scheduling logic are implemented in the workflow_schedules table and the scheduler components.