CLI

[ AxiomCore · Documentation ]

axiom database

Reference for every axiom database subcommand that checks, builds, migrates, rolls back and inspects versioned PostgreSQL and SQLite contracts.

axiom database checks and builds database contracts offline, then applies them to a PostgreSQL or SQLite target as immutable, versioned migrations. This page covers all 9 subcommands and the 5 history subcommands in Axiom CLI 0.149.1.

Offline checks first, then versioned changes against a target
Offline checks first, then versioned changes against a target
Diagram source
flowchart LR
  S[database source] --> C[database check]
  C --> B[database build]
  C --> D[database diff]
  C --> M[database migrate]
  M --> T[(PostgreSQL or SQLite)]
  T --> ST[database status]
  T --> H[database history]
  T --> R[database rollback]
  R --> T

check, fmt, build, inspect and diff never connect to a database. migrate validates each pending version and then applies it to the target. status and history read the target, and rollback publishes a new compensating version. axiom run on a database source runs the same migration and then opens a SQL console.

None of these commands need Cloud login. Commands that connect need a reachable PostgreSQL server or a local SQLite file.

axiom database

Run and migrate versioned PostgreSQL and SQLite database contracts.

Usage
axiom database <COMMAND>
SubcommandPurpose
checkCheck a source entry and its imports without database I/O.
fmtFormat database source.
buildBuild a canonical server-only schema package.
inspectInspect a source or schema package without connecting.
diffCompare two contracts, or two catalog versions.
migrateApply pending versioned migrations.
statusShow applied version, pending changes and drift.
rollbackRestore a recorded schema through a new compensating version.
historyShow version history and failed attempts.

The CONTRACT argument of migrate, rollback, status and history accepts an .acore source, a release bundle written by --export, or a schema package from database build together with its .sources.axiom companion. The project root is the nearest directory with an AxiomDeps.toml that declares type = "database". Generated state, the local version catalog and the default SQLite file live under that root's .axiom/ directory.

Connection options

migrate, rollback, status, history and axiom run share these options.

OptionValueDefaultMeaning
--database-urlURLDATABASE_URLPostgreSQL (postgres:// or postgresql://) or SQLite (sqlite:) URL. DATABASE_URL is read only when no endpoint field or --database-file is given.
--hosthostlocalhostPostgreSQL host.
-p, --portnumber5432PostgreSQL port.
--databasenamePGDATABASEPostgreSQL database name. Required when you use fields instead of a URL.
--usernamenamePGUSER, then USERPostgreSQL user.
--passwordtextPGPASSWORDPostgreSQL password. Prefer PGPASSWORD or the masked interactive prompt, so the value stays out of shell history.
--database-filepath.axiom/database/data/database.sqliteSQLite file. Conflicts with --database-url.
--ssl-modedisable, prefer, require, verify-fullnonePostgreSQL TLS mode.
--tls-capathnoneCA certificate used to verify the PostgreSQL server.

Rules the CLI enforces (error ADB1107):

  • Give a URL or individual endpoint fields, not both.
  • SQLite takes --database-file or a sqlite: URL that names a local file. :memory: and URL query options are rejected, and PostgreSQL fields are rejected.
  • PostgreSQL contracts cannot use --database-file.

If DATABASE_URL is set in your shell for another project, unset it before you run a SQLite contract, or pass --database-file.

Migration policy options

migrate and rollback share these options. In CI, add --non-interactive.

OptionValueDefaultMeaning
--auto-versionflagoffAccept the suggested next version when the source version is already used. The CLI updates project(version: ...) in your source.
--non-interactiveflagoffNever prompt. A prompt that would be needed becomes an error naming the flag to add. Prompts are also skipped without a terminal or when CI is set.
--dry-runflagoffPreview the change without applying it. A missing SQLite file is not created.
--allow-destructiveflagoffAuthorize a change that may delete data or remove invariants. A schema rollback does not restore lost values.
--allow-data-dependentflagoffAuthorize a change that depends on existing data or rebuilds invariants.
--allow-security-changesflagoffAuthorize a change to database permissions or security policy.
--adoptflagoffEnroll an existing scope only when it exactly matches the validated source.
--jsonflagoffPrint machine-readable results to stdout.
--exportpathnoneAfter the run, write the target's complete applied history as one bundle, so CI can promote the same bytes later with --frozen.

Without the matching --allow-* flag, a risky change asks for confirmation in a terminal and fails with ADB1111 in non-interactive mode.

Author and build offline

axiom database check

Check a database source entry and its imports without any database I/O. Use it first, in editors and in CI.

Usage
axiom database check <SOURCE>
OptionValueDefaultMeaning
<SOURCE>pathrequiredDatabase .acore entry file.

On success it prints an axiom-database-evidence/v1 JSON report with the compiled nodes, edges, exported tables and source hashes.

Terminal
axiom database check database/sqlite/schema.acore

axiom database fmt

Format database source. It prints the result to stdout unless you pass --write.

Usage
axiom database fmt [OPTIONS] <SOURCE>
OptionValueDefaultMeaning
<SOURCE>pathrequiredDatabase .acore file.
--writeflagoffReplace the file with the formatted source.

axiom database build

Build a canonical server-only schema package. The build is offline and grants no migration authority.

Usage
axiom database build [OPTIONS] <SOURCE>
OptionValueDefaultMeaning
<SOURCE>pathrequiredDatabase .acore entry file.
--outpath.axiom/contracts/database.axiom under the project rootOutput schema package.

The command also writes a .sources.axiom source companion beside the package and prints an axiom-database-build/v1 summary with the artifact path and SHA-256. Keep the companion with the package: migrate and inspect need it to read a package.

Terminal
axiom database build database/sqlite/schema.acore

axiom database inspect

Inspect a source contract or a built schema package without connecting. It prints JSON describing the engine, exported tables and columns.

Usage
axiom database inspect <SOURCE>
OptionValueDefaultMeaning
<SOURCE>pathrequiredDatabase .acore source or schema package.

axiom database diff

Compare two database contracts, or two versions in the local catalog. Use it to review a schema change before you migrate.

Usage
axiom database diff [OPTIONS] <CONTRACT> [AFTER]
OptionValueDefaultMeaning
<CONTRACT>pathrequiredThe "before" source or schema package. With --from, the contract whose catalog you compare.
[AFTER]pathnoneThe "after" source or schema package. When present, --from, --to and --json are ignored and the output is JSON.
--fromversionrequired without AFTERArchived catalog version to compare from.
--toversion or workingworkingVersion to compare to. working is the current source.
--jsonflagoffPrint the catalog comparison as JSON.

The two-file form prints an axiom-database-contract-change/v1 report. Each change lists the object path, operation and a compatibility class such as requires-transition-validation.

Terminal
axiom database diff before/schema.acore after/schema.acore
axiom database diff database/schema.acore --from 1.0.0 --to working

Apply and observe versions

axiom database migrate

Apply pending versioned migrations to a target. Each pending version is validated before it is applied, and drift blocks the run (ADB1105).

Usage
axiom database migrate [OPTIONS] <CONTRACT>
OptionValueDefaultMeaning
<CONTRACT>pathrequiredSource, exported release bundle or schema package.
Connection optionssee Connection options--database-url, --host, -p, --port, --database, --username, --password, --database-file, --ssl-mode, --tls-ca.
Policy optionssee Migration policy options--auto-version, --non-interactive, --dry-run, --allow-destructive, --allow-data-dependent, --allow-security-changes, --adopt, --json, --export.
--frozenflagoffApply only an existing immutable release, for example one written by --export. Never prepare a new version.
--toversionlatestStop at a retained forward version. Use rollback to go back.

If the source version was already published with different content, the CLI suggests the next version. It prompts in a terminal, uses it with --auto-version, and otherwise fails with ADB1103. When the environment variable AXIOM_DATABASE_TRUSTED_KEY is set, the release signer must match it (ADB1109).

Terminal
axiom database migrate database/schema.acore --database-url "$DATABASE_URL"
axiom database migrate database/schema.acore --database-file ./tasks.sqlite --dry-run

Prepare a release once and promote the same bytes in CI:

Terminal
axiom database migrate database/schema.acore --database-url "$STAGING_URL" \
  --non-interactive --auto-version --export release.axiom
axiom database migrate release.axiom --database-url "$PRODUCTION_URL" \
  --non-interactive --frozen

axiom database status

Show the applied version, the working version, pending changes and drift without migrating.

Usage
axiom database status [OPTIONS] <CONTRACT>
OptionValueDefaultMeaning
<CONTRACT>pathrequiredSource, release bundle or schema package.
Connection optionssee Connection optionsSelect the target.
--jsonflagoffPrint the status as JSON.
--watchflagoffRefresh every 2 seconds until you press Ctrl+C.
--checkflagoffExit non-zero (ADB1105, "database is not current") when a change is pending or drift exists. Use it as a CI gate.

If the working source is invalid, status reports the last archived definition and marks the working version invalid.

Terminal
axiom database status database/schema.acore --database-url "$DATABASE_URL" --check

axiom database rollback

Restore an earlier recorded schema by publishing a new compensating version. History is never rewritten.

Usage
axiom database rollback [OPTIONS] <CONTRACT>
OptionValueDefaultMeaning
<CONTRACT>pathrequiredSource, release bundle or schema package.
Connection optionssee Connection optionsSelect the target.
Policy optionssee Migration policy optionsThe rollback is a new version: use --auto-version in CI.
--stepsnumber1Number of applied versions to step back, from 1 to the number applied. Conflicts with --to.
--toversion or emptynoneRestore a retained version. empty restores the empty baseline.

Rollback refuses a target with drift (ADB1105). It also refuses to cross a data overwrite whose previous values were not archived (ADB1113): write an explicit compensating migration or restore a backup instead.

Terminal
axiom database rollback database/schema.acore --database-url "$DATABASE_URL" --steps 1
axiom database rollback database/schema.acore --database-url "$DATABASE_URL" --to empty

axiom database history

Show version history, compensating rollbacks and failed attempts. It can also recover missing local definitions from the target's verified ledger.

Usage
axiom database history [OPTIONS] [SOURCE] [COMMAND]
OptionValueDefaultMeaning
[SOURCE]pathnoneSource, release bundle or schema package.
Connection optionssee Connection optionsSelect the target.
--jsonflagoffPrint the history as JSON.
--watchflagoffRefresh every 2 seconds until you press Ctrl+C.

Each line shows a version, its kind (migration, rollback or adoption), its changes and, for a rollback, the version it restores.

Terminal
axiom database history database/schema.acore --database-url "$DATABASE_URL"

Advanced history subcommands

axiom database history export

Export the complete verified history prefix into a new private offline directory.

Usage
axiom database history export [OPTIONS] --out <OUT> <SOURCE>
OptionValueDefaultMeaning
<SOURCE>pathrequiredDatabase source.
--headcandidate IDlocal history headLast candidate to include.
--outpathrequiredNew output directory.

axiom database history checkpoint

Export a complete-prefix checkpoint that also carries deployed data lineage.

Usage
axiom database history checkpoint [OPTIONS] --out <OUT> <SOURCE>
OptionValueDefaultMeaning
<SOURCE>pathrequiredDatabase source.
--headcandidate IDlocal history headLast candidate to include.
--outpathrequiredNew output directory.

axiom database history verify

Verify an exported bundle offline. Verification does not connect to a database and does not grant authority to apply.

Usage
axiom database history verify <BUNDLE>
OptionValueDefaultMeaning
<BUNDLE>pathrequiredDirectory written by history export or history checkpoint.

axiom database history import

Import exact generated history for the matching compiled project.

Usage
axiom database history import --source <SOURCE> <BUNDLE>
OptionValueDefaultMeaning
<BUNDLE>pathrequiredExported history bundle.
--sourcepathrequiredDatabase source whose compiled package must match the bundle.

axiom database history import-atlas

Adopt a verified Atlas migration directory and revision snapshot as private provenance, when you move an existing Atlas-managed database to Acore.

Usage
axiom database history import-atlas [OPTIONS] --directory <DIRECTORY> --deployment <DEPLOYMENT> --revision-schema <REVISION_SCHEMA> --legacy-stopped <BUNDLE>
OptionValueDefaultMeaning
<BUNDLE>pathrequiredHistory bundle that receives the provenance.
--directorypathrequiredAtlas migration directory.
--deploymentpathrequiredPrivate target binding used to read the Atlas revision table.
--revision-schemanamerequiredSchema that holds the Atlas revision table.
--revision-tablenameatlas_schema_revisionsAtlas revision table name.
--legacy-stoppedflagrequiredConfirms that the legacy Atlas deployment is stopped.

Hidden operator commands

axiom database also accepts subcommands that --help does not list. They are retained for certified and operator profiles and are outside this reference. One example is axiom database fleet, the Experimental frozen fleet delivery workflow: prepare, inspect, approve, verify, export, expand, run, monitor, promote, dashboard, terraform-plan, recovery-check and admit-production. ci, operator and terraform-apply are aliases of run. Verification, execution and promotion require --trusted-policy-sha256. Live operations require an explicit inventory, a private provider root, a journal and a receipt key. See Database fleets.

axiom server

Reference for every axiom server subcommand that scaffolds, validates, runs, packages and verifies a compiled backend contract and its private server plan.

axiom ui

Reference for the axiom ui commands that install target hosts and check, inspect, test and build Acore UI applications.

On this page

axiom databaseConnection optionsMigration policy optionsAuthor and build offlineaxiom database checkaxiom database fmtaxiom database buildaxiom database inspectaxiom database diffApply and observe versionsaxiom database migrateaxiom database statusaxiom database rollbackaxiom database historyAdvanced history subcommandsaxiom database history exportaxiom database history checkpointaxiom database history verifyaxiom database history importaxiom database history import-atlasHidden operator commands