feat: make automatic table creation an explicit option and build tables from their model #31
Labels
No labels
bug
documentation
duplicate
enhancement
good first issue
help wanted
invalid
qa:preview
question
wontfix
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
quatrain/core#31
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Context
When a record is written or read, the SQL backend adapters create missing tables on the fly (
_ensureTablein@quatrain/backend-postgres, its equivalent in@quatrain/backend-sqlite). They also create the tables that object properties refer to, so that joins do not fail.This behaviour conflicts with several rule units of the AGENTS.okf knowledge base. The rule names below refer to its
content/tree.Problems, by rule
Fail-Fast Contracts & Configuration (
architecture/fail-fast-contracts.md)Core, the adapter creates a substitute table holding onlyidandname. Any later use of the real model fails withcolumn "…" does not exist. The failure is order-dependent: it broke CI on an empty database when a test whose model only referred to users ran before the tests using theUsermodel.CREATEright, as row isolation requires) it can only fail late, at the first query.PostgreSQL DDL Migrations & Lowercase Naming Standards (
backend-workers/postgresql-ddl-and-naming.md).sqlfile. Tables created at run time bypass it.CREATE TABLE "user" ("name" TEXT)); the rule forbids double quotes and requires strictly lowercase names. Note: theusercollection is a reserved word and only works quoted.TIMESTAMP; the rule requiresTIMESTAMP WITH TIME ZONE.TEXT, identifiersVARCHAR(255).Dependency Injection & DRY (
architecture/dependency-injection-and-dry.md)backend-postgres(_ensureTableByName,generateCreateSql,generateDeltaSql) and again inbackend-sqlite.Structured Logging (
architecture/structured-logging.md)console.log(err)/console.error(err).Expected behaviour
AbstractBackendAdapter, as the fail-fast rule requires for configuration of abstract classes.UNIQUEfor unique properties, lowercase unquoted identifiers, time-zone-aware timestamps..sqlfile per table, idempotent (CREATE TABLE IF NOT EXISTS, constraints and indexes guarded the same way), so it can be committed and replayed on any environment to obtain the same schema. A table never exists in a database without its DDL existing as a file. This reuses the migration generation of@quatrain/backend-migrationsrather than a second mechanism.Backend.errorwith a structured payload (collection, table, cause).Decisions to take
Where dynamic-creation migration files are written (configured directory, required when the flag is enabled; fail fast if it is missing or not writable) and how they are named and ordered.
What happens when a migration file already exists for the table but differs from the model.
Default value of the flag. Today's behaviour is "enabled"; the DDL rule argues for "disabled" outside development and tests.
The
usercollection name, incompatible with unquoted identifiers: rename (breaking) or documented exception.Whether changing column types of generated tables needs a migration path for existing databases.
Acceptance
tsccompiles with zero errors; noas anyadded (Strict Typing, Interfaces & Zero-Any Policy)..sqlmigration file; replaying that file on an empty database yields the same table, and replaying it twice changes nothing.TIMESTAMPwithout time zone.feat(backend): make automatic table creation a global option and build related tables from their modelto feat: make automatic table creation an explicit option and build tables from their model