@syncular/typegen 0.15.39 → 0.15.42

package/README.md

@@ -148,12 +148,20 @@ silently invent a value for them. `baseline`, `migrations check`, and
 `generate` therefore reject `ALTER TABLE … ADD COLUMN … NOT NULL`, including
 one with a literal default.
 
-Use an expand/backfill/validate rollout instead: add the trailing column as
+### Data changes and backfills
+
+Migration SQL is schema-only. `UPDATE`, `INSERT`, and `DELETE` do not mutate
+accepted Syncular row payloads and are rejected before their inner SQL is
+parsed, with a diagnostic linking to this rollout contract. Keep the old
+representation available until the new one is proven complete.
+
+Use an expand/backfill/validate/retire rollout instead: add the trailing column as
 nullable; deploy that schema; fill existing rows with versioned,
 server-authoritative writes under a new idempotency key; then enforce the
-required value in host validation. Do not tighten the synced column's
-nullability in a later migration. `generate` appends a valid new migration to
-the lock, while
+required value in host validation. Validate the backfill and every supported
+client before retiring an old column or table in a later schema version. Do not
+tighten the synced column's nullability in a later migration. `generate`
+appends a valid new migration to the lock, while
 `generate --check` fails until that updated lock and generated outputs are
 committed. Drift diagnostics name the locked migration and the first affected
 table/column without printing SQL or local paths.

package/dist/sql.js

@@ -54,6 +54,8 @@ const DEFAULT_CRDT_TYPE = 'yjs-doc';
 const WORD_START = /[\p{L}_]/u;
 const WORD_PART = /[\p{L}\p{M}\p{N}_]/u;
 const DIGIT = /[0-9]/;
+const DATA_MUTATION_STATEMENTS = new Set(['UPDATE', 'INSERT', 'DELETE']);
+const DATA_MUTATION_GUIDANCE = 'Syncular migration SQL is schema-only: retain the old representation, deploy a nullable expansion, backfill through versioned server-authoritative Syncular writes under a new idempotency key, validate future writes, then retire the old representation in a later schema version. See https://syncular.dev/guide-schema/#data-changes-and-backfills';
 const tableIdentifierSources = new WeakMap();
 const columnIdentifierSources = new WeakMap();
 const indexIdentifierSources = new WeakMap();
@@ -139,7 +141,12 @@ function tokenizeStatements(sql, source) {
             let end = i + 1;
             while (end < sql.length && WORD_PART.test(sql[end]))
                 end += 1;
-            current.push({ kind: 'word', text: sql.slice(i, end) });
+            const text = sql.slice(i, end);
+            current.push({ kind: 'word', text });
+            const statementKind = text.toUpperCase();
+            if (current.length === 1 && DATA_MUTATION_STATEMENTS.has(statementKind)) {
+                throw new TypegenError(source, `${statementKind} data migration is unsupported. ${DATA_MUTATION_GUIDANCE}`);
+            }
             i = end;
         }
         else if (DIGIT.test(ch)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/typegen",
-  "version": "0.15.39",
+  "version": "0.15.42",
   "description": "Syncular schema-to-TypeScript type generator and the `syncular` CLI",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -56,9 +56,9 @@
     "!dist/**/*.test.d.ts"
   ],
   "dependencies": {
-    "@syncular/core": "0.15.39"
+    "@syncular/core": "0.15.42"
   },
   "devDependencies": {
-    "@syncular/server": "0.15.39"
+    "@syncular/server": "0.15.42"
   }
 }

package/src/sql.ts

@@ -73,6 +73,9 @@ interface Token {
 const WORD_START = /[\p{L}_]/u;
 const WORD_PART = /[\p{L}\p{M}\p{N}_]/u;
 const DIGIT = /[0-9]/;
+const DATA_MUTATION_STATEMENTS = new Set(['UPDATE', 'INSERT', 'DELETE']);
+const DATA_MUTATION_GUIDANCE =
+  'Syncular migration SQL is schema-only: retain the old representation, deploy a nullable expansion, backfill through versioned server-authoritative Syncular writes under a new idempotency key, validate future writes, then retire the old representation in a later schema version. See https://syncular.dev/guide-schema/#data-changes-and-backfills';
 
 const tableIdentifierSources = new WeakMap<ParsedTable, string>();
 const columnIdentifierSources = new WeakMap<IrColumn, string>();
@@ -170,7 +173,15 @@ function tokenizeStatements(sql: string, source: string): Token[][] {
     } else if (WORD_START.test(ch)) {
       let end = i + 1;
       while (end < sql.length && WORD_PART.test(sql[end] as string)) end += 1;
-      current.push({ kind: 'word', text: sql.slice(i, end) });
+      const text = sql.slice(i, end);
+      current.push({ kind: 'word', text });
+      const statementKind = text.toUpperCase();
+      if (current.length === 1 && DATA_MUTATION_STATEMENTS.has(statementKind)) {
+        throw new TypegenError(
+          source,
+          `${statementKind} data migration is unsupported. ${DATA_MUTATION_GUIDANCE}`,
+        );
+      }
       i = end;
     } else if (DIGIT.test(ch)) {
       let end = i + 1;