In MAAS (Metal as a Service), migrate-database is a command used to apply database schema changes when upgrading MAAS or modifying its database structure. It ensures that the PostgreSQL database used by MAAS is properly updated to match the current software version.
Purpose in MAAS
The migrate-database command is essential for:
- Upgrading MAAS – Applies necessary schema changes when updating to a new MAAS version.
- Ensuring database integrity – Keeps the database in sync with the application logic.
- Fixing missing migrations – Can be used to apply pending schema changes if MAAS fails to start due to a database mismatch.
MAAS relies on a PostgreSQL backend, and migrate-database ensures that new features, tables, and relationships are correctly applied during upgrades.
Scope & behavior in MAAS
- Applies to the MAAS database only – Does not affect external data or machines.
- Required after major upgrades – If MAAS is upgraded, the database schema must be migrated.
- Must be run before starting MAAS after an upgrade – Failing to migrate the database may result in startup failures.
- Requires database access – The command must be run with appropriate PostgreSQL permissions.
MAAS CLI usage
Running database migrations
maas migrate-database
Applies all pending migrations to the MAAS database.
Running migrations with debug logging
maas migrate-database --debug
Runs migrations with verbose logging for troubleshooting.
Checking for pending migrations (indirectly)
MAAS does not have a direct command for checking pending migrations, but attempting a dry-run migration can help:
sudo -u maas psql maasdb -c "SELECT * FROM django_migrations ORDER BY applied DESC LIMIT 5;"
This query shows the last applied migrations.
Key considerations
- Always backup the database before migrating – Migrations modify the database schema and cannot always be reversed.
- Must be run before restarting MAAS after an upgrade – Skipping this step may lead to startup errors.
- Requires PostgreSQL access – If the database is hosted remotely, ensure connectivity and credentials are correct.
- Can take time on large datasets – If many machines or logs exist, the migration process may take longer.
Last updated 9 hours ago.