SQLAlchemy Celery Beat
raw JSON → 0.8.4 verified Sat May 09 auth: no python
A scheduler that stores Celery periodic task schedules in a SQLAlchemy database. Version 0.8.4 is the latest; release cadence is irregular. Provides a database-backed scheduler alternative to Celery's default file-based or Redis scheduler.
pip install sqlalchemy-celery-beat Common errors
error ImportError: cannot import name 'DatabaseScheduler' from 'beat_schedulers' ↓
cause Old import path used. The library moved to `sqlalchemy_celery_beat`.
fix
Use
from sqlalchemy_celery_beat import DatabaseScheduler. error sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) no such table: periodic_task ↓
cause Database tables have not been created. The scheduler expects the tables to exist.
fix
Run
celery beat -S sqlalchemy_celery_beat.DatabaseScheduler --create or manually create tables using from sqlalchemy_celery_beat.models import PeriodicTask; from sqlalchemy import create_engine; engine = create_engine('...'); PeriodicTask.__table__.create(engine). error KeyError: 'sqlalchemy_celery_beat_database_url' ↓
cause The configuration key for the database URL is missing. The scheduler requires this to be set.
fix
Set the database URL in Celery config:
app.conf.sqlalchemy_celery_beat_database_url = 'sqlite:///schedules.db' or via env SQLALCHEMY_CELERY_BEAT_DATABASE_URL. Warnings
breaking In version 0.8.4, `declarative_base` is imported from `sqlalchemy.orm` (not `sqlalchemy.ext.declarative`) to avoid deprecation. If you manually define models that mix with PeriodicTask, ensure you use the same import. ↓
fix Use `from sqlalchemy.orm import declarative_base` instead of `from sqlalchemy.ext.declarative import declarative_base`.
breaking In version >=0.8.0, the `PeriodicTask` model fields changed. After upgrading, you may need to recreate your database tables or run migrations. ↓
fix Check the changelog for field changes. Usually requires dropping and recreating the schedules table, or using Alembic migrations.
deprecated The old import path `from beat_schedulers import DatabaseScheduler` is deprecated. It was removed in version 0.7.0. ↓
fix Use `from sqlalchemy_celery_beat import DatabaseScheduler` instead.
gotcha Do not use `DatabaseScheduler` as the default scheduler in Celery config if you also run `celery beat` without the `-S` flag. The scheduler must be specified at runtime or in config. ↓
fix Set `beat_scheduler` in your Celery config: `app.conf.beat_scheduler = 'sqlalchemy_celery_beat.DatabaseScheduler'` or pass `-S` on the command line.
gotcha The scheduler uses a dedicated database session. Ensure you configure the database URL properly via the `sqlalchemy_celery_beat` database URL setting (defaults to `sqlite:///celerybeatschedule.db`). ↓
fix Set `SQLALCHEMY_CELERY_BEAT_DATABASE_URL` environment variable or configure via `app.conf.sqlalchemy_celery_beat_database_url`.
Imports
- DatabaseScheduler
from sqlalchemy_celery_beat import DatabaseScheduler - PeriodicTask
from sqlalchemy_celery_beat.models import PeriodicTask - CrontabSchedule
from sqlalchemy_celery_beat.models import CrontabSchedule - IntervalSchedule
from sqlalchemy_celery_beat.models import IntervalSchedule - ClockedSchedule
from sqlalchemy_celery_beat.models import ClockedSchedule
Quickstart
import os
from celery import Celery
from sqlalchemy_celery_beat import DatabaseScheduler
from sqlalchemy_celery_beat.models import PeriodicTask, CrontabSchedule
app = Celery('myapp')
app.config_from_object('celeryconfig')
# Start the beat worker with DatabaseScheduler
# Run: celery -A myapp beat -S sqlalchemy_celery_beat.DatabaseScheduler -l info