Scheduled Syncs¶

Automate data syncs with cron schedules so your warehouse stays fresh without manual intervention.

Quick Start¶

1. Add a schedule:

   dango schedule add
   

2. Verify it's registered:

   dango schedule list
   

3. Check the next run time:

   dango schedule status daily_sync
   

That's it — your sources will sync automatically on the cron schedule you chose.

Detailed Steps¶

The Schedule Wizard (dango schedule add)¶

The interactive wizard walks you through creating a schedule:

$ dango schedule add

📅 Schedule Setup
─────────────────

Schedule name (lowercase, letters/numbers/underscores): daily_sync
Schedule type:
  Sync & Transform (recommended)
  Sync only (no transform)
  Transform only (dbt)
Choice: Sync & Transform (recommended)

Select sources to sync:
  [x] stripe
  [x] google_sheets
  [x] hubspot
(SPACE to toggle, ENTER to confirm)

Run frequency:
  Every hour
  Every 2 hours
  Every 3 hours
  Every 4 hours
  Every 6 hours
  Every 8 hours
  Every 12 hours
  Daily
  Weekly
  Custom cron
Choice: Daily

Timezone (leave blank for UTC): America/New_York

✅ Schedule 'daily_sync' created
   Next run: 2026-05-16 06:00:00 EDT

Schedule Types¶

Frequency Options¶

The wizard offers these frequency presets, then prompts for specific time details (hour, minute, day of week):

After selecting a preset, the wizard prompts for time details. For example, choosing "Daily" asks for the hour and minute; choosing "Weekly" asks for the day, hour, and minute.

Timezone Handling¶

Schedules default to UTC if no timezone is specified. To use a local timezone:

schedules:
  - name: daily_sync
    cron: "0 6 * * *"
    timezone: "America/New_York"

dbt Selectors (for type: dbt schedules)¶

When using type: dbt, specify a dbt command with selectors:

schedules:
  - name: hourly_marts
    type: dbt
    cron: "0 * * * *"
    dbt_command: "run --select tag:hourly"

Common dbt selector patterns:

# Run a specific model and its upstream dependencies
dbt_command: "run --select +fct_orders"

# Run all models in a directory
dbt_command: "run --select marts.*"

# Run models tagged for hourly refresh
dbt_command: "run --select tag:hourly"

# Run tests after a specific model
dbt_command: "test --select fct_orders"

Configuration Reference¶

schedules.yml Format¶

Schedules are stored in .dango/schedules.yml. The wizard writes this file automatically, but you can also edit it directly.

# .dango/schedules.yml

schedules:
  - name: daily_sync
    type: sync                  # sync | sync_only | dbt
    cron: "0 6 * * *"          # 5-field cron expression
    sources:                    # Sources to sync (ignored for type: dbt)
      - stripe
      - google_sheets
    enabled: true               # Toggle without removing
    timezone: "America/New_York"
    notify_on:                  # Per-schedule notification override
      - failure
      - stale

  - name: hourly_marts
    type: dbt
    cron: "0 * * * *"
    dbt_command: "run --select tag:hourly"
    timeout_minutes: 30         # Override default 60-min timeout

# Notification config (see Webhook Notifications for details)
notifications:
  webhooks:
    - name: slack_alerts
      url: "https://hooks.slack.com/services/T.../B.../xxx"
      format: slack
  on_failure: true
  on_success: true
  on_stale: true
  on_governance: true
  on_analysis: true
  stale_threshold_hours: 24

Schedule Field Reference¶

Cron Expressions¶

Cron expressions use 5 fields:

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-7, Sun=0 or 7)
│ │ │ │ │
* * * * *

Execution History¶

Viewing History¶

# Status of a specific schedule
dango schedule status daily_sync

# List all schedules with last run info
dango schedule list

GET /api/schedules/{name}/history
GET /api/schedules/history/recent

Status Values¶

History records are retained for 30 days, after which they are automatically cleaned up. Running records older than 24 hours are automatically marked as failed (stale detection).

Resilience & Recovery¶

Scheduled jobs have built-in retry and timeout handling:

Retry Behavior¶

After all 3 attempts fail, the job is marked as failed and a sync_failed webhook notification is sent (if configured).

Timeout¶

Jobs are killed after 60 minutes by default (configurable per-schedule via timeout_minutes). Timed-out jobs are marked with timeout status and do not retry.

Missed Run Recovery¶

If Dango was offline when a schedule was supposed to fire (e.g., laptop was asleep, server was rebooting), the missed run executes immediately on startup. This is controlled by misfire_grace_time=None (unlimited) and coalesce=True — multiple missed runs collapse into a single execution.

Verification¶

After creating a schedule, verify it's working:

# List all schedules with their status
dango schedule list

# Check a specific schedule's details and next run time
dango schedule status daily_sync

Expected output from dango schedule list:

Schedules
─────────
Name          Type   Cron          Sources                Enabled  Next Run
daily_sync    sync   0 6 * * *     stripe, google_sheets  yes      2026-05-16 06:00
hourly_marts  dbt    0 * * * *                            yes      2026-05-15 15:00

Troubleshooting¶

Schedule not firing

• Verify dango start is running (local) or the server is online (cloud)
• Check dango schedule list — is the schedule enabled?
• Verify the cron expression: dango schedule status <name> shows the next run time

Overlapping syncs

• APScheduler's max_instances=1 prevents overlapping runs of the same schedule
• If a sync is still running when the next one is due, the new run waits until the current one finishes (with coalesce=True, backed-up runs collapse into one)

Timezone confusion

• Schedules default to UTC. Check dango schedule status <name> to see the next run in your local time
• Use a valid IANA timezone string (e.g., America/New_York, not EST)

Cron syntax errors

• Cron must be exactly 5 fields separated by spaces
• The wizard validates syntax before saving — if editing schedules.yml manually, run dango config validate to check

Stale "running" status

• If a schedule shows running for more than 24 hours, it was likely killed without cleanup (e.g., kill -9)
• Stale running records are automatically marked as failed during the next cleanup cycle
• Restart dango start to clear the state

Next Steps¶

• Webhook Notifications — get alerts on sync success, failure, or staleness
• Configuring Monitors — set up automated metric tracking after syncs
• Schema Drift — detect source schema changes between syncs
• CLI Schedule Commands — full CLI reference for schedule management