Migrate, check, inspect and activate a Dendrux database with deployment-owned jobs.

Database CLI

The CLI reads DENDRUX_DATABASE_URL. It defaults to sqlite+aiosqlite:///./dendrux.db when the variable is absent. Supply the intended database through your deployment's credential configuration before running a command. There is no database URL flag, and no offline mode: every command works against the live database.

The commands run on PostgreSQL, SQLite, MySQL and MariaDB. The sections below say where the databases differ.

Migrate and activate

On PostgreSQL, dendrux db migrate activates a new database automatically using the same activation path as dendrux db activate. New means no alembic_version table and none of the Dendrux tables before upgrade; unrelated application tables are allowed. Existing databases stay at format 1 until explicit activation, even if there are zero runs or the schema is already at head. An already active database stays active.

If migration succeeds but activation fails or the process stops between them, a rerun treats the schema as existing and leaves it at format 1. Whenever PostgreSQL migration finishes at format 1, the command tells you to run dendrux db activate once every worker and reader is upgraded.

Run migration once per deployment, over a direct database connection (not through a transaction-mode pooler). The 0.6 migration adds storage but leaves a database migrated from 0.5 at format 1. Roll every worker and reader to 0.6 before activation. Take a pre-activation backup. Follow the full upgrade procedure.

dendrux db check
dendrux db status
# Only after all workers and readers are upgraded and the backup is complete:
dendrux db activate --batch-size 5000
dendrux db status

An active database reports storage_format=2 activate_step=done. A database with no activation progress reports activate_step=not-started. db status exits 2 if it cannot read status; it does not repair or migrate anything.

activate and dedupe accept --batch-size from 1 to 5,000 (default 5,000). Progress is recorded so a failed command can resume. Conflicting duplicate contents or an index conflict exit 3; other activation failures exit 1. Resolve the reported condition and rerun. Do not choose or delete conflicting payloads blindly.

Use a direct database connection for activation; on PostgreSQL the concurrent index builds and the maintenance lock require it. For SQLite, stop every other process using the file first. The exclusive lock refuses a live competing transaction, but cannot establish that every idle process has stopped.

Activation reads the whole react_traces, tool_calls and run_events tables, builds three unique indexes concurrently on Postgres and then drops the old indexes. Run it in a quiet period and check free disk for the builds first.

No downgrade command. Once activation starts, rollback requires the pre-activation backup. Even an incomplete activation prevents Alembic downgrade of the 0.6 storage migration.

db dedupe records the same activation-progress marker even though it does not enable format 2. Take the backup before dedupe too; its marker also prevents downgrade of the storage migration.

MySQL and MariaDB

dendrux db migrate on an empty MySQL or MariaDB database builds the current schema in resumable steps, under a named server lock (GET_LOCK), and records it as already active: dendrux db status then prints storage_format=2 activate_step=done. There is no 0.5 schema on these servers, so there is nothing to activate; db activate and db dedupe are for PostgreSQL and SQLite databases migrated from 0.5. An interrupted build shows as bootstrap_in_progress=<step> in db status; run migrate again and it resumes. A database that already holds tables Dendrux does not recognise is refused, and so is one where your application keeps its own alembic_version table. The migration is forward-only: there is no downgrade, so take a backup first. See MySQL and MariaDB.