| name | aquilia-database-orm-migrations |
| description | Build Aquilia database, sqlite, ORM model, query, transaction, and migration workflows. Use for DatabaseIntegration, typed DB configs, AquiliaDatabase, native sqlite, Model fields/managers, makemigrations/migrate/sqlmigrate/inspectdb/status, and schema snapshots. |
Aquilia Database Orm Migrations
Purpose
Implement and debug Aquilia database and model workflows from typed config through migrations.
Trigger Conditions
Use for Workspace.database, Integration.database, SqliteConfig/PostgresConfig/MysqlConfig/OracleConfig, AquiliaDatabase, native sqlite, Model subclasses, fields, querysets, transactions, and aq db commands.
Inputs
- Database URL or typed config.
- Model classes and fields.
- Migration directory, app filter, database alias, and whether to emit DSL or SQL.
Execution Flow
- Configure DB globally through
Workspace.database(...) or Integration.database(config=...).
- Define models as Python
Model subclasses with fields from aquilia.models.
- Use async query APIs such as
Model.objects.filter(...).all(), Model.create(...), and transaction helpers.
- Generate migrations with
aq db makemigrations; apply with aq db migrate; inspect with showmigrations, sqlmigrate, status, or inspectdb.
- For sqlite internals, use native
aquilia.sqlite rather than deprecated aiosqlite paths.
Constraints
- Use parameterized query APIs; do not construct SQL with untrusted field/table names.
- Manifest-level database config is deprecated and ignored at runtime.
- Migration snapshots use Crous binary where available; do not hand-edit unless necessary.
Implementation Anchors
aquilia/db/configs.py, aquilia/db/engine.py, aquilia/sqlite/, aquilia/models/base.py, aquilia/models/fields_module.py, aquilia/models/migration_gen.py, aquilia/cli/commands/model_cmds.py, examples/sqlite_inventory_app/.
Examples
- Add
SqliteConfig(path="runtime/app.db", auto_create=True) to a workspace.
- Create
class Project(Model): key = CharField(max_length=64, unique=True).
- Run
aq db makemigrations --app inventory then aq db migrate --plan.
Failure Handling
Unsupported URLs raise database connection faults. Field validation raises FieldValidationFault. If startup guard complains about migrations, generate/apply migrations or set an explicit development auto-migration policy.
