Skip to main content
crewship db operates on the SQLite database file on this host — DATABASE_URL when set, otherwise <data dir>/crewship.db. Nothing here goes over HTTP, so nothing here can act on a remote instance. Stop crewshipd before commands that write or replace the database. The commands are host-side operations and do not require an API session.

​
--local: which database, and why the CLI asks

If --server, --profile or CREWSHIP_SERVER names a server, every db command refuses to run unless you also pass --local. The refusal names the server, names the file it would otherwise have opened, and names the flag:
A server on localhost is not an exemption. Earlier versions printed a note only for a remote target, on the reasoning that a server on this host must be using this host’s data directory. That is false whenever crewshipd runs with its own DATABASE_URL — every development clone uses file:./crewship.db — and it is how migration-status came to report a completely unrelated schema version under the heading Database: (#2086). Every run prints the path it resolved, whether or not a server was named.

​
crewship db migration-status

Reads the migration ledger in the database file on this host and reports the applied schema version plus outstanding post-deployment migrations. It is read-only and can run while the server is stopped. It honours DATABASE_URL, which it did not before #2086 — pointing it at the file a given crewshipd actually uses is how you ask about that instance.

​
crewship db repair-ledger

Repairs a migration version collision after a migration was renumbered. It moves ledger version numbers only; it does not change table data or schema.
--dry-run is read-only and may be used while the server is running. Applying the repair refuses to proceed while the database is in use — see When the in-use check cannot answer. The command fails closed when the ledger names a migration unknown to the current binary; that case requires a newer binary or a snapshot restore.

​
crewship db restore-snapshot

Restores a pre-migration snapshot created beside the local database. Before an actual restore, the current database is copied to a reversible .before-restore-* file. Stop the server first.
Restoring is the database half of a downgrade: run the matching older binary afterwards. A --server target does not change which file this command operates on — it makes the command refuse until you say --local.

​
When the in-use check cannot answer

Both commands ask the database file itself whether anything is holding it open, rather than probing a port — a server on a non-standard port used to sail straight through. The probe is checked twice: once up front, and again immediately before the write, because the confirmation prompt is unbounded and a supervised crewshipd can come back while you are reading it. There are three outcomes, and --force only lifts one of them: “Cannot tell” is mostly one situation: a database corrupt enough that it cannot answer the probe — file is not a database (26) — which is exactly the state a snapshot restore exists for. Check that no crewshipd is running, then re-run with --force.