#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:
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 hereA 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.
aegis db list| Argument / option | Default | Meaning |
|---|---|---|
| — | — | 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:
aegis db listaegis db list | wc -laccountaegisdnsmailtaskerwebNo databases yet:
ℹ 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.
aegis db info NAME| Argument | Default | Meaning |
|---|---|---|
NAME | required | database 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:
aegis db info accountaegis db info webname: 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: 0An unknown database exits 1:
✖ database 'website' does not exist#aegis db status
Shows the migration state of one database and names every pending migration.
aegis db status NAME| Argument | Default | Meaning |
|---|---|---|
NAME | required | database name |
Examples:
aegis db status webaegis db status aegisdatabase: webapplied: 7pending: 1 - 20261117_104512_add_php_version.sqlUp to date:
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.
aegis db create NAME| Argument | Default | Meaning |
|---|---|---|
NAME | required | database name |
Examples:
aegis db create blogaegis db create analytics✔ database 'blog' created /etc/aegis/database/storage/blog/blog.dbA name that already exists, in any layout, is refused:
✖ database 'blog' already exists#aegis db drop
Destructive. Deletes the database file and its
-waland-shmcompanions. The data cannot be recovered from the command line.
Refuses to run without --force.
aegis db drop NAME --force| Argument / option | Default | Meaning |
|---|---|---|
NAME | required | database name |
--force | off | required 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:
aegis db drop blogaegis db drop blog --forceWithout the flag:
✖ refusing to drop without --forceWith it:
✔ 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.
aegis db fresh NAME --force| Argument / option | Default | Meaning |
|---|---|---|
NAME | required | database name |
--force | off | required 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:
aegis db fresh web --forceaegis db fresh blog --forceWithout the flag:
✖ refusing to recreate without --forceWith it:
✔ 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.
aegis db migrate NAME| Argument | Default | Meaning |
|---|---|---|
NAME | required | database 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:
aegis db migrate webaegis db migrate aegis✔ 1 migration(s) applied 20261117_104512_add_php_version.sqlNothing pending:
ℹ no pending migrationsA failing script aborts the file and leaves it unrecorded:
✖ near "CRATE": syntax error#aegis db rollback
Destructive. Reverts applied migrations by running their paired
*.down.sqlfiles, which usually drop tables or columns. The data those objects held is lost.
Reverts the most recently applied migrations, one step by default.
aegis db rollback NAME --step N| Argument / option | Default | Meaning |
|---|---|---|
NAME | required | database name |
--step | 1 | how 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:
aegis db rollback web✔ 1 migration(s) rolled back 20261117_104512_add_php_version.sqlTwo steps:
aegis db rollback web --step 2✔ 2 migration(s) rolled back 20261117_103000_add_vhost_tls.sql, 20261117_104512_add_php_version.sqlNothing to revert:
ℹ nothing to roll backA missing down file:
✖ 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.
aegis db make:migration DATABASE NAME| Argument | Default | Meaning |
|---|---|---|
DATABASE | required | database the migration belongs to |
NAME | required | file-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:
aegis db make:migration web add_php_versionaegis db make:migration blog add_posts✔ 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.sqlA bad name or an existing file exits 1:
✖ 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.
aegis db seed NAME| Argument | Default | Meaning |
|---|---|---|
NAME | required | database 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:
aegis db seed webaegis db seed blog✔ 2 seeder(s) executed 20260101_000000_roles.sql, 20260101_000010_settings.sqlAn empty seeder directory:
ℹ no seeders found#aegis db make:seeder
Creates an empty seeder file.
aegis db make:seeder DATABASE NAME| Argument | Default | Meaning |
|---|---|---|
DATABASE | required | database the seeder belongs to |
NAME | required | file-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:
aegis db make:seeder web default_settingsaegis db make:seeder blog demo_posts✔ seeder created /etc/aegis/database/seeders/web/20261117_104530_default_settings.sqlA bad name or an existing file exits 1:
✖ invalid name 'Default Settings': expected [a-z][a-z0-9_]*#How migrations run
ending in .down.sql are rollback counterparts and are not applied by migrate.
schema_migrations with its name andan ISO timestamp.
schema_migrations row are wrapped in an explicitBEGIN 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.
ADD COLUMN IF NOT EXISTS or DROP COLUMN IF EXISTS. Before afile 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 inreverse 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.
does, no record of having run, and no rollback.
#Files
| Path | Content |
|---|---|
database/storage/<name>/<name>.db | the SQLite database |
database/storage/<name>/<name>.db-wal | write-ahead log, when present |
database/storage/<name>/<name>.db-shm | shared-memory file, when present |
database/migrations/core/<name>/*.sql | migrations of a core module |
database/migrations/<name>/*.sql | migrations of an operator database |
database/seeders/<name>/*.sql | seeders, run on every db seed |
schema_migrations | one 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.