Schema Migrations

Sovrium evolves your database schema automatically. It diffs the application configuration against the physical database, generates the appropriate SQL, and executes it inside a transaction — no hand-written migration files. The system validates checksums to detect drift, supports rollback to recover from failures, and records a complete audit trail of every change.

Schema evolution runs at boot: when the configuration on disk differs from the database, Sovrium generates and applies the necessary SQL inside a transaction, then records the new schema version. Configuration is code-only, so you evolve the schema by editing your app.ts / app.yaml and restarting (or re-deploying). There is no runtime schema-editing API, and sovrium reload refreshes a running server's config identity without applying schema changes — a schema change takes effect on the next start.

Automatic Schema Evolution

When the configuration differs from the database, Sovrium detects the change and applies the migration automatically — all within a transaction so a partial failure rolls back cleanly.

Supported structural changes:

# Before
tables:
  - id: 1
    name: users
    fields:
      - { id: 1, name: email, type: email }

# After — add a phone field; Sovrium generates ADD COLUMN
tables:
  - id: 1
    name: users
    fields:
      - { id: 1, name: email, type: email }
      - { id: 2, name: phone, type: single-line-text }

Field IDs are the rename anchor — keep the id stable and change the name to rename a column without losing data. See Table Indexes & Constraints and Validation for the per-field properties migrations track.

Checksum Validation

Sovrium fingerprints the schema to skip unnecessary migration work and detect drift.

1. On the first migration, Sovrium computes a SHA-256 checksum of the schema and stores it.
2. On each subsequent startup it compares the current schema's checksum against the stored one.
3. Unchanged → the server starts quickly, running no migrations.
4. Changed → Sovrium executes the necessary migrations and saves the new checksum.

This makes restarts cheap when nothing changed and guarantees the database matches the declared schema when something did.

Applying a schema change

To change your schema, edit the config file and restart the server (or re-deploy). On the next boot Sovrium diffs the new configuration against the database and applies the migration in a transaction before the app starts serving traffic, so a newly declared table or column exists by the time its /api/tables/:slug/records routes are registered — routes never point at a table that does not yet exist. If the migration fails, the transaction rolls back and the server refuses to start on an inconsistent schema, rather than serving a half-migrated database.

Rollback

When a migration fails, the transaction rolls back and the schema is left in its prior consistent state. Rollback is currently available programmatically; dedicated CLI rollback commands (migrate:rollback, --to <version>, --force) are planned. The migration history records every applied schema version, so a prior version snapshot can be re-applied.

Audit Trail

The migration system records, for each migration:

• Migration timestamp
• Schema version number
• Schema checksum (SHA-256)
• Complete schema snapshot
• Rollback operations and reason

This audit trail is the source of truth for "which schema produced this database" — auditors cross-reference it against the activity log to correlate data changes with the schema version in force at the time.

Error Handling

Migrations fail loud and safe. Each of these scenarios aborts before or during execution and rolls back any partial work:

Related Pages

• Database Infrastructure — the SQLite/PostgreSQL engines migrations target.
• Table Indexes & Constraints — the index and constraint definitions migrations apply.
• Validation — field- and table-level rules tracked across evolution.
• Activity Monitoring — the audit stream correlated against schema versions.
• Admin Dashboard — config/version reports the active runtime and build.