Skip to main content

Troubleshooting

Module not initialized​

Make sure @quik/database is registered in your bootstrap module and appears after its dependencies.

Configuration not applied​

Verify db.configuration and the matching db.mysql/db.postgres/db.sqlite block are set before module init; leave db.configuration empty to run without a database connection.

Legacy migrations table​

If migration:apply reports missing metadata columns on an older migrations table, run migration:update-table. Column upgrades otherwise happen automatically the next time the table is resolved, so this is only needed to force the upgrade ahead of time or to refresh stored checksums with --force.

Schema-scoped module on a non-Postgres dialect​

MigrationStore.setSchema(module, schema) throws QMigrationError on any dialect other than Postgres — schema qualification relies on Knex's dot-qualified identifier handling on the pg client and is not portable to MySQL.

migration:generate misses a model's changes​

migration:generate only sees @Model() classes whose file has already been imported/registered at the point the command runs — the same precondition as getModels(). It also diffs against the global snapshot (db.migrations.snapshotFile), not the live database, so changes made directly in the database without going through a migration won't show up as a diff.

Common Errors​

  • quik.errors.database.item-not-found: the requested row does not exist (or was soft-deleted and withDeleted was not passed).
  • quik.errors.database.soft-delete-unsupported: delete/restore was called on a model that does not define a soft-delete column.
  • quik.errors.database.repository-not-loaded: the repository was not registered via RepositoryStore.register(...)/RepositoryStore.load(...) before use.
  • quik.errors.database.unsupported-uuid-default-dialect: uuidDefault(engine) was called against a dialect other than Postgres or MySQL.
  • quik.errors.database.unsupported-enum-alteration-dialect: alterEnumColumn(engine, options) was called against a dialect other than Postgres or MySQL.