Database Schema Lifecycle | Kamiwaza Docs
Version: 1.0.1 (Latest)
Overview
On this page, Kamiwaza v1.0 adds a bounded database schema anchor for PostgreSQL-backed installs. This is a safety foundation for future migrations, not the full migration platform.
The v1.0 contract is:
- Fresh supported installs initialize the database through the normal deployment path.
- The core database is stamped as the supported v1.0 schema floor.
- Startup fails closed if the database advertises an unknown or newer schema version.
- Downgrading a stamped database below v1.0 is not supported.
- Full migration runner behavior is deferred to the v1.1 migration platform.
Supported Initialization Path
For PostgreSQL-backed Kubernetes installs, the supported initialization gate is the core-db-init Helm hook. The hook runs the core image initializer at /app/scripts/db-init.py before scheduler startup.
During v1.0 initialization, the initializer creates or verifies the kamiwaza_schema_version table and records the core schema marker:
| Field | Expected value |
|---|---|
schema_name |
core |
version |
1.0 |
The stamp operation is idempotent. Re-running the supported init path against a database already marked as core=1.0 should leave the marker in place and continue.
Baseline Snapshot
v1.0 also includes a frozen, PostgreSQL-compatible baseline snapshot for the core database schema. The snapshot is the canonical floor that future v1.1 migration tooling can use without reconstructing all pre-v1.0 schema history.
The baseline covers tables owned by the v1.0 core initialization path, including the schema marker table. Lite-mode SQLite metadata is excluded from this PostgreSQL baseline.
Normal post-v1.0 schema changes should not rewrite the accepted v1.0 baseline. Treat changes after the baseline as migration work for the migration platform.
Failure Behavior
Kamiwaza must not blindly run schema initialization against a database owned by a newer or unrecognized binary. If the database contains a kamiwaza_schema_version row for core with a version other than 1.0, v1.0 treats that state as unsupported and fails startup or initialization with an actionable error.
Common meanings:
| Database state | v1.0 behavior |
|---|---|
| No marker on a fresh supported install | Initialize schema and stamp core=1.0 |
Existing core=1.0 marker |
Continue; the marker is known |
Existing core marker with a future or unknown version |
Fail closed; do not run blind initialization |
If a deployment fails because the database is ahead of the running binary, do not downgrade the application onto that database. Restore the matching application version, restore from a compatible backup, or contact Kamiwaza support for the correct recovery path.
Downgrades
Downgrading a database stamped by v1.0 to an application version below v1.0 is unsupported. Pre-v1.0 binaries do not understand the v1.0 schema anchor and should not be used as a rollback target for a stamped PostgreSQL database.
For rollback planning, keep backups aligned with the application release you are rolling back to. A database backup taken after the v1.0 stamp should be restored only with a version that understands that schema state.
What Moves to v1.1
The v1.0 schema anchor is intentionally narrow. These items are not part of the v1.0 database lifecycle contract:
- full Alembic migration runner
- v1.0-to-v1.1 migration scripts
- downgrade or rollback migration tooling
- broad migration rehearsal CI
- operator live-upgrade runbook
- schema status API
- SQLite/lite-mode migration platform coverage
Those items belong to the v1.1 database migration platform.
Operator Checks
After install or upgrade, operators can verify the anchor by inspecting the core PostgreSQL database for the marker row:
SELECT schema_name, version
FROM kamiwaza_schema_version
WHERE schema_name = 'core';
The expected v1.0 result is:
schema_name | version
core | 1.0
If the table or row is missing after a supported PostgreSQL install has completed successfully, collect the core-db-init job logs and contact Kamiwaza support before retrying with ad hoc database changes.