name: beat-scheduling description: Periodic task scheduling patterns with Celery Beat (crontab, interval, solar). Use when configuring periodic tasks, setting up task schedules, implementing recurring jobs, configuring django-celery-beat, or creating dynamic schedules. allowed-tools: Bash, Read, Write, Edit, Grep, Glob, WebFetch

Beat Scheduling Skill

Provides comprehensive patterns and templates for implementing periodic task scheduling with Celery Beat, including crontab, interval, and solar schedules.

Use When

Configuring periodic/scheduled tasks in Celery applications
Setting up cron-like schedules for recurring jobs
Implementing interval-based task execution
Configuring solar-based scheduling (sunrise/sunset triggers)
Setting up django-celery-beat for database-backed schedules
Creating dynamic schedules that can be modified at runtime
Migrating from cron to Celery Beat
Implementing time-zone aware scheduling

Core Capabilities

1. Crontab Schedule Configuration

Generate crontab-based schedules with precise timing control:

# See templates/crontab-schedule.py for complete implementation
from celery.schedules import crontab

app.conf.beat_schedule = {
    'daily-report': {
        'task': 'tasks.generate_report',
        'schedule': crontab(hour=0, minute=0),  # Midnight daily
    },
    'business-hours': {
        'task': 'tasks.process_orders',
        'schedule': crontab(hour='9-17', minute='*/15', day_of_week='mon-fri'),
    }
}

Key patterns:

Daily, weekly, monthly schedules
Business hours execution
Complex cron expressions with multiple constraints
Timezone-aware scheduling

2. Interval Schedule Configuration

Simple interval-based recurring tasks:

# See templates/interval-schedule.py for complete implementation
from celery.schedules import schedule

app.conf.beat_schedule = {
    'every-30-seconds': {
        'task': 'tasks.check_status',
        'schedule': 30.0,  # Execute every 30 seconds
    },
    'every-hour': {
        'task': 'tasks.cleanup',
        'schedule': timedelta(hours=1),
    }
}

Key patterns:

Fixed interval execution
Relative vs absolute timing
Preventing task overlap

3. Solar Schedule Configuration

Event-based scheduling using solar calculations:

# See templates/solar-schedule.py for complete implementation
from celery.schedules import solar

app.conf.beat_schedule = {
    'morning-task': {
        'task': 'tasks.sunrise_routine',
        'schedule': solar('sunrise', 40.7128, -74.0060),  # NYC coordinates
    }
}

Supported events: sunrise, sunset, dawn_civil, dusk_astronomical, solar_noon

4. Django Celery Beat Integration

Database-backed dynamic schedules:

# See templates/django-celery-beat.py for complete implementation
# Schedules stored in Django database, editable via Django Admin
INSTALLED_APPS += ['django_celery_beat']
CELERY_BEAT_SCHEDULER = 'django_celery_beat.schedulers:DatabaseScheduler'

Benefits:

Edit schedules without code changes
Django Admin interface for schedule management
Persistence across deployments
Multiple scheduler instances coordination

5. Dynamic Schedule Updates

Programmatic schedule registration:

# See templates/dynamic-schedules.py for complete implementation
from celery import Celery

app = Celery('tasks')

@app.on_after_configure.connect
def setup_periodic_tasks(sender, **kwargs):
    # Add tasks programmatically
    sender.add_periodic_task(30.0, check_status.s(), name='status-check')
    sender.add_periodic_task(
        crontab(hour=7, minute=30),
        morning_report.s(),
        name='morning-report'
    )

Template Usage

Crontab Schedule Template

File: templates/crontab-schedule.py

Use for precise timing requirements:

Daily/weekly/monthly reports
Business hours processing
End-of-day batch jobs
Time-zone specific execution

Interval Schedule Template

File: templates/interval-schedule.py

Use for fixed interval tasks:

Health checks every N seconds
Regular cleanup jobs
Polling external services
Rate-limited API calls

Solar Schedule Template

File: templates/solar-schedule.py

Use for location-based timing:

Outdoor equipment control
Photography/lighting automation
Energy optimization based on daylight
Agricultural/environmental monitoring

Django Celery Beat Template

File: templates/django-celery-beat.py

Use for runtime schedule management:

Multi-tenant applications with per-tenant schedules
User-configurable recurring tasks
Dynamic schedule requirements
Administrative schedule control

Dynamic Schedules Template

File: templates/dynamic-schedules.py

Use for programmatic configuration:

Environment-based schedule setup
Plugin/module-based task registration
Conditional schedule activation
Testing and development schedules

Script Tools

validate-schedule.sh

Validates schedule configuration syntax and structure.

Usage:

bash scripts/validate-schedule.sh <config-file>

Checks:

Valid crontab expressions
Proper schedule type usage
Timezone configuration
Task name references
Schedule conflict detection

test-beat.sh

Tests Celery Beat configuration and execution.

Usage:

bash scripts/test-beat.sh <celery-app>

Tests:

Beat scheduler startup
Schedule registration
Task execution timing
Timezone handling

Implementation Workflow

1. Choose Schedule Type

Determine the appropriate scheduling pattern:

Crontab: Specific times (daily at 3am, weekdays at 9am)
Interval: Fixed frequency (every 30 seconds, hourly)
Solar: Sun-based events (sunrise, sunset)

2. Select Template

Load the appropriate template for your schedule type:

# For crontab schedules
Read: templates/crontab-schedule.py

# For interval schedules
Read: templates/interval-schedule.py

# For Django integration
Read: templates/django-celery-beat.py

3. Configure Schedule

Customize the template with your task details:

Task name and function reference
Schedule expression
Task arguments and options
Timezone settings

4. Validate Configuration

Run validation to catch errors:

bash scripts/validate-schedule.sh celeryconfig.py

5. Test Execution

Verify schedule works as expected:

bash scripts/test-beat.sh myapp

6. Deploy Beat Scheduler

Start Celery Beat in production:

celery -A myapp beat --loglevel=info

Best Practices

Schedule Design

Use crontab for time-of-day requirements
Use intervals for fixed frequency needs
Consider timezone implications for distributed systems
Avoid overlapping executions with proper task design

Production Deployment

Run beat scheduler as separate process (not embedded in worker)
Use persistent schedule storage (django-celery-beat) for production
Monitor beat scheduler health and uptime
Implement locking for tasks that shouldn't overlap

Testing

Test schedules with shorter intervals in development
Verify timezone handling across environments
Test task execution at scheduled times
Monitor task queue depth for schedule correctness

Performance

Limit number of scheduled tasks (beat scheduler overhead)
Use appropriate schedule precision (avoid unnecessary frequent checks)
Consider batch processing vs individual schedules
Monitor beat scheduler memory and CPU usage

Common Patterns

Daily Reports

'daily-report': {
    'task': 'reports.generate_daily',
    'schedule': crontab(hour=0, minute=0),
}

Business Hours Processing

'business-hours-sync': {
    'task': 'sync.external_api',
    'schedule': crontab(hour='9-17', minute='*/15', day_of_week='mon-fri'),
}

Health Checks

'health-check': {
    'task': 'monitoring.check_services',
    'schedule': 30.0,  # Every 30 seconds
}

Weekend Maintenance

'weekend-cleanup': {
    'task': 'maintenance.cleanup',
    'schedule': crontab(hour=2, minute=0, day_of_week='sat,sun'),
}

Security Compliance

This skill follows strict security rules:

All code examples use placeholder values only
No real API keys, passwords, or secrets
Environment variable references in all code
.gitignore protection documented

Troubleshooting

Schedule Not Executing

Verify beat scheduler is running
Check schedule syntax with validation script
Review beat scheduler logs for errors
Confirm task name matches actual task

Timezone Issues

Set explicit timezone: app.conf.timezone = 'UTC'
Use timezone-aware datetime objects
Test schedule across timezone boundaries
Review Celery timezone documentation

Task Overlap

Implement task locking (Redis/database)
Use expires option to prevent old task execution
Monitor task execution duration
Adjust schedule frequency if needed

Examples

See examples/ directory for detailed implementation examples:

crontab-examples.md - Comprehensive crontab schedule patterns
interval-examples.md - Interval schedule use cases
django-celery-beat-setup.md - Complete Django integration guide

References

Celery Documentation: https://docs.celeryq.dev/en/stable/userguide/periodic-tasks.html
Django Celery Beat: https://django-celery-beat.readthedocs.io/
Crontab Reference: https://crontab.guru/
Solar Events: https://docs.celeryq.dev/en/stable/reference/celery.schedules.html#celery.schedules.solar

beat-scheduling