qubu 0.6.2 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/dist/codegen.d.mts +1 -1
  2. package/dist/codegen.mjs +1 -1
  3. package/dist/core.d.mts +1 -1
  4. package/dist/diff.d.mts +1 -1
  5. package/dist/index-DB07P2X8.d.mts +2 -0
  6. package/dist/index.d.mts +1 -1
  7. package/dist/introspection/mysql.d.mts +1 -1
  8. package/dist/introspection/postgres.d.mts +1 -1
  9. package/dist/introspection/sqlite.d.mts +1 -1
  10. package/dist/introspection.d.mts +3 -2
  11. package/dist/introspection.mjs +1 -1
  12. package/dist/mysql.d.mts +2 -2
  13. package/dist/postgres.d.mts +2 -2
  14. package/dist/schema.d.mts +1 -1
  15. package/dist/{serialize-Du2UPZMt.d.mts → serialize-Dg-Q55YQ.d.mts} +1 -1
  16. package/dist/snapshot/mysql.d.mts +2 -2
  17. package/dist/snapshot/postgres.d.mts +2 -2
  18. package/dist/snapshot/sqlite.d.mts +2 -2
  19. package/dist/{snapshot-mIb-Zzb5.mjs → snapshot-C1x2R-iK.mjs} +25 -9
  20. package/dist/snapshot.d.mts +3 -3
  21. package/dist/sqlite.d.mts +2 -2
  22. package/dist/{types-CiMvKi5V.d.mts → types-CdcYI0lU.d.mts} +1 -1
  23. package/dist/{types-Dqr4o2I1.d.mts → types-DcIiNePM.d.mts} +7 -0
  24. package/docs/dialects-and-execution.md +54 -25
  25. package/docs/getting-started.md +9 -9
  26. package/docs/guides/better-auth.md +16 -5
  27. package/docs/guides/compose-queries.md +21 -9
  28. package/docs/guides/drizzle.md +8 -3
  29. package/docs/guides/extensions/dialects.md +1 -1
  30. package/docs/guides/extensions/overview.md +1 -1
  31. package/docs/guides/extensions/sources-and-clauses.md +7 -3
  32. package/docs/guides/extensions/typed-expressions.md +25 -13
  33. package/docs/guides/extensions/unsafe-syntax.md +10 -6
  34. package/docs/guides/json.md +52 -27
  35. package/docs/guides/mutations.md +15 -6
  36. package/docs/guides/select/conditions.md +18 -11
  37. package/docs/guides/select/grouping-and-windows.md +5 -2
  38. package/docs/guides/select/ordering-and-pagination.md +5 -3
  39. package/docs/guides/select/overview.md +6 -3
  40. package/docs/guides/sql-templates.md +11 -5
  41. package/docs/guides/valtio-sync.md +11 -5
  42. package/docs/guides/vite-plugin.md +2 -2
  43. package/docs/index.md +24 -17
  44. package/docs/migrations/adapters.md +58 -22
  45. package/docs/migrations/adopt.md +331 -0
  46. package/docs/migrations/artifacts-and-policy.md +49 -20
  47. package/docs/migrations/index.md +18 -9
  48. package/docs/migrations/operations.md +60 -70
  49. package/docs/migrations/recovery.md +34 -17
  50. package/docs/query-model/fragments.md +13 -5
  51. package/docs/query-model/result-shapes.md +2 -2
  52. package/docs/query-model/source-scope.md +5 -3
  53. package/docs/reference/introspection-support.md +26 -19
  54. package/docs/reference/mysql-snapshot.md +19 -4
  55. package/docs/reference/postgres-snapshot.md +17 -4
  56. package/docs/reference/sqlite-snapshot.md +19 -2
  57. package/docs/reference/supported-surface.md +221 -85
  58. package/docs/schema/catalog-model.md +24 -7
  59. package/docs/schema/code-generation.md +40 -21
  60. package/docs/schema/columns-and-writes.md +21 -11
  61. package/docs/schema/constraints-and-indexes.md +12 -5
  62. package/docs/schema/ddl-emission.md +16 -5
  63. package/docs/schema/diff.md +12 -4
  64. package/docs/schema/introspection.md +47 -21
  65. package/docs/schema/migration-plans.md +18 -10
  66. package/docs/schema/snapshots.md +57 -29
  67. package/docs/schema/storage-and-schema-sql.md +10 -4
  68. package/docs/schema/tables-and-names.md +1 -1
  69. package/docs/sql-semantic-types.md +11 -8
  70. package/docs/troubleshooting.md +14 -6
  71. package/package.json +1 -1
  72. package/dist/index-CaxrMD1A.d.mts +0 -1
  73. package/docs/migrations/lotta-adoption.md +0 -50
package/docs/reference/mysql-snapshot.md CHANGED
@@ -1,8 +1,6 @@
1
1
  # MySQL snapshot support
2
2
 
3
- > Use this matrix before selecting `mysqlSnapshotAdapter`; it records the
4
- > MySQL facts Qubu v1 can encode and the combinations that need a later server
5
- > version or engine policy.
3
+ > Check which MySQL schema features the Snapshot v1 adapter can save.
6
4
 
7
5
  Import the adapter from the MySQL snapshot subpath:
8
6
 
@@ -21,7 +19,7 @@ to this adapter.
21
19
 
22
20
  | Schema fact | MySQL v1 behavior |
23
21
  | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
24
- | Portable storage | Maps `integer` to `INT`, `numeric` to `DECIMAL`, `text` to `TEXT`, `boolean` to `BOOLEAN`, `date` to `DATE`, `timestamp` to `DATETIME`, `uuid` to `CHAR(36)`, `json` to `JSON`, `bigint` to `BIGINT`, and `binary` to `VARBINARY`. |
22
+ | Portable storage | Uses the mappings below. |
25
23
  | Native storage | Preserves a non-empty declaration tagged `mysql` exactly. Native declarations owned by another dialect fail. |
26
24
  | Literals | Encodes `NULL`, finite numbers, strings, booleans, and `bigint` without query parameters. Strings use SQL quote doubling. |
27
25
  | Defaults | Canonical literals, branded deterministic expressions, and explicit external behavior are retained. Default expressions cannot reference columns or parameters. |
@@ -34,6 +32,23 @@ to this adapter.
34
32
  | Indexes | Ordered terms, expressions, uniqueness, and candidate-key evidence are retained. Partial predicates, included columns, and `NULLS FIRST/LAST` are diagnosed. Algorithm, locking, access method, parser, and key-block options live under `dialect`. |
35
33
  | Names | Table, column, constraint, and index names are checked against MySQL's 64-character identifier limit. Table names are database-scoped; index names are table-scoped. |
36
34
 
35
+ ## Portable storage types
36
+
37
+ | Qubu storage | Database declaration |
38
+ | ------------ | -------------------- |
39
+ | `integer` | `INT` |
40
+ | `numeric` | `DECIMAL` |
41
+ | `text` | `TEXT` |
42
+ | `boolean` | `BOOLEAN` |
43
+ | `date` | `DATE` |
44
+ | `timestamp` | `DATETIME` |
45
+ | `uuid` | `CHAR(36)` |
46
+ | `json` | `JSON` |
47
+ | `bigint` | `BIGINT` |
48
+ | `binary` | `VARBINARY` |
49
+
50
+ ## Diagnostics
51
+
37
52
  Capability checks run before common traversal. Use the non-throwing form when
38
53
  a schema may include a MySQL engine or version-specific feature:
39
54
 
package/docs/reference/postgres-snapshot.md CHANGED
@@ -1,8 +1,6 @@
1
1
  # PostgreSQL snapshot support
2
2
 
3
- > Use this matrix before selecting `postgresSnapshotAdapter`; it records the
4
- > PostgreSQL facts Qubu v1 can encode and the cases that need a later server
5
- > version policy.
3
+ > Check which PostgreSQL schema features the Snapshot v1 adapter can save.
6
4
 
7
5
  Import the adapter from the PostgreSQL snapshot subpath:
8
6
 
@@ -24,7 +22,7 @@ snapshot metadata and `unsafeSchemaSql()` use `postgresql` consistently.
24
22
 
25
23
  | Schema fact | PostgreSQL v1 behavior |
26
24
  | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
27
- | Portable storage | Emits PostgreSQL declarations: `INTEGER`, `NUMERIC`, `TEXT`, `BOOLEAN`, `DATE`, `TIMESTAMP`, `UUID`, `JSONB`, `BIGINT`, and `BYTEA`. |
25
+ | Portable storage | Uses the mappings below. |
28
26
  | Native storage | Preserves a non-empty declaration tagged `postgresql` exactly. Other dialect tags fail. |
29
27
  | Literals | Encodes finite numbers, strings, booleans, `bigint`, and `NULL` without query parameters. |
30
28
  | Defaults | Canonical literals, branded deterministic expressions, and explicit external behavior are retained. Column references in defaults fail. |
@@ -41,6 +39,21 @@ deterministic data for the `qubu/snapshot` decoder. The package-wide
41
39
  [ownership map](supported-surface.md#ownership-boundary) shows the separate
42
40
  schema and application boundaries.
43
41
 
42
+ ## Portable storage types
43
+
44
+ | Qubu storage | Database declaration |
45
+ | ------------ | -------------------- |
46
+ | `integer` | `INTEGER` |
47
+ | `numeric` | `NUMERIC` |
48
+ | `text` | `TEXT` |
49
+ | `boolean` | `BOOLEAN` |
50
+ | `date` | `DATE` |
51
+ | `timestamp` | `TIMESTAMP` |
52
+ | `uuid` | `UUID` |
53
+ | `json` | `JSONB` |
54
+ | `bigint` | `BIGINT` |
55
+ | `binary` | `BYTEA` |
56
+
44
57
  ## Diagnostics
45
58
 
46
59
  Use the non-throwing form when a schema may contain a server-specific feature:
package/docs/reference/sqlite-snapshot.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # SQLite snapshot support
2
2
 
3
- > Use this matrix to decide which SQLite schema facts Qubu v1 can serialize and which combinations must be diagnosed before a snapshot is written.
3
+ > Check which SQLite schema features the Snapshot v1 adapter can save.
4
4
 
5
5
  Import the adapter from the SQLite snapshot subpath:
6
6
 
@@ -20,7 +20,7 @@ to distinguish it from the query renderer. A dialect-tagged
20
20
 
21
21
  | Schema fact | SQLite v1 behavior |
22
22
  | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
23
- | Portable storage | Maps `integer`, `boolean`, and `bigint` to `INTEGER`; `text`, `date`, `timestamp`, `uuid`, and `json` to `TEXT`; `numeric` to `NUMERIC`; and `binary` to `BLOB`. The snapshot also records SQLite's derived affinity. |
23
+ | Portable storage | Uses the mappings below. SQLite affinity is also recorded. |
24
24
  | Native storage | Preserves a non-empty declaration tagged `sqlite` exactly and records its affinity using SQLite's ordered declared-type rules. Other dialect tags fail. |
25
25
  | Literals | Encodes `NULL`, finite numbers, strings, `bigint`, and booleans as parameter-free SQL. Boolean literals use `1` and `0`; strings retain SQL escaping. |
26
26
  | Defaults | Canonical literals, branded deterministic expressions, and explicit external behavior are retained. Default expressions cannot reference columns or parameters. |
@@ -32,6 +32,23 @@ to distinguish it from the query renderer. A dialect-tagged
32
32
  | Indexes | Ordered terms, expressions, uniqueness, predicates for partial indexes, and candidate-key evidence are retained. Included columns are diagnosed as unsupported. The typed SQLite index extension is encoded under `dialect`. |
33
33
  | Namespaces | An optional unqualified namespace is retained; Qubu does not attach or inspect SQLite databases. |
34
34
 
35
+ ## Portable storage types
36
+
37
+ | Qubu storage | Database declaration |
38
+ | ------------ | -------------------- |
39
+ | `integer` | `INTEGER` |
40
+ | `numeric` | `NUMERIC` |
41
+ | `text` | `TEXT` |
42
+ | `boolean` | `INTEGER` |
43
+ | `date` | `TEXT` |
44
+ | `timestamp` | `TEXT` |
45
+ | `uuid` | `TEXT` |
46
+ | `json` | `TEXT` |
47
+ | `bigint` | `INTEGER` |
48
+ | `binary` | `BLOB` |
49
+
50
+ ## Diagnostics
51
+
35
52
  Capability checks run before common traversal. Use the non-throwing form when a
36
53
  schema may include a feature that depends on a SQLite version or table shape:
37
54
 
package/docs/reference/supported-surface.md CHANGED
@@ -1,61 +1,73 @@
1
1
  # Supported features
2
2
 
3
- > Choose a public package entrypoint and keep application policy separate from portable migration and driver-owned capabilities.
3
+ > Find the right import and check what Qubu supports and what your application manages.
4
4
 
5
5
  ## Package entrypoints
6
6
 
7
- | Import | Kind | Use it for |
8
- | ----------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
9
- | `qubu` | Runtime | Ordinary query and schema definitions, reads, writes, SQL templates, rendering, EXPLAIN, and execution contracts |
10
- | `qubu/core` | Runtime | Fragment and rendering primitives, dialect construction, SQL types, and extension constructors |
11
- | `qubu/codegen` | Runtime | Deterministic machine-owned TypeScript schemas from complete, non-lossy introspection |
12
- | `qubu/diff` | Runtime | Canonical Snapshot v1 comparison, rename hints, suggestions, and safety diagnostics |
13
- | `qubu/introspection` | Runtime | Shared catalog contracts, normalized catalog models, diagnostics, and mapping to Snapshot v1 |
14
- | `qubu/introspection/postgres` | Runtime | PostgreSQL catalog reader and catalog queries for one selected namespace |
15
- | `qubu/introspection/sqlite` | Runtime | SQLite catalog reader and catalog queries for one selected namespace |
16
- | `qubu/introspection/mysql` | Runtime | MySQL catalog reader and catalog queries for one selected namespace |
17
- | `qubu/mysql` | Runtime | The MySQL query dialect policy |
18
- | `qubu/postgres` | Runtime | PostgreSQL query dialect helpers such as `postgresDialect()` and `ilike()` |
19
- | `qubu/schema` | Runtime | Advanced schema metadata, storage and constraint models, source models, and schema-expression extensions |
20
- | `qubu/snapshot` | Runtime | Canonical Snapshot v1 traversal, encoding, decoding, diagnostics, and fingerprints |
21
- | `qubu/snapshot/mysql` | Runtime | MySQL snapshot adapter, schema dialect, and convenience creators |
22
- | `qubu/snapshot/postgres` | Runtime | PostgreSQL snapshot adapter, schema dialect, and convenience creators |
23
- | `qubu/snapshot/sqlite` | Runtime | SQLite snapshot adapter, schema dialect, affinity helper, and convenience creators |
24
- | `qubu/sqlite` | Runtime | The SQLite query dialect policy and native SQLite column factories |
25
- | `qubu/vite` | Runtime | The optional `qubu()` Vite compiler hint |
26
- | `qubu/package.json` | JSON | The published package manifest |
27
- | `@qubu/migrate` | Runtime | Migration compiler format identity and shared plan types |
28
- | `@qubu/pgvector` | Runtime | PostgreSQL pgvector columns, dense-vector codecs, distance expressions, and HNSW/IVFFlat index metadata |
29
- | `@qubu/migrate/plan` | Runtime | Pure migration planning with dependencies, decisions, preconditions, and explicit custom SQL |
30
- | `@qubu/migrate/ddl` | Runtime | DDL preflight and generic emission from a migration plan and supplied schema dialect |
31
- | `@qubu/migrate/ddl/postgres` | Runtime | PostgreSQL DDL emission from an approved migration plan |
32
- | `@qubu/migrate/ddl/sqlite` | Runtime | SQLite DDL emission from an approved migration plan |
33
- | `@qubu/migrate/ddl/mysql` | Runtime | MySQL DDL emission from an approved migration plan |
34
- | `@qubu/migrate/artifact` | Runtime | Generic versioned program compilation with a caller-supplied schema dialect, plus strict artifacts and baselines |
35
- | `@qubu/migrate/artifact/postgres` | Runtime | PostgreSQL versioned program compilation |
36
- | `@qubu/migrate/artifact/sqlite` | Runtime | SQLite versioned program compilation, including table rebuilds |
37
- | `@qubu/migrate/artifact/mysql` | Runtime | MySQL versioned program compilation |
38
- | `@qubu/migrate/repository` | Runtime | Strict full-chain and journal-prefix verification |
39
- | `@qubu/migrate/journal` | Runtime | Storage-neutral journal records, transitions, validation, and reference storage |
40
- | `@qubu/migrate/executor` | Runtime | Portable execution, structured errors, checkpointing, and explicit reconciliation |
41
- | `@qubu/migrate/baseline` | Runtime | Strict live baseline verification and physical managed-schema comparison |
42
- | `@qubu/migrate/status` | Runtime | Pending chain, managed drift, unmanaged objects, interrupted attempts, and incompatible requirements |
43
- | `@qubu/migrate/bootstrap` | Runtime | Shared bootstrap preparation, result types, and generic planning with a caller-supplied schema dialect |
44
- | `@qubu/migrate/bootstrap/postgres` | Runtime | Fresh PostgreSQL schema planning through the normal diff, plan, and program compiler |
45
- | `@qubu/migrate/bootstrap/sqlite` | Runtime | Fresh SQLite schema planning through the normal diff, plan, and program compiler |
46
- | `@qubu/migrate/testing` | Runtime | Deterministic fake adapters, fault boundaries, and adapter conformance checks |
47
- | `@qubu/cli` | Runtime and CLI | `@alloc/cmd-ts` commands, typed config, filesystem repositories, stable output, and exit codes |
48
- | `@qubu/drizzle` | Runtime | Shared Drizzle conversion errors and dialect types |
49
- | `@qubu/drizzle/mysql` | Runtime | Runtime conversion from Qubu schemas to MySQL Drizzle tables |
50
- | `@qubu/drizzle/postgres` | Runtime | Runtime conversion from Qubu schemas to PostgreSQL Drizzle tables |
51
- | `@qubu/drizzle/sqlite` | Runtime | Runtime conversion from Qubu schemas to SQLite Drizzle tables |
52
- | `@qubu/better-auth` | Runtime | Better Auth schema derivation and native PostgreSQL, MySQL, and SQLite adapter behavior |
53
- | `@qubu/adapter-neon` | Runtime | Experimental Neon HTTP PostgreSQL `QueryAdapter` behavior |
54
- | `@qubu/adapter-planetscale` | Runtime | Experimental PlanetScale serverless MySQL `QueryAdapter` and transaction behavior |
55
- | `@qubu/adapter-aws-rds-data-api/postgres` | Runtime | Experimental Aurora PostgreSQL AWS RDS Data API adapter behavior |
56
- | `@qubu/adapter-aws-rds-data-api/mysql` | Runtime | Experimental Aurora MySQL AWS RDS Data API adapter behavior |
57
- | `@qubu/adapter-sqlite-wasm` | Runtime | Official SQLite WASM OO1 `QueryAdapter` for browser and web-worker databases |
58
- | `qubu/globals` | TypeScript types | Opt-in ambient declarations for directive-bearing modules |
7
+ ### Query and schema imports
8
+
9
+ | Import | Kind | Use it for |
10
+ | ----------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
11
+ | `qubu` | Runtime | Ordinary query and schema definitions, reads, writes, SQL templates, rendering, EXPLAIN, and execution contracts |
12
+ | `qubu/core` | Runtime | Fragment and rendering primitives, dialect construction, SQL types, and extension constructors |
13
+ | `qubu/codegen` | Runtime | Deterministic machine-owned TypeScript schemas from complete, non-lossy introspection |
14
+ | `qubu/diff` | Runtime | Canonical Snapshot v1 comparison, rename hints, suggestions, and safety diagnostics |
15
+ | `qubu/introspection` | Runtime | Shared catalog contracts, normalized catalog models, diagnostics, and mapping to Snapshot v1 |
16
+ | `qubu/introspection/postgres` | Runtime | PostgreSQL catalog reader and catalog queries for one selected namespace |
17
+ | `qubu/introspection/sqlite` | Runtime | SQLite catalog reader and catalog queries for one selected namespace |
18
+ | `qubu/introspection/mysql` | Runtime | MySQL catalog reader and catalog queries for one selected namespace |
19
+ | `qubu/mysql` | Runtime | The MySQL query dialect policy |
20
+ | `qubu/postgres` | Runtime | PostgreSQL query dialect helpers such as `postgresDialect()` and `ilike()` |
21
+ | `qubu/schema` | Runtime | Advanced schema metadata, storage and constraint models, source models, and schema-expression extensions |
22
+ | `qubu/snapshot` | Runtime | Canonical Snapshot v1 traversal, encoding, decoding, diagnostics, and fingerprints |
23
+ | `qubu/snapshot/mysql` | Runtime | MySQL snapshot adapter, schema dialect, and convenience creators |
24
+ | `qubu/snapshot/postgres` | Runtime | PostgreSQL snapshot adapter, schema dialect, and convenience creators |
25
+ | `qubu/snapshot/sqlite` | Runtime | SQLite snapshot adapter, schema dialect, affinity helper, and convenience creators |
26
+ | `qubu/sqlite` | Runtime | The SQLite query dialect policy and native SQLite column factories |
27
+ | `qubu/vite` | Runtime | The optional `qubu()` Vite compiler hint |
28
+ | `qubu/package.json` | JSON | The published package manifest |
29
+ | `qubu/globals` | TypeScript types | Opt-in ambient declarations for directive-bearing modules |
30
+
31
+ ### Migration imports
32
+
33
+ | Import | Kind | Use it for |
34
+ | ---------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------- |
35
+ | `@qubu/migrate` | Runtime | Migration compiler format identity and shared plan types |
36
+ | `@qubu/migrate/plan` | Runtime | Pure migration planning with dependencies, decisions, preconditions, and explicit custom SQL |
37
+ | `@qubu/migrate/ddl` | Runtime | DDL preflight and generic emission from a migration plan and supplied schema dialect |
38
+ | `@qubu/migrate/ddl/postgres` | Runtime | PostgreSQL DDL emission from an approved migration plan |
39
+ | `@qubu/migrate/ddl/sqlite` | Runtime | SQLite DDL emission from an approved migration plan |
40
+ | `@qubu/migrate/ddl/mysql` | Runtime | MySQL DDL emission from an approved migration plan |
41
+ | `@qubu/migrate/artifact` | Runtime | Generic versioned program compilation with a caller-supplied schema dialect, plus strict artifacts and baselines |
42
+ | `@qubu/migrate/artifact/postgres` | Runtime | PostgreSQL versioned program compilation |
43
+ | `@qubu/migrate/artifact/sqlite` | Runtime | SQLite versioned program compilation, including table rebuilds |
44
+ | `@qubu/migrate/artifact/mysql` | Runtime | MySQL versioned program compilation |
45
+ | `@qubu/migrate/repository` | Runtime | Strict full-chain and journal-prefix verification |
46
+ | `@qubu/migrate/journal` | Runtime | Storage-neutral journal records, transitions, validation, and reference storage |
47
+ | `@qubu/migrate/executor` | Runtime | Portable execution, structured errors, checkpointing, and explicit reconciliation |
48
+ | `@qubu/migrate/baseline` | Runtime | Live candidate capture, exact baseline verification, and physical managed-schema comparison |
49
+ | `@qubu/migrate/status` | Runtime | Pending chain, managed drift, unmanaged objects, interrupted attempts, and incompatible requirements |
50
+ | `@qubu/migrate/bootstrap` | Runtime | Shared bootstrap preparation, result types, and generic planning with a caller-supplied schema dialect |
51
+ | `@qubu/migrate/bootstrap/postgres` | Runtime | Fresh PostgreSQL schema planning through the normal diff, plan, and program compiler |
52
+ | `@qubu/migrate/bootstrap/sqlite` | Runtime | Fresh SQLite schema planning through the normal diff, plan, and program compiler |
53
+ | `@qubu/migrate/testing` | Runtime | Deterministic fake adapters, fault boundaries, and adapter conformance checks |
54
+ | `@qubu/cli` | Runtime and CLI | `@alloc/cmd-ts` commands, typed config, filesystem repositories, stable output, and exit codes |
55
+
56
+ ### Integrations and adapters
57
+
58
+ | Import | Kind | Use it for |
59
+ | ----------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
60
+ | `@qubu/pgvector` | Runtime | PostgreSQL pgvector columns, dense-vector codecs, distance expressions, and HNSW/IVFFlat index metadata |
61
+ | `@qubu/drizzle` | Runtime | Shared Drizzle conversion errors and dialect types |
62
+ | `@qubu/drizzle/mysql` | Runtime | Runtime conversion from Qubu schemas to MySQL Drizzle tables |
63
+ | `@qubu/drizzle/postgres` | Runtime | Runtime conversion from Qubu schemas to PostgreSQL Drizzle tables |
64
+ | `@qubu/drizzle/sqlite` | Runtime | Runtime conversion from Qubu schemas to SQLite Drizzle tables |
65
+ | `@qubu/better-auth` | Runtime | Better Auth schema derivation and native PostgreSQL, MySQL, and SQLite adapter behavior |
66
+ | `@qubu/adapter-neon` | Runtime | Experimental Neon HTTP PostgreSQL `QueryAdapter` behavior |
67
+ | `@qubu/adapter-planetscale` | Runtime | Experimental PlanetScale serverless MySQL `QueryAdapter` and transaction behavior |
68
+ | `@qubu/adapter-aws-rds-data-api/postgres` | Runtime | Experimental Aurora PostgreSQL AWS RDS Data API adapter behavior |
69
+ | `@qubu/adapter-aws-rds-data-api/mysql` | Runtime | Experimental Aurora MySQL AWS RDS Data API adapter behavior |
70
+ | `@qubu/adapter-sqlite-wasm` | Runtime | Official SQLite WASM OO1 `QueryAdapter` for browser and web-worker databases |
59
71
 
60
72
  The package validator checks every declared entrypoint in each packed workspace
61
73
  package. Concrete dialect constructors live on their database subpaths. The
@@ -66,33 +78,110 @@ Snapshot dialect behavior is documented in the [PostgreSQL](postgres-snapshot.md
66
78
 
67
79
  ## Canonical query vocabulary
68
80
 
69
- Use the root names in new query code: `eq`, `ne`, `lt`, `lte`, `gt`, `gte`,
70
- `avg`, `min`, `max`, `fetchFirst`, `alias`, `render`, `qubu`, `execute`,
71
- `deleteFrom`, and `allowAll`. The package does not document competing aliases
72
- for these operations. Keep advanced fragment, dialect-construction, and
73
- schema-extension imports on `qubu/core` or `qubu/schema` as shown in the
74
- entrypoint table.
81
+ Use these names from `qubu` in new query code:
82
+
83
+ - Equality: `eq`, `ne`.
84
+ - Ordering comparisons: `lt`, `lte`, `gt`, `gte`.
85
+ - Aggregates: `avg`, `min`, `max`.
86
+ - Pagination and aliases: `fetchFirst`, `alias`.
87
+ - Rendering and execution: `render`, `qubu`, `execute`.
88
+ - Mutations: `deleteFrom`, `allowAll`.
89
+
90
+ Import advanced fragment and dialect constructors from `qubu/core`, and schema
91
+ extensions from `qubu/schema`.
75
92
 
76
93
  ## Capability map
77
94
 
78
- | Area | Supported building blocks |
79
- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
80
- | Schema values | `table`, immutable `schema` registries with namespaces, portable and dialect-native column storage descriptors, canonical default and generated-column metadata, identity descriptors, named primary, candidate-key, nullable unique, foreign-key, and check constraints, physical object names, included-column indexes, typed dialect extensions, and typed column helpers |
81
- | Read queries | Named projections, spreadable source columns, aliases, joins, typed custom and LATERAL `FROM` sources, correlated subqueries, `WHERE`, grouping with declared-key proofs, `HAVING`, ordering, window expressions, distinctness, pagination, row locking, ordinary and recursive CTEs, subqueries, and set operations |
82
- | Expressions | Comparison, boolean, arithmetic, null, range, membership, aggregate, window, string, JSON scalar reads and typed nested JSON query results, definition-backed and raw casts, cases, parameterized SQL templates, custom expressions, and branded deterministic schema expressions |
83
- | SQL type metadata | Portable domains and capabilities, physical column storage descriptors, `SqlTypeOf`, projected SQL type maps, `SourceLike` and `TableLike` field constraints, contextual literals, typed extension values, calls, and casts, plus a permissive `SqlUnknown` fallback |
84
- | Write queries | `INSERT` values, defaults, and selects; typed `UPDATE`, PostgreSQL `UPDATE ... FROM`, and `DELETE`; typed assignments; PostgreSQL/SQLite conflict clauses; MySQL duplicate-key updates and incoming rows; `RETURNING` on supporting dialects; and explicit unrestricted-write opt-in |
85
- | Rendering | Standard, PostgreSQL, SQLite, MySQL, and user-created policies for identifiers, placeholders, pagination, row locking, JSON, logical cast targets, schema literals, and EXPLAIN options |
86
- | Execution boundary | `QueryAdapter`, opt-in `ExplainableQueryAdapter`, `StreamingQueryAdapter`, and `TransactionalQueryAdapter` capabilities, bound clients from `qubu()`, structured results from `execute()` or `db.execute()`, row-only results from `executeRows()` or `db.rows()`, typed read streams from `stream()` or `db.stream()`, and adapter-decoded plan rows from `explain()` or `db.explain()` |
87
- | Snapshots | Pure Snapshot v1 creation, canonical encoding and strict decoding, immutable data, diagnostics, and FNV change-detection fingerprints |
88
- | Introspection | PostgreSQL, SQLite, and MySQL catalog readers for one selected namespace, normalized catalog data, structured diagnostics, and strict or explicit lossy snapshot mapping |
89
- | Snapshot diffing | Pure Snapshot v1 comparison, explicit rename evidence, non-authoritative suggestions, and safety diagnostics |
90
- | Migration planning | Pure, dialect-neutral plans with stable ordering, dependency edges, preconditions, explicit review decisions, and tagged custom SQL |
91
- | DDL emission | Preflight plus deterministic PostgreSQL, SQLite, and MySQL statements from an approved `MigrationPlan` and matching `SchemaDialect` |
92
- | Migration operations | Strict artifacts and baselines, authoritative programs, repository and journal validation, adapter capability preflight, execution, status/drift, reconciliation, SQLite bootstrap, and complete PostgreSQL bootstrap with standalone enum ordering |
93
- | Build tooling | The optional Vite directive transform and its matching TypeScript ambient declarations |
94
- | Drizzle conversion | Optional, dialect-specific runtime conversion from Qubu schema registries to Drizzle tables |
95
- | Source generation | Pure Snapshot v1 table source printing, deterministic camelCase IDs, exact physical metadata, controlled type mappings, and structured failure diagnostics |
95
+ ### Schema definitions
96
+
97
+ - Typed tables and immutable schema registries with namespaces.
98
+ - Portable and database-native column storage.
99
+ - Defaults, generated columns, and identity metadata.
100
+ - Named primary keys, candidate keys, and nullable unique constraints.
101
+ - Foreign keys and checks.
102
+ - Physical names, included-column indexes, and typed dialect extensions.
103
+
104
+ ### Read queries
105
+
106
+ - Named projections and spreadable source columns.
107
+ - Aliases, joins, and custom or LATERAL sources.
108
+ - Correlated subqueries and ordinary or recursive CTEs.
109
+ - `WHERE`, `GROUP BY`, and `HAVING`, including grouping checks based on declared keys.
110
+ - Ordering, window expressions, and distinct results.
111
+ - Pagination, row locking, and set operations.
112
+
113
+ ### Expressions and SQL types
114
+
115
+ - Comparisons, boolean logic, and arithmetic.
116
+ - Null checks, ranges, and membership tests.
117
+ - Aggregates, windows, string functions, and `CASE` expressions.
118
+ - JSON scalar reads and typed nested JSON results.
119
+ - Casts using column definitions or explicit SQL types.
120
+ - Parameterized SQL templates and custom expressions.
121
+ - Deterministic expressions for schema definitions.
122
+ - SQL domains and capabilities, including projected SQL type maps and `SqlTypeOf`.
123
+ - Reusable field constraints through `SourceLike` and `TableLike`.
124
+ - Contextual literals and typed extension values, calls, and casts.
125
+ - Permissive `SqlUnknown` for expressions without a declared SQL domain.
126
+
127
+ ### Write queries
128
+
129
+ - `INSERT` from values, defaults, or a query.
130
+ - Typed `UPDATE` and `DELETE`, including PostgreSQL `UPDATE ... FROM`.
131
+ - Typed assignments and PostgreSQL/SQLite conflict clauses.
132
+ - MySQL duplicate-key updates and incoming-row references.
133
+ - `RETURNING` on supporting dialects.
134
+ - Explicit opt-in for writes without a `WHERE` clause.
135
+
136
+ ### Rendering and execution
137
+
138
+ Standard SQL, PostgreSQL, SQLite, MySQL, and custom dialects control rendering:
139
+
140
+ - Identifier quoting and placeholders.
141
+ - Pagination and row locking.
142
+ - JSON and logical cast targets.
143
+ - Schema literals and EXPLAIN options.
144
+
145
+ Execution is available through standalone functions or a client from `qubu()`:
146
+
147
+ | Result | Standalone | Bound client |
148
+ | -------------------------- | --------------- | -------------- |
149
+ | Rows and mutation metadata | `execute()` | `db.execute()` |
150
+ | Rows only | `executeRows()` | `db.rows()` |
151
+ | Read stream | `stream()` | `db.stream()` |
152
+ | Query plan | `explain()` | `db.explain()` |
153
+
154
+ `QueryAdapter` handles basic execution. Streaming, EXPLAIN, and transactions
155
+ require the matching adapter capabilities.
156
+
157
+ ### Schema tools
158
+
159
+ - **Snapshots:** immutable Snapshot v1 data, canonical encoding, strict decoding,
160
+ diagnostics, and FNV change-detection fingerprints.
161
+ - **Introspection:** PostgreSQL, SQLite, and MySQL readers for one namespace,
162
+ with normalized catalog data and strict or explicitly lossy snapshot mapping.
163
+ - **Diffing:** snapshot comparison with explicit rename evidence, suggestions
164
+ for review, and safety diagnostics.
165
+ - **Planning:** dialect-neutral migration plans with ordered dependencies,
166
+ preconditions, review decisions, and tagged custom SQL.
167
+ - **DDL emission:** preflight checks and repeatable SQL output for an approved
168
+ plan and matching PostgreSQL, SQLite, or MySQL schema dialect.
169
+ - **Source generation:** TypeScript table declarations with deterministic
170
+ camelCase IDs, exact physical metadata, controlled type mappings, and diagnostics.
171
+
172
+ ### Migration operations
173
+
174
+ - Strict migration artifacts and verified baselines.
175
+ - Versioned executable programs.
176
+ - Repository and journal validation.
177
+ - Adapter capability checks before execution.
178
+ - Execution, status, drift detection, and reconciliation.
179
+ - SQLite bootstrap and complete PostgreSQL bootstrap, including enum ordering.
180
+
181
+ ### Build tools and integrations
182
+
183
+ - An optional Vite directive transform and matching TypeScript ambient declarations.
184
+ - Optional conversion from Qubu schema registries to dialect-specific Drizzle tables.
96
185
 
97
186
  ## Ownership boundary
98
187
 
@@ -102,14 +191,61 @@ interfaces the application provides. `@qubu/migrate` can orchestrate a sealed
102
191
  program only through a migration adapter's pinned session and advertised
103
192
  capabilities; `@qubu/cli` is the Node.js filesystem/process boundary.
104
193
 
105
- | Boundary | Qubu side | Application side |
106
- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
107
- | Query rendering | Builds a typed query and renders SQL text with ordered raw parameter values | Keeps the runtime database schema aligned with query definitions and validates any dynamic syntax passed to an unsafe helper |
108
- | Query execution | Binds an adapter with `qubu()` when requested; passes rendered statements and result shapes to execution adapters; applies registered logical field decoders to buffered or streamed object rows; scopes transaction callbacks; returns typed results, plans, rows, or streams | Owns the adapter, driver, connections, pools, cursors, stream cleanup, transactions, savepoints, retries, parameter encoding, proprietary row normalization, decoder policy, plan-row decoding, backpressure, cancellation, driver error translation, and database lifecycle |
109
- | Catalog introspection | Selects fixed parameterized catalog queries, normalizes rows, and maps catalog data to snapshots | Supplies `CatalogConnection`, credentials, already-decoded catalog rows, logging, and connection lifecycle |
110
- | Schema source generation | Prints deterministic TypeScript from complete, non-lossy Snapshot v1 introspection without writing files | Owns generated-file writes, replacement policy, hand-edit merging, and CLI integration |
111
- | Schema compilation | Creates snapshots, compares them, builds deterministic migration plans, previews DDL, and compiles authoritative versioned programs | Defines the target snapshot, operation approvals, custom programs, renderer/server constraints, and artifact provenance |
112
- | Migration operations | Verifies complete artifact and journal chains; orchestrates pinned sessions, leases, locks, transactions, checkpoints, head CAS, status, baselines, bootstrap, and explicit reconciliation through adapter contracts | Owns credentials, environment selection, adapter construction, rollout timing, deployment-provider coordination, recovery proof, legacy cutover, and database lifecycle |
194
+ ### Query rendering and execution
195
+
196
+ Qubu:
197
+
198
+ - Builds typed queries and renders SQL with ordered raw parameters.
199
+ - Passes statements and result shapes to the adapter.
200
+ - Decodes buffered or streamed rows with the registered field decoders.
201
+ - Creates scoped clients for transaction callbacks.
202
+ - Returns typed results, rows, streams, and plans.
203
+
204
+ Your application and adapter:
205
+
206
+ - Keep query definitions aligned with the database schema.
207
+ - Validate dynamic syntax passed to unsafe helpers.
208
+ - Manage drivers, connections, pools, and database lifecycle.
209
+ - Manage transactions, savepoints, and retries.
210
+ - Bind parameters and normalize driver rows.
211
+ - Choose result decoders and decode query-plan rows.
212
+ - Manage cursors, stream cleanup, buffering, and cancellation.
213
+ - Handle driver-specific errors.
214
+
215
+ ### Catalog introspection and source generation
216
+
217
+ Qubu runs fixed parameterized catalog queries through `CatalogConnection`,
218
+ normalizes the rows, and maps them to snapshots. It can print a TypeScript
219
+ schema from a complete introspection result without omitted facts.
220
+
221
+ Your application supplies:
222
+
223
+ - `CatalogConnection` and already-decoded catalog rows.
224
+ - Credentials, logging, and connection lifecycle.
225
+ - Generated-file writes and replacement policy.
226
+ - Any hand-edit merging and CLI integration.
227
+
228
+ ### Schema compilation and migration operations
229
+
230
+ Qubu creates and compares snapshots, builds plans, and compiles SQL previews or
231
+ versioned executable programs. The migration executor verifies artifact and
232
+ journal chains, then coordinates execution through the adapter:
233
+
234
+ - Sessions, leases, and locks.
235
+ - Transactions and checkpoints.
236
+ - Atomic checks and updates of the journal head.
237
+ - Status checks and baselines.
238
+ - Bootstrap and explicit reconciliation.
239
+
240
+ Your application supplies:
241
+
242
+ - The target snapshot and operation approvals.
243
+ - Custom programs and renderer/server requirements.
244
+ - Artifact provenance.
245
+ - Credentials, environment selection, and adapter construction.
246
+ - Rollout timing and deployment-provider coordination.
247
+ - Proof needed for recovery and decisions about legacy cutover.
248
+ - Database lifecycle management.
113
249
 
114
250
  Start with [Dialects and execution](../dialects-and-execution.md) for the query
115
251
  adapter contract. The schema path is documented in [Canonical schema
package/docs/schema/catalog-model.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # Complete catalog model
2
2
 
3
+ > Understand the database facts Qubu records before creating a snapshot.
4
+
3
5
  Qubu keeps database discovery in a normalized catalog before producing a
4
6
  snapshot. The catalog is a read-only record of observed facts; it does not
5
7
  contain a connection, execute catalog SQL, or assign database catalog keys as
@@ -18,13 +20,24 @@ const completeCatalog = createCompleteIntrospectionCatalog(catalog)
18
20
  const result = mapCatalogToCompleteSnapshot(completeCatalog)
19
21
  ```
20
22
 
21
- Tables, columns, views, materialized views, sequences, enums, domains,
22
- collations, triggers, routines, partitions, row-level policies, extension
23
- objects, comments, and ownership metadata have typed records. A reader may
24
- also retain a deferred or opaque object when it observes a family that Qubu
25
- cannot yet normalize. Such an object remains visible and can carry opaque
26
- catalog data, SQL text, provenance, and a dialect extension; it is never
27
- silently dropped.
23
+ ## Recorded objects
24
+
25
+ The catalog has typed records for:
26
+
27
+ - Tables and columns.
28
+ - Views and materialized views.
29
+ - Sequences, enums, and domains.
30
+ - Collations.
31
+ - Triggers and routines.
32
+ - Partitions and row-level policies.
33
+ - Extension objects.
34
+ - Comments and ownership metadata.
35
+
36
+ When a reader cannot fully describe an observed object, it retains a deferred
37
+ or opaque record. The record can keep catalog data and SQL text, along with
38
+ their source and dialect metadata. The object remains visible for review.
39
+
40
+ ## Names and identities
28
41
 
29
42
  Physical names and references describe the current database. Stable logical
30
43
  IDs are evidence selected by the adapter's identity policy. PostgreSQL OIDs,
@@ -49,6 +62,8 @@ strictly validated. Arrays are ordered by logical ID (with ordinal sequences
49
62
  and index terms ordered by their semantic position), and the fingerprint is computed
50
63
  from the deterministic encoding.
51
64
 
65
+ ### References to nested objects
66
+
52
67
  Normalized references to nested catalog objects retain their owner scope. A
53
68
  table-local index or constraint reference is mapped with
54
69
  `owner: { kind: "table", id }`; view columns use the view kind and ID; domain
@@ -57,6 +72,8 @@ catalog entity references is converted to that owner form at the Snapshot v1
57
72
  boundary. Top-level references have no owner. This scope prevents equal child
58
73
  IDs from different tables or object families from overwriting one another.
59
74
 
75
+ ### Opaque data and validation
76
+
60
77
  Catalog extension payloads and configuration records are opaque JSON. Their
61
78
  keys and values are preserved through normalization and canonical encoding;
62
79
  objects inside those payloads are not treated as Snapshot expressions or