Skip to main content

Running migrations

IdentSphere ships a CLI that owns its schema's migration lifecycle.

Bootstrap​

psql "$DATABASE_URL" -c "CREATE SCHEMA IF NOT EXISTS IdentSphere;"

The SDK lives inside a configurable Postgres schema (default identsphere). The schema is the multi-tenancy seam — sharing public with other applications is unsupported.

Apply migrations​

identsphere migrate up \
  --database-url "$DATABASE_URL" \
  --schema identsphere

Or with cargo run against the source tree:

cargo run -p identsphere-cli -- migrate up \
  --database-url "$DATABASE_URL" \
  --schema identsphere

Migrations are idempotent. Running up on an already-current schema is a no-op.

Other commands​

identsphere migrate status   # show applied / pending migrations
identsphere migrate down --steps 1
identsphere migrate fresh    # ⚠️ drops everything and re-applies — dev only

Naming the schema​

Use a different schema name with the --schema flag (and matching IDENTSPHERE_SCHEMA env var on the running app):

identsphere migrate up --schema myproduct_auth

The CLI sets search_path = <schema>,public on each connection, so it doesn't matter what schema psql defaults to.

Schema isolation​

Every connection acquired by the SDK at runtime does:

SET search_path TO IdentSphere, public

This is the multi-tenant model in production:

  • Each tenant gets a separate Postgres schema.
  • The SDK is configured per-tenant with the right IDENTSPHERE_SCHEMA.
  • Tenants never see each other's data, enforced by Postgres permissions.

CI / CD​

In CI, run identsphere migrate up in your deploy step before the new app process starts. The migration runner takes an advisory lock so concurrent runs from rolling-deploy hosts are safe.

# pseudo-CD
- name: migrate
  run: identsphere migrate up --database-url $DATABASE_URL --schema identsphere
- name: deploy
  run: kubectl rollout restart deployment/auth

Rolling back​

identsphere migrate down --steps 1

Reverts the most recent migration. The down step is generated for every migration; review the SQL before running in production.

See also​