Subsystem Search

subroutine db

The 8 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 unless you tell it to: this command's '--check', or 'check = true' under '\[releases]' in a served instance's configuration, which then asks once a day while somebody signed in is using it. With neither, it makes no outbound request at all.

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 archive

subroutine db archive [OPTIONS]

Move events older than events_retention_days out of the change feed, into the archive.

Nothing is deleted. The journal, each item's history and an export still read the events that move; a client resuming the change feed from before them is told the last event that moved, and carries on after it. Only a run of old events moves, so an old one numbered after a newer one waits for it, and the newest event always stays. A served instance does this itself once a day while it is in use, so this is for one that is not served, or for a timer.

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