@bockit/sequel 0.1.0 → 0.2.0

package/README.md

@@ -158,14 +158,50 @@ Collations, CHECKs, partial and expression indexes, vector and trigram indexes,
 - live in hand-written migration SQL, noted in a comment on their model;
 - appear in the committed extras snapshot, so a change to them shows in review.
 
+### Migrations managed by another tool
+
+If another tool manages your schema and migrations, set `externalMigrations: true`. sequel then only types your queries:
+
+```ts
+export default defineConfig({
+  externalMigrations: true,
+  queries: 'src/**/queries',
+  databases: { test: process.env.TEST_DATABASE_URL },
+})
+```
+
+- `generate` types queries against the test database as your other tool left it. It never migrates it, and that tool's history table there, such as `_prisma_migrations`, is fine. Migrate the test database with your tool first.
+- `check` checks only the generated modules: stale, missing or orphaned. It prints a line saying it skipped drift, lint, the extras snapshot and schema validation.
+- `generate --watch` watches only the query folders.
+- No schema folder or migrations are read, so `schema`, `migrations` and `snapshot` aren't needed, and are ignored if set. Only sqlc is fetched; `pg_dump` is still needed.
+- `validate`, `format`, `migrate …` and `extras` refuse, naming the setting.
+
+Remove the setting to have sequel manage the schema and migrations.
+
 ## Adopting sequel in a Prisma app
 
+Move queries first, and decide about migrations last. Prisma keeps the schema, the migrations and `@prisma/client` while you port, and the app runs on both in the meantime.
+
+### Queries first
+
+1. Write `sequel.config.ts` with `externalMigrations: true` (see [above](#migrations-managed-by-another-tool)). The schema stays as it is, `url` included, and Prisma keeps migrating every database, the test database too.
+2. Move queries to `.sql` files module by module, porting modules that share a transaction together. Run `sequel generate`, and add `sequel check` to your test script and CI.
+3. Hand-written SQL now does what Prisma Client did for you:
+   - **`@updatedAt`:** Prisma Client sets it on every create and update, and the column has no database default. Set `updated_at = now()` in every `INSERT` and `UPDATE`.
+   - **`@default(cuid())` and `@default(uuid())`:** Prisma Client makes the id, and the column has no database default. Your app supplies it as a parameter.
+   - **A missing row:** Prisma's `update` and `delete` throw `P2025`. A `:one` query returns `null`, and an `:execrows` query returns `0`, so check for them.
+   - **Unique violations:** Prisma's `P2002` is now `pg`'s error with `code` `'23505'`.
+   - **Nested writes and `$transaction([...])`:** Prisma ran these in a transaction implicitly. Now take a client from the pool, run `BEGIN`, pass that client to every query in the transaction, and `COMMIT` (or `ROLLBACK` on error).
+4. When the last query is ported, remove `@prisma/client` and the schema's `generator` block. Prisma's CLI still runs the migrations.
+
+### Then migrations, if sequel is to run them
+
 1. Split `schema.prisma` into a folder, and remove `url` from the `datasource` block.
-2. Write `sequel.config.ts`. Set the lint cut-over to your newest existing migration.
+2. In `sequel.config.ts`, remove `externalMigrations`, and set `schema`, `migrations`, `snapshot` and the target database. Set the lint cut-over to your newest existing migration.
 3. Run `sequel migrate adopt-prisma` and commit the renamed files. Their contents don't change, so their checksums still match.
 4. Run `sequel migrate adopt-prisma` once against every database: production, each developer's, and the test database. It creates sequel's history from `_prisma_migrations`, checking every checksum, and leaves that table untouched. Until then, `deploy` refuses that database.
 5. Run `sequel extras`, and commit the snapshot.
-6. Move queries to `.sql` files module by module, porting modules that share a transaction together. Then remove `@prisma/client`, `prisma` and their install hooks.
+6. Remove `prisma` and its install hooks.
 7. In VS Code's Prisma extension, which still formats and validates offline, turn off the "Generate" CodeLens and the Prisma Client file watcher.
 
 ## Status

package/dist/check.js

@@ -15,10 +15,9 @@ import { unsupportedColumns } from './schema/unsupported.js';
 // SPEC §3's `check`: brings the test database up to the latest migration, then runs every check
 // and returns every failure, in SPEC's order. It writes no files. A check that can't run because
 // an earlier one failed (drift needs a valid schema, say) is skipped, and the earlier failure
-// says why.
+// says why. With external migrations it checks only the generated modules (SPEC §2).
 export async function runChecks(config, log) {
     const testUrl = requireDatabase(config, 'test');
-    const shown = (file) => path.relative(config.root, file);
     const failures = [];
     const fail = (order, failure) => failures.push({ order, failure });
     const expected = async (order, problem, fix, body) => {
@@ -32,6 +31,14 @@ export async function runChecks(config, log) {
             return undefined;
         }
     };
+    // With external migrations, the test database is as the other tool left it, and only the
+    // generated modules are checked. The skip is said, never silent.
+    if (config.externalMigrations) {
+        log(`Skipped drift, lint, the extras snapshot and schema validation: this app's migrations are managed elsewhere (\`externalMigrations\` in ${path.basename(config.configFile)}).`);
+        await checkGeneratedModules(config, testUrl, expected, (failure) => fail(1, failure));
+        return failures.map((entry) => entry.failure);
+    }
+    const shown = (file) => path.relative(config.root, file);
     // The schema folder.
     const files = await expected(5, "The schema folder can't be read", "Fix the config's `schema`, then run `sequel check` again.", () => readSchemaFiles(config.schema, config.root));
     let schemaValid = false;
@@ -55,29 +62,8 @@ export async function runChecks(config, log) {
             return true;
         })) === true;
     // 1. Generated modules.
-    if (deployed) {
-        const modules = await expected(1, "The query modules can't be generated", 'Fix the queries named. `sequel generate` reports the same errors.', async () => checkModules({
-            sqlc: await ensureBinary('sqlc'),
-            databaseUrl: testUrl,
-            folders: await findQueryFolders(config.queries),
-            bigint: config.types.bigint,
-            root: config.root,
-        }));
-        if (modules !== undefined) {
-            const details = [
-                ...modules.stale.map((file) => `stale: ${shown(file)}`),
-                ...modules.missing.map((file) => `missing: ${shown(file)}`),
-                ...modules.orphaned.map((file) => `orphaned: ${shown(file)} (its query file is gone)`),
-            ];
-            if (details.length > 0) {
-                fail(1, {
-                    problem: 'Generated modules are out of date',
-                    details,
-                    fix: 'Run `sequel generate`, and commit the result.',
-                });
-            }
-        }
-    }
+    if (deployed)
+        await checkGeneratedModules(config, testUrl, expected, (failure) => fail(1, failure));
     // 2. Drift.
     if (migrations !== undefined && files !== undefined && schemaValid) {
         const diff = await expected(2, "Drift between the migrations and the schema folder can't be checked", 'Fix the problem named, then run `sequel check` again.', () => diffMigrationsToSchema({ config, migrations, files }));
@@ -121,6 +107,32 @@ export async function runChecks(config, log) {
     }
     return failures.sort((a, b) => a.order - b.order).map((entry) => entry.failure);
 }
+// Generates the modules as `generate` would, against the test database as it stands, and
+// compares them with the modules in place: stale, missing or orphaned.
+async function checkGeneratedModules(config, testUrl, expected, fail) {
+    const shown = (file) => path.relative(config.root, file);
+    const modules = await expected(1, "The query modules can't be generated", 'Fix the queries named. `sequel generate` reports the same errors.', async () => checkModules({
+        sqlc: await ensureBinary('sqlc'),
+        databaseUrl: testUrl,
+        folders: await findQueryFolders(config.queries),
+        bigint: config.types.bigint,
+        root: config.root,
+    }));
+    if (modules === undefined)
+        return;
+    const details = [
+        ...modules.stale.map((file) => `stale: ${shown(file)}`),
+        ...modules.missing.map((file) => `missing: ${shown(file)}`),
+        ...modules.orphaned.map((file) => `orphaned: ${shown(file)} (its query file is gone)`),
+    ];
+    if (details.length > 0) {
+        fail({
+            problem: 'Generated modules are out of date',
+            details,
+            fix: 'Run `sequel generate`, and commit the result.',
+        });
+    }
+}
 // The lines that differ, from a longest-common-subsequence diff: `-` for the snapshot as
 // committed, `+` for the database. Snapshots are small, so the quadratic table is fine.
 export function lineChanges(current, next) {

package/dist/cli.js

@@ -28,7 +28,7 @@ const OPTIONS = {
     'allow-out-of-order': { type: 'boolean' },
 };
 async function validate(context) {
-    const config = await load(context);
+    const config = await loadManaged(context);
     const files = await readSchemaFiles(config.schema, config.root);
     assertValidSchema(files, config.root);
     for (const warning of schemaWarnings(files, config.root)) {
@@ -37,7 +37,7 @@ async function validate(context) {
     out(`The schema is valid: ${plural(files.length, 'file')} in ${shown(config, config.schema)}.`);
 }
 async function format(context) {
-    const config = await load(context);
+    const config = await loadManaged(context);
     const changed = await formatSchemaFiles(await readSchemaFiles(config.schema, config.root), config.root);
     for (const file of changed)
         out(`Formatted ${shown(config, file)}`);
@@ -45,7 +45,7 @@ async function format(context) {
         out(`The schema is already formatted.`);
 }
 async function migrateNew(context) {
-    const config = await load(context);
+    const config = await loadManaged(context);
     const { file, findings } = await newMigration({ config, name: context.positionals[0] });
     if (file === undefined) {
         out('The migrations already match the schema: no migration written.');
@@ -58,7 +58,7 @@ async function migrateNew(context) {
     out('Lint: no findings.');
 }
 async function migrateLint(context) {
-    const config = await load(context);
+    const config = await loadManaged(context);
     const migrations = context.positionals.length > 0
         ? await Promise.all(context.positionals.map(async (given) => {
             const file = path.resolve(given);
@@ -84,7 +84,7 @@ async function migrateLint(context) {
     out(`${plural(migrations.length, 'migration file')} linted: no findings.`);
 }
 async function migrateAdoptPrisma(context) {
-    const config = await load(context);
+    const config = await loadManaged(context);
     const url = requireDatabase(config, 'target');
     const files = await adoptPrismaFiles(config.migrations, config.root);
     for (const { from, to } of files.renamed) {
@@ -113,7 +113,7 @@ async function migrateAdoptPrisma(context) {
     }
 }
 async function migrateDeploy(context) {
-    const config = await load(context);
+    const config = await loadManaged(context);
     await deployTo(config, requireDatabase(config, 'target'), {
         allowOutOfOrder: context.flags['allow-out-of-order'],
         log: out,
@@ -123,7 +123,10 @@ async function generate(context) {
     const config = await load(context);
     const url = requireDatabase(config, 'test');
     const once = async () => {
-        await deployTo(config, url, { log: out, quietWhenCurrent: true });
+        // With external migrations, the test database is typed as the other tool left it.
+        if (!config.externalMigrations) {
+            await deployTo(config, url, { log: out, quietWhenCurrent: true });
+        }
         const folders = await findQueryFolders(config.queries);
         const result = await generateModules({
             sqlc: await ensureBinary('sqlc'),
@@ -147,7 +150,9 @@ async function generate(context) {
     const stop = new AbortController();
     process.once('SIGINT', () => stop.abort());
     process.once('SIGTERM', () => stop.abort());
-    const folders = [...(await findQueryFolders(config.queries)), config.migrations];
+    const folders = await findQueryFolders(config.queries);
+    if (!config.externalMigrations)
+        folders.push(config.migrations);
     await watchAndRerun({
         folders,
         run: once,
@@ -156,7 +161,7 @@ async function generate(context) {
     });
 }
 async function extras(context) {
-    const config = await load(context);
+    const config = await loadManaged(context);
     const url = requireDatabase(config, 'test');
     await deployTo(config, url, { log: out, quietWhenCurrent: true });
     const next = await readExtrasSnapshot(url);
@@ -179,6 +184,15 @@ async function check(context) {
 function load(context) {
     return loadConfig({ config: context.config });
 }
+// For the commands that act on the schema, the migrations or the extras snapshot: they refuse
+// when another tool manages them, before connecting, reading a file or fetching a binary.
+async function loadManaged(context) {
+    const config = await load(context);
+    if (config.externalMigrations) {
+        throw new SequelError(`\`sequel ${context.name}\` is off: ${path.basename(config.configFile)} sets \`externalMigrations\`, so another tool manages this app's schema and migrations, and sequel only types its queries. To have sequel manage them, remove \`externalMigrations\`.`);
+    }
+    return config;
+}
 function shown(config, file) {
     return path.relative(config.root, file) || '.';
 }
@@ -301,6 +315,7 @@ async function main(argv) {
         throw new SequelError(`Usage: sequel ${command.usage}`);
     }
     await command.run({
+        name,
         config: values.config,
         positionals: args,
         flags: {

package/dist/config/define-config.d.ts

@@ -18,6 +18,7 @@ export type SequelConfig = {
     types?: {
         bigint?: BigintMode;
     };
+    externalMigrations?: boolean;
 };
 export type BigintMode = 'string' | 'number' | 'bigint';
 export declare function defineConfig(config: SequelConfig): SequelConfig;

package/dist/config/resolve-config.d.ts

@@ -18,6 +18,7 @@ export type ResolvedConfig = {
     types: {
         bigint: BigintMode;
     };
+    externalMigrations: boolean;
 };
 export declare const DEFAULTS: {
     readonly schema: 'prisma';

package/dist/config/resolve-config.js

@@ -9,7 +9,17 @@ export const DEFAULTS = {
     bigint: 'string',
 };
 const KEYS = {
-    '': ['schema', 'migrations', 'queries', 'snapshot', 'databases', 'timeouts', 'lint', 'types'],
+    '': [
+        'schema',
+        'migrations',
+        'queries',
+        'snapshot',
+        'databases',
+        'timeouts',
+        'lint',
+        'types',
+        'externalMigrations',
+    ],
     databases: ['target', 'test', 'shadow'],
     timeouts: ['lockMs', 'statementMs'],
     lint: ['cutover'],
@@ -60,6 +70,10 @@ export function resolveConfig(value, configFile) {
     if (!BIGINT_MODES.includes(bigint)) {
         fail('types.bigint', `must be one of ${BIGINT_MODES.map((m) => `'${m}'`).join(', ')}.`);
     }
+    const external = config.externalMigrations ?? false;
+    if (typeof external !== 'boolean') {
+        fail('externalMigrations', 'must be `true` or `false`: `true` when another tool manages the schema and migrations.');
+    }
     return {
         configFile,
         root,
@@ -75,6 +89,7 @@ export function resolveConfig(value, configFile) {
         },
         lint: { cutover: cutover },
         types: { bigint: bigint },
+        externalMigrations: external,
     };
 }
 // Returns the connection string for a database a command needs, or explains how to set it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bockit/sequel",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "One CLI for a TypeScript app's Postgres data layer: Prisma schema, reviewed SQL migrations, typed SQL queries.",
   "license": "Apache-2.0",
   "repository": {