Existing database

Decide who owns the database schema before you point AxiomCore at it. Adding an API contract does not require moving database ownership to AxiomCore. When you do want AxiomCore to manage some tables, you can enroll (adopt) them, but only when they exactly match an Acore schema you wrote.

Choose the boundary

Diagram source

flowchart TD
  Q1{AxiomCore manages tables?}
  Q1 -->|No| K[Keep your ORM and migrations; extract the API only]
  Q1 -->|Yes| Q2{Exact match with your Acore schema?}
  Q2 -->|Yes| A[Dry run, then enroll with --adopt]
  Q2 -->|No| F[Fix the source or database; never drop data to force a match]

If AxiomCore should manage no tables, keep your ORM and migrations and extract only the API. If it should, enroll only tables that exactly match your Acore schema; otherwise fix the source or the database first.

SQL bootstrap reads an exported DDL file. It does not connect to or manage a live database. Native inspection, adoption, migrations and runtime persistence each carry their own capability limits.

Prepare a disposable target

Work on a copy first. Use a supported PostgreSQL 17 or 18 server or a SQLite file; database contracts lists engine and platform constraints. PostgreSQL needs a reachable server and a matching validator. The CLI does not provision that server.

Before you enroll anything:

1. Take an inventory and a backup with the tools that already own the database.
2. Write the selected tables, keys, relationships, constraints and ownership scope in Acore.
3. Treat anything you did not model as unsafe to change or remove.

Compare before you enroll

Run these from the directory that holds the database manifest. They select an explicit disposable SQLite copy, legacy.sqlite:

axiom check schema.acore
axiom database migrate schema.acore --database-file ./legacy.sqlite --adopt --dry-run

Review the reported differences and capability diagnostics before you allow any change. For PostgreSQL, replace --database-file with --database-url or the connection fields (--host, --port with default 5432, --database, --username, --ssl-mode, --tls-ca); prefer PGPASSWORD or the masked prompt to --password. Always name the target: without an endpoint, the CLI falls back to the DATABASE_URL environment variable.

Enroll an exact match

--adopt enrolls an existing scope only when it exactly matches the validated source. Names, storage types, nullability, keys, collations and the selected physical definition must all match. Adoption records management ownership and migration history. It does not ignore drift and it never overwrites a different schema.

axiom database migrate schema.acore --database-file ./legacy.sqlite --adopt
axiom database status schema.acore --database-file ./legacy.sqlite
axiom database history schema.acore --database-file ./legacy.sqlite

ADB1105 means the comparison failed. Inspect the difference rather than dropping data to get past it:

Production and fleet operations follow the separate fleet workflow, with exact-profile admission and backup and recovery requirements. A local migration does not broaden those qualifications.

Connect the application

Use typed persistence to bind resource operations to the selected tables. Keep application authentication, least-privilege credentials, ownership rules and migration review. If you keep your existing ORM, keep using it behind the extracted backend instead.

Start with a small persisted app before you migrate a larger one. Compare schema and consumer impact together, and test the data-loss limits of rollback on disposable data.

Next steps

• Database contracts
• Migrations and persistence
• Use your existing stack