Aegis documentation

#db — SQLite databases, migrations and seeders

aegis db manages the platform's own SQLite files under database/. It is not a client for the PostgreSQL or MariaDB servers: those are configured through their cubes, while this command creates, inspects, migrates and seeds the small databases used by the panel, the tasker, account, mail, web and the other core modules.

One database lives in its own directory, so the file, its write-ahead log and its shared-memory file stay together:

text
database/storage/<name>/<name>.dbdatabase/migrations/core/<name>/*.sql      # core module migrationsdatabase/migrations/<name>/*.sql           # migrations of an operator databasedatabase/seeders/<name>/*.sql              # seeders, always here

A file written by an older layout (a flat storage/<name>.db or storage/<name>/<name>.sqlite) is moved into the current layout the first time the database is opened. The move happens in code, so no manual step is needed.

Database names must match [a-z][a-z0-9_-]*. Migration and seeder names must match [a-z][a-z0-9_]* (no hyphen).

Output is human-formatted throughout: these commands print their own lines and tables and never consult the global --json flag. Exit codes follow Conventions: 0 success, 1 failure, 2 usage, 130 Ctrl+C.

#Inspecting databases

#aegis db list

Lists every database found under database/storage, one name per line.

bash
aegis db list
Argument / optionDefaultMeaning
——no arguments or options

The names come from the disk, including databases that still use an older layout and have not been opened yet.

Examples:

bash
aegis db listaegis db list | wc -l
text
accountaegisdnsmailtaskerweb

No databases yet:

text
ℹ no databases

#aegis db info

Shows the file path, size, tables and migration counts of one database.

info is the single-database view; this group has no separate show verb.

bash
aegis db info NAME
ArgumentDefaultMeaning
NAMErequireddatabase name

The table list excludes SQLite internal tables. applied and pending are counts; applied counts rows in schema_migrations, and pending counts migration files that are not recorded there.

Examples:

bash
aegis db info accountaegis db info web
text
name:    accountpath:    /etc/aegis/database/storage/account/account.dbsize:    384.0 KiBtables:  9  - account_databases  - account_domains  - account_events  - account_ftp_accounts  - account_purged  - account_sites  - account_ssh_keys  - accounts  - schema_migrationsapplied: 2pending: 0

An unknown database exits 1:

text
✖ database 'website' does not exist

#aegis db status

Shows the migration state of one database and names every pending migration.

bash
aegis db status NAME
ArgumentDefaultMeaning
NAMErequireddatabase name

Examples:

bash
aegis db status webaegis db status aegis
text
database: webapplied:  7pending:  1  - 20261117_104512_add_php_version.sql

Up to date:

text
database: webapplied:  8pending:  0

#Creating and destroying databases

#aegis db create

Creates an empty SQLite database and its directory. No schema and no seeder is applied.

bash
aegis db create NAME
ArgumentDefaultMeaning
NAMErequireddatabase name

Examples:

bash
aegis db create blogaegis db create analytics
text
✔ database 'blog' created  /etc/aegis/database/storage/blog/blog.db

A name that already exists, in any layout, is refused:

text
✖ database 'blog' already exists

#aegis db drop

Destructive. Deletes the database file and its -wal and -shm companions. The data cannot be recovered from the command line.

Refuses to run without --force.

bash
aegis db drop NAME --force
Argument / optionDefaultMeaning
NAMErequireddatabase name
--forceoffrequired confirmation; without it nothing is deleted

The per-database directory is removed only when it becomes empty; anything else placed there by an operator is left alone.

Examples:

bash
aegis db drop blogaegis db drop blog --force

Without the flag:

text
✖ refusing to drop without --force

With it:

text
✔ database 'blog' dropped  /etc/aegis/database/storage/blog/blog.db

#aegis db fresh

Destructive. Drops the database, creates it again, applies every migration and runs every seeder. All existing data is lost.

Refuses to run without --force.

bash
aegis db fresh NAME --force
Argument / optionDefaultMeaning
NAMErequireddatabase name
--forceoffrequired confirmation; without it nothing is changed

This is the shortest way to get a known-good development database. It is not a repair command: the database is recreated from the migration files, not from a backup.

Examples:

bash
aegis db fresh web --forceaegis db fresh blog --force

Without the flag:

text
✖ refusing to recreate without --force

With it:

text
✔ database 'web' recreatedℹ 8 migration(s) appliedℹ 1 seeder(s) executed

#Migrations

#aegis db migrate

Applies every pending migration to one database, in filename order.

bash
aegis db migrate NAME
ArgumentDefaultMeaning
NAMErequireddatabase name

The command reads database/migrations/core/<name> when that directory exists and falls back to database/migrations/<name> otherwise. The core directory wins when both exist, so aegis db migrate web reads the same files the web module's own setup uses.

A database whose file does not exist yet is an error; create it with aegis db create or aegis db fresh first.

Examples:

bash
aegis db migrate webaegis db migrate aegis
text
✔ 1 migration(s) applied  20261117_104512_add_php_version.sql

Nothing pending:

text
ℹ no pending migrations

A failing script aborts the file and leaves it unrecorded:

text
✖ near "CRATE": syntax error

#aegis db rollback

Destructive. Reverts applied migrations by running their paired *.down.sql files, which usually drop tables or columns. The data those objects held is lost.

Reverts the most recently applied migrations, one step by default.

bash
aegis db rollback NAME --step N
Argument / optionDefaultMeaning
NAMErequireddatabase name
--step1how many migrations to revert; must be at least 1

Only migrations that are recorded in schema_migrations and have a paired <migration>.down.sql can be rolled back. A missing rollback file stops the operation; migrations already reverted in the same call stay reverted.

The core migrations under database/migrations/core ship without .down.sql files, so rolling one of those back stops with the message below. A migration created by db make:migration has its rollback file from the start.

Examples:

bash
aegis db rollback web
text
✔ 1 migration(s) rolled back  20261117_104512_add_php_version.sql

Two steps:

bash
aegis db rollback web --step 2
text
✔ 2 migration(s) rolled back  20261117_103000_add_vhost_tls.sql, 20261117_104512_add_php_version.sql

Nothing to revert:

text
ℹ nothing to roll back

A missing down file:

text
✖ cannot roll back 0007_account.sql: 0007_account.down.sql is missing

#aegis db make:migration

Creates an empty migration and its rollback counterpart, both timestamped so the order stays stable and two calls cannot overwrite each other.

bash
aegis db make:migration DATABASE NAME
ArgumentDefaultMeaning
DATABASErequireddatabase the migration belongs to
NAMErequiredfile-name suffix, [a-z][a-z0-9_]*

The files are written into database/migrations/core/<database> when that directory exists, otherwise into database/migrations/<database>. The names are <YYYYMMDD_HHMMSS>_<name>.sql and <YYYYMMDD_HHMMSS>_<name>.down.sql, with the timestamp in UTC. The generated headers document the database, the creation time and the rules for that file type.

Examples:

bash
aegis db make:migration web add_php_versionaegis db make:migration blog add_posts
text
✔ migration created  /etc/aegis/database/migrations/core/web/20261117_104512_add_php_version.sql✔ rollback created  /etc/aegis/database/migrations/core/web/20261117_104512_add_php_version.down.sql

A bad name or an existing file exits 1:

text
✖ invalid name 'Add-Posts': expected [a-z][a-z0-9_]*✖ file already exists: /etc/aegis/database/migrations/core/web/20261117_104512_add_php_version.sql

#Seeders

#aegis db seed

Runs every .sql file in database/seeders/<name>, in filename order.

bash
aegis db seed NAME
ArgumentDefaultMeaning
NAMErequireddatabase name

Seeders are not tracked. Every run executes every file, so a seeder must be idempotent: use INSERT OR IGNORE, an upsert, or a guarded insert. There is no schema_migrations row for a seeder and no rollback file.

Examples:

bash
aegis db seed webaegis db seed blog
text
✔ 2 seeder(s) executed  20260101_000000_roles.sql, 20260101_000010_settings.sql

An empty seeder directory:

text
ℹ no seeders found

#aegis db make:seeder

Creates an empty seeder file.

bash
aegis db make:seeder DATABASE NAME
ArgumentDefaultMeaning
DATABASErequireddatabase the seeder belongs to
NAMErequiredfile-name suffix, [a-z][a-z0-9_]*

The file is written to database/seeders/<database>/<YYYYMMDD_HHMMSS>_<name>.sql. Its header repeats that seeders are untracked and may run more than once.

Examples:

bash
aegis db make:seeder web default_settingsaegis db make:seeder blog demo_posts
text
✔ seeder created  /etc/aegis/database/seeders/web/20261117_104530_default_settings.sql

A bad name or an existing file exits 1:

text
✖ invalid name 'Default Settings': expected [a-z][a-z0-9_]*

#How migrations run

  • Files are sorted by filename, so the timestamp prefix is the order. Files
  • ending in .down.sql are rollback counterparts and are not applied by migrate.

  • Each file runs once and is recorded in schema_migrations with its name and
  • an ISO timestamp.

  • The file and its schema_migrations row are wrapped in an explicit
  • BEGIN IMMEDIATE … COMMIT. A failure rolls the whole file back and leaves it unrecorded, so it can be fixed and run again. Migration files must not open a transaction themselves.

  • SQLite has no ADD COLUMN IF NOT EXISTS or DROP COLUMN IF EXISTS. Before a
  • file runs, one-line ALTER TABLE <table> ADD|DROP COLUMN <column> statements are checked against pragma_table_info; a statement that already took effect is skipped. That is what makes a half-applied file re-runnable.

  • rollback reads the applied names, takes the last --step of them in
  • reverse order, runs the paired down file, then deletes the recorded row. It commits after each migration, so a missing down file leaves the earlier reverts in place.

  • Seeders are plain scripts: no transaction wrapper beyond what the script
  • does, no record of having run, and no rollback.

    #Files

    PathContent
    database/storage/<name>/<name>.dbthe SQLite database
    database/storage/<name>/<name>.db-walwrite-ahead log, when present
    database/storage/<name>/<name>.db-shmshared-memory file, when present
    database/migrations/core/<name>/*.sqlmigrations of a core module
    database/migrations/<name>/*.sqlmigrations of an operator database
    database/seeders/<name>/*.sqlseeders, run on every db seed
    schema_migrationsone row per applied migration

    The core directory is checked first on every read, which is why moving a module's migrations under database/migrations/core/<name> makes them visible to aegis db migrate without any registration step.