qubu 0.6.2 → 0.6.3
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.
- package/dist/mysql.d.mts +1 -1
- package/dist/postgres.d.mts +1 -1
- package/docs/dialects-and-execution.md +54 -25
- package/docs/getting-started.md +9 -9
- package/docs/guides/better-auth.md +16 -5
- package/docs/guides/compose-queries.md +21 -9
- package/docs/guides/drizzle.md +8 -3
- package/docs/guides/extensions/dialects.md +1 -1
- package/docs/guides/extensions/overview.md +1 -1
- package/docs/guides/extensions/sources-and-clauses.md +7 -3
- package/docs/guides/extensions/typed-expressions.md +25 -13
- package/docs/guides/extensions/unsafe-syntax.md +10 -6
- package/docs/guides/json.md +52 -27
- package/docs/guides/mutations.md +15 -6
- package/docs/guides/select/conditions.md +18 -11
- package/docs/guides/select/grouping-and-windows.md +5 -2
- package/docs/guides/select/ordering-and-pagination.md +5 -3
- package/docs/guides/select/overview.md +6 -3
- package/docs/guides/sql-templates.md +11 -5
- package/docs/guides/valtio-sync.md +11 -5
- package/docs/guides/vite-plugin.md +2 -2
- package/docs/index.md +24 -17
- package/docs/migrations/adapters.md +47 -19
- package/docs/migrations/artifacts-and-policy.md +49 -20
- package/docs/migrations/index.md +15 -8
- package/docs/migrations/lotta-adoption.md +16 -5
- package/docs/migrations/operations.md +29 -15
- package/docs/migrations/recovery.md +34 -17
- package/docs/query-model/fragments.md +13 -5
- package/docs/query-model/result-shapes.md +2 -2
- package/docs/query-model/source-scope.md +5 -3
- package/docs/reference/introspection-support.md +26 -19
- package/docs/reference/mysql-snapshot.md +19 -4
- package/docs/reference/postgres-snapshot.md +17 -4
- package/docs/reference/sqlite-snapshot.md +19 -2
- package/docs/reference/supported-surface.md +221 -85
- package/docs/schema/catalog-model.md +24 -7
- package/docs/schema/code-generation.md +40 -21
- package/docs/schema/columns-and-writes.md +21 -11
- package/docs/schema/constraints-and-indexes.md +12 -5
- package/docs/schema/ddl-emission.md +16 -5
- package/docs/schema/diff.md +12 -4
- package/docs/schema/introspection.md +47 -21
- package/docs/schema/migration-plans.md +18 -10
- package/docs/schema/snapshots.md +57 -29
- package/docs/schema/storage-and-schema-sql.md +10 -4
- package/docs/schema/tables-and-names.md +1 -1
- package/docs/sql-semantic-types.md +11 -8
- package/docs/troubleshooting.md +14 -6
- package/package.json +1 -1
|
@@ -1,61 +1,73 @@
|
|
|
1
1
|
# Supported features
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> Find the right import and check what Qubu supports and what your application manages.
|
|
4
4
|
|
|
5
5
|
## Package entrypoints
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
|
10
|
-
|
|
|
11
|
-
| `qubu
|
|
12
|
-
| `qubu/
|
|
13
|
-
| `qubu/
|
|
14
|
-
| `qubu/
|
|
15
|
-
| `qubu/introspection
|
|
16
|
-
| `qubu/introspection/
|
|
17
|
-
| `qubu/
|
|
18
|
-
| `qubu/
|
|
19
|
-
| `qubu/
|
|
20
|
-
| `qubu/
|
|
21
|
-
| `qubu/
|
|
22
|
-
| `qubu/snapshot
|
|
23
|
-
| `qubu/snapshot/
|
|
24
|
-
| `qubu/
|
|
25
|
-
| `qubu/
|
|
26
|
-
| `qubu/
|
|
27
|
-
|
|
|
28
|
-
|
|
|
29
|
-
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
|
34
|
-
|
|
|
35
|
-
| `@qubu/migrate
|
|
36
|
-
| `@qubu/migrate/
|
|
37
|
-
| `@qubu/migrate/
|
|
38
|
-
| `@qubu/migrate/
|
|
39
|
-
| `@qubu/migrate/
|
|
40
|
-
| `@qubu/migrate/
|
|
41
|
-
| `@qubu/migrate/
|
|
42
|
-
| `@qubu/migrate/
|
|
43
|
-
| `@qubu/migrate/
|
|
44
|
-
| `@qubu/migrate/
|
|
45
|
-
| `@qubu/migrate/
|
|
46
|
-
| `@qubu/migrate/
|
|
47
|
-
| `@qubu/
|
|
48
|
-
| `@qubu/
|
|
49
|
-
| `@qubu/
|
|
50
|
-
| `@qubu/
|
|
51
|
-
| `@qubu/
|
|
52
|
-
| `@qubu/
|
|
53
|
-
| `@qubu/
|
|
54
|
-
| `@qubu/
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
|
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 | Strict live 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
|
|
70
|
-
|
|
71
|
-
`
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
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
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
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
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
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
|
|
@@ -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
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
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
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Generate a schema from introspection
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> Generate a TypeScript schema module from a complete introspection result with no omitted facts.
|
|
4
4
|
|
|
5
5
|
Source generation is an optional capability exported from `qubu/codegen`. It
|
|
6
6
|
is a pure handoff after introspection: it opens no connection, runs no catalog
|
|
@@ -33,12 +33,20 @@ returns data. A successful result contains deterministic `source` and every
|
|
|
33
33
|
retained diagnostic. A failed result contains diagnostics and no partial
|
|
34
34
|
source.
|
|
35
35
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
36
|
+
### What the module contains
|
|
37
|
+
|
|
38
|
+
The module exports each ordinary Snapshot v1 table and one schema registry. It
|
|
39
|
+
reconstructs:
|
|
40
|
+
|
|
41
|
+
- Physical names and exact native storage.
|
|
42
|
+
- Column write behavior and defaults.
|
|
43
|
+
- Generated-column and identity metadata.
|
|
44
|
+
- Constraints and indexes.
|
|
45
|
+
- Opaque predicates and expressions.
|
|
46
|
+
- Dialect extensions.
|
|
47
|
+
|
|
48
|
+
Checks use `catalogCheck()`. Foreign keys use lazy `catalogForeignKey()` targets
|
|
49
|
+
so forward declarations and cycles remain valid.
|
|
42
50
|
|
|
43
51
|
## Adopt the generated identity baseline
|
|
44
52
|
|
|
@@ -100,11 +108,15 @@ diagnostics and no source.
|
|
|
100
108
|
|
|
101
109
|
## Diagnostics and source safety
|
|
102
110
|
|
|
103
|
-
Generation
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
111
|
+
Generation fails when the input contains:
|
|
112
|
+
|
|
113
|
+
- Failed or lossy introspection.
|
|
114
|
+
- An edited snapshot that no longer matches its catalog.
|
|
115
|
+
- Omitted Snapshot v1 facts or unresolved references.
|
|
116
|
+
- Unsafe names or invalid mapping tokens.
|
|
117
|
+
- Data that cannot be printed safely as source.
|
|
118
|
+
|
|
119
|
+
Existing introspection diagnostics stay attached to the result.
|
|
108
120
|
|
|
109
121
|
> [!IMPORTANT]
|
|
110
122
|
> A database can allow a foreign key to reference a nullable `UNIQUE`
|
|
@@ -126,15 +138,22 @@ result contracts.
|
|
|
126
138
|
|
|
127
139
|
## Snapshot v1 boundary
|
|
128
140
|
|
|
129
|
-
Generation covers ordinary Snapshot v1 tables in one namespace.
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
141
|
+
Generation covers ordinary Snapshot v1 tables in one namespace. It does not emit:
|
|
142
|
+
|
|
143
|
+
- Views and materialized views.
|
|
144
|
+
- Sequences, enums, and domains.
|
|
145
|
+
- Routines and triggers.
|
|
146
|
+
- Partitions and policies.
|
|
147
|
+
- Collations and extensions.
|
|
148
|
+
- Comments and ownership.
|
|
149
|
+
- Retained opaque or deferred objects.
|
|
150
|
+
|
|
151
|
+
If any excluded family is non-empty, generation reports diagnostics rather than
|
|
152
|
+
presenting the module as complete.
|
|
153
|
+
|
|
154
|
+
The caller handles file writes and driver integration. Generation does not
|
|
155
|
+
merge hand edits or run migrations.
|
|
135
156
|
|
|
136
|
-
|
|
137
|
-
integration, multiple namespaces, runtime schema materialization, migrations,
|
|
138
|
-
DDL, non-table object generation, or hand-edit merging. Use
|
|
157
|
+
Use
|
|
139
158
|
[Database introspection](introspection.md) for the catalog boundary and
|
|
140
159
|
[Canonical schema snapshots](snapshots.md) for the identity artifact.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Column behavior and write types
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> Choose the values a column returns and accepts, including defaults and generated values.
|
|
4
4
|
|
|
5
5
|
## Give each operation its own type
|
|
6
6
|
|
|
@@ -32,7 +32,7 @@ updates accept number | null.
|
|
|
32
32
|
|
|
33
33
|
## Describe defaults and generated columns
|
|
34
34
|
|
|
35
|
-
The
|
|
35
|
+
The `hasDefault` and `generated` flags describe which values writes accept. Use
|
|
36
36
|
complete metadata when schema tooling also needs the database fact:
|
|
37
37
|
|
|
38
38
|
```ts
|
|
@@ -60,15 +60,18 @@ Primitive values in `default` are canonical literals. Strings are never
|
|
|
60
60
|
interpreted as SQL, and booleans remain semantic values so each dialect can
|
|
61
61
|
choose its own spelling. Pass a branded deterministic schema expression
|
|
62
62
|
directly when the default is SQL, and use `unsafeSchemaSql()` only for trusted
|
|
63
|
-
syntax Qubu does not model.
|
|
64
|
-
|
|
65
|
-
|
|
63
|
+
syntax Qubu does not model.
|
|
64
|
+
|
|
65
|
+
Generated expressions record stored or virtual mode. An identity descriptor
|
|
66
|
+
stays separate because identity behavior is not an ordinary generated expression.
|
|
66
67
|
|
|
67
68
|
Complete defaults cannot be combined with generated or identity metadata.
|
|
68
69
|
Contradictory flags fail with a structured `ColumnBehaviorError`. Use
|
|
69
70
|
`externalDefault()` or `externalGeneratedColumn()` when another schema authority
|
|
70
71
|
owns the missing detail.
|
|
71
72
|
|
|
73
|
+
### Supply defaults at runtime
|
|
74
|
+
|
|
72
75
|
Use `defaultFn` when Qubu should supply an omitted insert value at runtime:
|
|
73
76
|
|
|
74
77
|
```ts
|
|
@@ -79,15 +82,22 @@ const sessions = table("sessions", {
|
|
|
79
82
|
|
|
80
83
|
Runtime defaults make the insert key optional and run once for each omitted
|
|
81
84
|
row value. They remain live column behavior: snapshots and emitted DDL do not
|
|
82
|
-
record a database default.
|
|
85
|
+
record a database default.
|
|
86
|
+
|
|
87
|
+
A column may declare both `default` and `defaultFn`;
|
|
83
88
|
Qubu writes use the runtime value while the database default remains available
|
|
84
89
|
to other clients.
|
|
85
90
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
+
### Check database-specific rules
|
|
92
|
+
|
|
93
|
+
Identity details stay on the identity descriptor:
|
|
94
|
+
|
|
95
|
+
- SQLite `autoIncrement` requires an exact `INTEGER` rowid alias that is the
|
|
96
|
+
sole column of a primary key.
|
|
97
|
+
- MySQL `AUTO_INCREMENT` is a column-level identity extension.
|
|
98
|
+
- MySQL `ON UPDATE` accepts a branded deterministic expression.
|
|
99
|
+
|
|
100
|
+
The database-specific restrictions are listed in the
|
|
91
101
|
[snapshot overview](snapshots.md) and its dialect matrices.
|
|
92
102
|
|
|
93
103
|
## Narrow an application type
|