Subsystem

subroutine db

The 7 commands under subroutine db, each with its arguments and options.

subroutine db [OPTIONS] COMMAND [ARGS]...

Look after the database.

subroutine db migrate

subroutine db migrate [OPTIONS]

Migrate the database, with none of the ceremony.

No backup, no confirmation and no version report. That is deliberate: this has to work when everything else refuses, which is what makes it the thing to reach for during a recovery and the wrong thing to reach for otherwise.

Use 'subroutine db upgrade' unless you know why you are here. It runs this, after reporting both versions and taking a backup it has verified.

subroutine db copy

subroutine db copy [OPTIONS]

Copy this instance's data into another database — SQLite to PostgreSQL, or back.

Examples:

subroutine db copy --to postgresql+psycopg:///subroutine

A copy, and the original is untouched. Nothing here writes to or deletes the current database: when the new one looks right, point 'database_url' at it. Until then you have two, which is the reassurance somebody changing engines on a Tuesday evening actually wants.

The target must be empty. Merging two instances is not this command, and doing it by accident would leave neither of them right.

Options

subroutine db current

subroutine db current [OPTIONS]

Report which migration the database is at.

subroutine db upgrade

subroutine db upgrade [OPTIONS]

Bring the database up to the schema this version needs, backing it up first.

Examples:

subroutine db upgrade

subroutine db upgrade --check

This does not install anything, and will not try to. Update Subroutine itself with whatever you installed it with — pip, pipx, uv, your package manager, a new container — and then run this to bring the database along.

'--check' asks whether a newer release exists and whether it changes the database schema, which is the part worth knowing in advance: it is the difference between planning a short outage and meeting one halfway through an install. It touches nothing.

Nothing else here ever reaches the network. Subroutine does not check for updates on its own, and there is no setting that makes it — asking is a thing you do, not a thing it does.

Options

subroutine db backup

subroutine db backup [OPTIONS]

Take a datetime-stamped copy of the database.

The copy records the schema it was taken on, so a restore can tell whether this version is able to read it.

Options

subroutine db backups

subroutine db backups [OPTIONS]

List the backups this instance has, newest first.

subroutine db restore

subroutine db restore [OPTIONS] {source}

Put a backup back, replacing this instance's database.

Restoring is two different operations and this will not guess which. --recover is your own data returning: the instance keeps its identity, because agents and configuration files already refer to it. --as-clone is a copy becoming a separate instance: it gets a new identity, because two live instances may not claim the same one.

Stop the service first. Restoring underneath a running one does not reach it: it goes on writing to the file that was replaced, and its next checkpoint can corrupt the restored one. This refuses when it can see another connection, and --force overrides that.

Arguments

Options