Skip to content
z4j docs

Database migrations

Auto-migration on boot

Section titled “Auto-migration on boot”

By default, the brain runs pending migrations on start. This is idempotent and safe to leave on.

Disable with Z4J_AUTOMIGRATE=false - then run migrations manually.

Manual migration

Section titled “Manual migration”
Terminal window
docker run --rm \
  -e Z4J_DATABASE_URL=... \
  z4jdev/z4j:v1.0.0 z4j-brain migrate

Or inside an existing container:

Terminal window
docker exec -it z4j-brain z4j-brain migrate

Status

Section titled “Status”
Terminal window
z4j-brain migrate --status

Lists applied / pending revisions.

Forward-only policy

Section titled “Forward-only policy”

Migrations are forward-only. We don’t ship downgrade scripts. If you need to roll back, restore Postgres from backup.

Multi-replica (v1.1+)

Section titled “Multi-replica (v1.1+)”

For N-replica deploys, run migrations from a one-shot job before rolling out the new brain image:

# kubernetes example
apiVersion: batch/v1
kind: Job
metadata:
  name: z4j-migrate-v1-1-0
spec:
  template:
    spec:
      containers:
        - name: migrate
          image: z4jdev/z4j:v1.1.0
          command: ["z4j-brain", "migrate"]
          env: [...]
      restartPolicy: Never

Then update the Deployment’s image.

Schema reference

Section titled “Schema reference”

See database schema for the authoritative table + column list.

Underlying tool

Section titled “Underlying tool”

Alembic (SQLAlchemy 2.0). Revisions live in packages/z4j-brain/backend/alembic/versions/. Each revision includes a descriptive message and never loses data without explicit, commented-out intent.