celery-beat

Run the z4j server, z4j-core, z4j-bare and z4j-celerybeat from the same release.

Install and run

pip install z4j-django z4j-celery 'z4j-celerybeat[django]' 'celery[redis]'

Use Celery 5.3+ and django-celery-beat 2.5+. Add django_celery_beat and z4j_django to Django's installed apps, run migrations, and configure the agent credentials in the Beat process as well as the worker. A Celery worker's automatic bootstrap captures tasks; it does not install the Beat scheduler adapter. A Django web process can also host the adapter.

celery -A myproject worker --loglevel=INFO
celery -A myproject beat --scheduler django_celery_beat.schedulers:DatabaseScheduler --loglevel=INFO

Run exactly one Beat scheduler for a given task schedule. z4j does not replace Beat's cadence or prevent duplicate firings from multiple Beat processes.

Supported sources and actions

Source	View	Create/edit/delete	Enable/disable	Run now
django-celery-beat database	Yes	Yes, through a connected adapter that advertises native writes	Yes	With a configured Celery app
`app.conf.beat_schedule`	Yes	Edit application code	Edit application code	With a configured Celery app
PersistentScheduler files or a custom scheduler's private store	Not read directly	No	No	Only entries also exposed in static configuration

Database schedules have an explicit database identity. Static names use a separate identity namespace, so numeric names cannot redirect a command to a different row. A database read failure aborts the whole snapshot and preserves the previously observed inventory.

Native writes and confirmation

The dashboard sends creation, editing and deletion to POST /api/v1/projects/{slug}/schedules/native-operations. Editing and deletion include the control_token from the displayed schedule. The adapter checks the native definition inside a database transaction and refuses stale edits. The response is 202 Accepted with an operation status URL. Success means a subsequent source snapshot has been accepted and agrees with the requested change. A timeout or uncertain outcome requires checking source state before issuing a new operation. Reusing the same request ID returns the same operation.

Enable/disable uses its own confirmed operation status. Native model saves notify a running Beat to reload; disabling also clears Beat's last-run cursor. Hold/release and z4j catch-up policies apply to z4j-owned schedules. They do not control Beat's independent scheduler loop.

Schedule types

Intervals preserve their native precision, including microseconds.
Crontab definitions use exactly five fields and the configured timezone.
Clocked definitions require an ISO timestamp with an offset and are saved as one-off tasks.
Solar schedules are observable. The source adapter requires explicit latitude and longitude for creation; the common dashboard form does not supply those coordinates. Existing solar coordinates are preserved when editing other fields. The adapter never silently substitutes latitude/longitude zero.

Deployment constraints

rq-scheduler and django-celery-beat depend on incompatible Python libraries that both import as crontab. Install those native scheduler integrations in separate environments/processes. They can report to the same z4j server. The repository's native Beat test runs in an isolated environment with scripts/test-native-beat.sh.

Changes made outside the adapter process are picked up by a full resync. Use Sync now when verifying a Django admin change. Reconnect allocates a fresh source epoch; unresolved operations remain explicit rather than being silently repeated. Static definitions remain read-only even when the same adapter also has access to the database.