Database fleets

A database fleet delivers one reviewed release to many already enrolled PostgreSQL and SQLite targets, such as one database per tenant, stage by stage and without a Cloud login. You author the desired Acore state; migration SQL and durable delivery artifacts stay private below .axiom/database/v1/ or in private CI artifacts.

How a fleet release moves

Diagram source

flowchart TD
  A[Private inventory and policy] --> B[fleet prepare]
  B --> C[fleet inspect]
  C --> D[fleet approve: source, security, operations]
  D --> E[fleet verify]
  E --> F[fleet run: dev]
  F --> G[fleet promote: staging]
  G --> H[fleet run: staging]
  H --> I[recovery-check and admit-production]
  I --> J[fleet run: production]
  J --> K[fleet monitor]

1. prepare freezes the inventory, each target's signed history and the policy into one artifact. A changed inventory or budget needs a new freeze and review.
2. inspect shows each target's masked, typed impact. The source owner, security reviewer and operations reviewer each sign the exact artifact with approve.
3. verify checks every review against a policy digest you pin independently, with no database effects.
4. run applies one stage. promote carries the same bytes to the next stage with a fresh signed receipt; it never replans or retargets history.
5. Production also needs a recovery check per member and a one-hour admission.
6. monitor reports fresh drift and history without applying DDL.

Inventory and policy

Both files are private JSON. Unknown fields and untyped URL or SQL templates fail.

IDs use up to 64 letters, digits, _ or -. A tenant appears once per stage. Promoted targets of one engine must share one typed desired-schema intent.

Enroll and plan each target first with the ordinary commands in Database contracts.

Prepare, review and run dev

axiom database fleet prepare --inventory .axiom/database/v1/inventory.json \
  --policy .axiom/database/v1/policy.json --out .axiom/database/v1/fleets/release
axiom database fleet inspect .axiom/database/v1/fleets/release
axiom database fleet approve .axiom/database/v1/fleets/release \
  --reviewer owner --kind source --key-file /private/owner-key.json
axiom database fleet approve .axiom/database/v1/fleets/release \
  --reviewer security --kind security --key-file /private/security-key.json
axiom database fleet approve .axiom/database/v1/fleets/release \
  --reviewer operations --kind operations --key-file /private/operations-key.json
axiom database fleet verify .axiom/database/v1/fleets/release \
  --trusted-policy-sha256 "$REVIEWED_POLICY_SHA256"
axiom database fleet run .axiom/database/v1/fleets/release \
  --inventory .axiom/database/v1/inventory.json \
  --providers /private/providers --journal .axiom/database/v1/fleets/dev-journal \
  --stage dev --receipt-key /private/operations-key.json \
  --trusted-policy-sha256 "$REVIEWED_POLICY_SHA256"

• Set REVIEWED_POLICY_SHA256 to the reviewed canonical policy digest in protected operator or CI configuration. An artifact's own keys and digests are not independent trust.
• Each review binds the exact artifact, typed evidence and an expiry (--ttl-seconds, default 3600, at most 604,800). Renewed reviews append immutable evidence.
• run --stage defaults to dev. The scheduler runs one target at a time, below every instance budget. The fleet has no shared database transaction. A failed canary blocks dependent groups.
• Rerunning verifies each native accepted head again and skips completed work, including a commit whose fleet acknowledgement was lost. A partial fleet exits non-zero and keeps masked per-target outcomes; a partial or non-zero result never means convergence.
• Supported PostgreSQL data transforms keep their signed batch limits and durable per-target cursors. Reports show bounded progress counts and no row values.

Schema-per-tenant releases

axiom database fleet expand database/schema.acore --schema app --tenant tenant1 \
  --sql-name tenant_one --out /private/tenant-one-project

expand changes one parsed literal PostgreSQL schema name, recompiles, keeps logical IDs and records digests. Plan and sign the expanded project before freezing it. It accepts core local PostgreSQL templates; opaque or advanced definitions and imported package templates need explicit authoring. There is no deploy-time SQL substitution. Independent schemas in one physical database use one aggregate contract and revision scope; separate databases are independent fleet targets.

Other fleet commands

No Kubernetes controller, Terraform provider plugin or hosted registry is installed. Discovery is bounded local-file resolution. Arbitrary shell hooks, HTTP or SQL discovery and unbounded data-report scripts are not supported.

Named PostgreSQL production admission

The named profile postgres-17.11-darwin-25.2-arm64-file/v1 is Available for exactly this environment:

Another build, engine patch, operating system or hosted provider needs separate qualification. SQLite keeps its Experimental gate.

Before production:

1. Quiesce the clean enrolled checkpoint and stop application writes.
2. Take and verify an actual physical backup and retain its WAL.
3. Restore to a named point on an isolated server and prove that a later committed transaction is excluded.
4. Keep backup, WAL, restoration, isolation, fencing and recovery-point logs in private operator storage. The provider evidence record binds their digests, the observation time and the measured RPO and RTO. A reversible SQL flag cannot replace a restore.
5. Run recovery-check for every member, then admit-production, then the production run:

axiom database fleet recovery-check /private/fleet/release \
  --member tenant_one --restored-binding /private/tenant-one-restored.json \
  --providers /private/providers --provider-evidence /private/provider-evidence.json \
  --trusted-policy-sha256 "$REVIEWED_POLICY_SHA256" \
  --key-file /private/operations-key.json --out /private/tenant-one-recovery.json
axiom database fleet admit-production /private/fleet/release \
  --recovery /private/tenant-one-recovery.json \
  --trusted-policy-sha256 "$REVIEWED_POLICY_SHA256" \
  --key-file /private/operations-key.json --out /private/production-admission.json
axiom database fleet run /private/fleet/release \
  --inventory /private/inventory.json --providers /private/providers \
  --journal /private/production-journal --stage production \
  --promotion /private/production-promotion.json \
  --production-admission /private/production-admission.json \
  --receipt-key /private/operations-key.json \
  --trusted-policy-sha256 "$REVIEWED_POLICY_SHA256"

Supply one distinct --recovery receipt per production member. The recovery check compares physical identity, ledger incarnation and head, ownership and ordinary managed heap rows with fixed output settings. A same-server alias, mismatched data, a pending checkpoint or an inaccessible row-security subset fails. It does not compare foreign data, sequence counters, materialized results, credentials or provider jobs.

Admission binds the exact artifact, inventory, independently pinned policy, executable and receipts. It cannot override drift, ownership or native pending-state checks.

These are implementation ceilings. The measured two-tenant users and tasks fixture and the retained feature drills do not establish service levels for arbitrary workloads.

Every production connection that executes or verifies status must be a durable TLS primary with data checksums, fsync, full_page_writes, synchronous_commit=on, wal_level=replica and currently successful physical WAL archiving. To recover from a partial run, rerun the exact admitted artifact; it verifies again and skips committed work.

Operator responsibilities

• Own archive retention, backup verification, isolation, fencing and routing.
• During failover, replay the protected LSN and fence the old primary before promotion and routing.
• Rotate credentials by updating PostgreSQL and the private provider file, then verify fresh connections.
• Cloud CI may copy private bytes or orchestrate this exact native runner. Other Cloud runtime or provider profiles are unqualified.

Moving from an experimental PostgreSQL 17.5 installation

Keep the old signed history and backups. Follow PostgreSQL patch, security and reindex guidance, then transfer schema and data to an isolated 17.11 target, excluding the old _axiom_database ledger. Verify data equivalence, adopt the exact schema, enroll new authority, then replay, review, recover and admit. The profile never silently repins or transplants old ledgers.

Backend queries and pools, full rolling application compatibility and complete PostgreSQL and Atlas property coverage keep separate gates.

Next steps

• Review the per-target workflow in Migrations and persistence.
• Check exact limits in Capability boundaries.
• Gate releases in CI checks.