@abgov/nx-adsp 13.23.1 → 13.24.0

package/migrations.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "generators": {
+    "add-migrate-advisory-lock": {
+      "version": "13.24.0",
+      "description": "Wrap express-service's generated src/migrate.ts drizzle migrate() call in a Postgres advisory lock, so concurrent init containers serialize instead of racing.",
+      "implementation": "./src/migrations/add-migrate-advisory-lock/add-migrate-advisory-lock",
+      "prompt": "./src/migrations/add-migrate-advisory-lock/add-migrate-advisory-lock.md"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abgov/nx-adsp",
-  "version": "13.23.1",
+  "version": "13.24.0",
   "license": "Apache-2.0",
   "main": "src/index.js",
   "description": "Government of Alberta - Nx plugin for ADSP apps.",
@@ -41,6 +41,9 @@
     "socket.io-client": "^4.8.3"
   },
   "generators": "./generators.json",
+  "nx-migrations": {
+    "migrations": "./migrations.json"
+  },
   "scripts": {},
   "types": "./src/index.d.ts",
   "type": "commonjs"

package/src/build-assets.spec.ts

@@ -59,4 +59,78 @@ describe('build assets packaging', () => {
 
     expect(unmatched).toEqual([]);
   });
+
+  // The same boundary one level up. A migration is only reachable if
+  // package.json declares the registry and project.json ships it — and the
+  // migration's own unit tests resolve everything from the source tree, so they
+  // pass either way. Nothing else catches a migration that publishes inert.
+  it('ships the migrations registry declared in package.json', () => {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf-8'),
+    );
+    const registry: string | undefined = pkg['nx-migrations']?.migrations;
+    expect(registry).toBeDefined();
+
+    const registryPath = path.join(projectRoot, registry as string);
+    expect(fs.existsSync(registryPath)).toBe(true);
+
+    const project = JSON.parse(
+      fs.readFileSync(path.join(projectRoot, 'project.json'), 'utf-8'),
+    );
+    const assets: unknown[] = project.targets.build.options.assets ?? [];
+    const rootGlobs = assets
+      .filter(
+        (a): a is { input: string; glob: string } =>
+          typeof a === 'object' &&
+          a !== null &&
+          'input' in a &&
+          path.resolve(repoRoot, (a as { input: string }).input) ===
+            path.resolve(projectRoot),
+      )
+      .map((a) => a.glob);
+
+    const rel = path.relative(projectRoot, registryPath);
+    expect(rootGlobs.some((glob) => minimatch(rel, glob, { dot: true }))).toBe(
+      true,
+    );
+  });
+
+  // Every file a migration names must resolve, or `nx migrate` fails at run
+  // time in the consumer's workspace rather than here. `prompt` is the markdown
+  // handed to the paired AI step; Nx resolves it relative to migrations.json
+  // (not through package exports), and requires at least one of implementation,
+  // factory, or prompt per entry.
+  it('points every migration at files that exist', () => {
+    const registry = JSON.parse(
+      fs.readFileSync(path.join(projectRoot, 'migrations.json'), 'utf-8'),
+    );
+    const entries: [
+      string,
+      { implementation?: string; factory?: string; prompt?: string },
+    ][] = Object.entries(registry.generators ?? {});
+    expect(entries.length).toBeGreaterThan(0);
+
+    const problems: string[] = [];
+    for (const [name, entry] of entries) {
+      if (!entry.implementation && !entry.factory && !entry.prompt) {
+        problems.push(`${name}: needs implementation, factory, or prompt`);
+      }
+      if (
+        entry.implementation &&
+        !fs.existsSync(path.join(projectRoot, `${entry.implementation}.ts`))
+      ) {
+        problems.push(`${name}: implementation not found`);
+      }
+      // Referenced verbatim, extension included — unlike implementation, which
+      // Nx resolves without one.
+      if (
+        entry.prompt &&
+        !fs.existsSync(path.join(projectRoot, entry.prompt))
+      ) {
+        problems.push(`${name}: prompt not found`);
+      }
+    }
+
+    expect(problems).toEqual([]);
+  });
 });

package/src/migrations/add-migrate-advisory-lock/add-migrate-advisory-lock.d.ts

@@ -0,0 +1,7 @@
+import { Tree } from '@nx/devkit';
+interface MigrationReport {
+    nextSteps: string[];
+    agentContext: string[];
+}
+export default function addMigrateAdvisoryLock(tree: Tree): Promise<MigrationReport | undefined>;
+export {};

package/src/migrations/add-migrate-advisory-lock/add-migrate-advisory-lock.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = addMigrateAdvisoryLock;
+const tslib_1 = require("tslib");
+const devkit_1 = require("@nx/devkit");
+const fs_1 = require("fs");
+const path_1 = require("path");
+// express-service's generated migration runner, verbatim, either side of the
+// advisory-lock fix — as the generator actually emits it, i.e. after
+// formatFiles(). That differs from the files-postgres template itself, whose
+// .ts__tmpl__ extension Prettier doesn't recognise and so never formats; the
+// generated file is what this migration reads and writes, so it's the generated
+// file that gets captured here.
+//
+// Held as fixtures rather than read from the live template because a migration
+// has to keep applying the same change forever: sourcing from the template would
+// mean a later edit to it silently changed what this already-released migration
+// does.
+const BEFORE_PATH = (0, path_1.join)(__dirname, 'migrate.before.txt');
+const AFTER_PATH = (0, path_1.join)(__dirname, 'migrate.after.txt');
+const MIGRATE_PATH = 'src/migrate.ts';
+const DRIZZLE_MIGRATOR = 'drizzle-orm/node-postgres/migrator';
+// What the rewrite must contain to be the rewrite at all. The asset glob in
+// project.json is the only thing putting the fixtures in the published package,
+// so a mis-scoped glob would otherwise overwrite every matching migrate.ts with
+// nothing — checked once, loudly, instead of trusted.
+const REQUIRED_MARKERS = [
+    'MIGRATION_LOCK_KEY',
+    'pg_advisory_lock',
+    'pg_advisory_unlock',
+    'lockClient.release()',
+];
+// Compared after normalising only line endings and trailing whitespace — the
+// noise git and editors introduce, which cannot hide a meaningful change.
+//
+// Deliberately NOT a general source normaliser. Tolerating arbitrary
+// reformatting is either a half-measure that silently misses cases (collapsing
+// whitespace handles a wrapped argument list but not the spaces Prettier puts
+// inside the parens of a wrapped `if`, nor the trailing comma it adds) or
+// aggressive enough to risk matching a file that isn't the generated one. A
+// workspace whose own Prettier reformatted this file gets a warning naming it
+// instead — the safe direction, since we only rewrite a file we can positively
+// identify. In practice `create-nx-workspace` writes the same
+// `{ "singleQuote": true }` config this repo uses, so the generated file is
+// byte-identical for all but a deliberately customised setup.
+function normalize(content) {
+    return content
+        .replace(/\r\n/g, '\n')
+        .replace(/[ \t]+$/gm, '')
+        .trimEnd();
+}
+function addMigrateAdvisoryLock(tree) {
+    return tslib_1.__awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const before = (0, fs_1.readFileSync)(BEFORE_PATH, 'utf-8');
+        const after = (0, fs_1.readFileSync)(AFTER_PATH, 'utf-8');
+        const missing = REQUIRED_MARKERS.filter((marker) => !after.includes(marker));
+        if (missing.length > 0) {
+            throw new Error(`[nx-adsp] ${AFTER_PATH} is missing ${missing.join(', ')} — the packaged ` +
+                `migration fixture is incomplete, so nothing was rewritten. This is a ` +
+                `packaging bug in @abgov/nx-adsp, not a problem with your workspace.`);
+        }
+        // The other fixture fails safe (nothing matches, so nothing is rewritten),
+        // but silently and with a warning per project — check it too so a truncated
+        // asset reports itself rather than looking like every service was customised.
+        if (!before.includes(DRIZZLE_MIGRATOR) ||
+            before.includes('pg_advisory_lock')) {
+            throw new Error(`[nx-adsp] ${BEFORE_PATH} is not the pre-fix migration runner — the ` +
+                `packaged migration fixture is wrong, so nothing was rewritten. This ` +
+                `is a packaging bug in @abgov/nx-adsp, not a problem with your workspace.`);
+        }
+        let updated = 0;
+        const skipped = [];
+        for (const [name, project] of (0, devkit_1.getProjects)(tree)) {
+            const migratePath = (0, devkit_1.joinPathFragments)(project.root, MIGRATE_PATH);
+            if (!tree.exists(migratePath)) {
+                continue;
+            }
+            const content = (_a = tree.read(migratePath, 'utf-8')) !== null && _a !== void 0 ? _a : '';
+            // Already serialized — by a newer generator, a previous run of this
+            // migration, or by hand.
+            if (content.includes('pg_advisory_lock')) {
+                continue;
+            }
+            // Not the file this migration is about: a hand-written runner, or a
+            // Prisma-era service from before the Drizzle switch.
+            if (!content.includes(DRIZZLE_MIGRATOR)) {
+                continue;
+            }
+            if (normalize(content) !== normalize(before)) {
+                // Warned per file so it appears inline next to this migration; the
+                // actionable instruction is carried once, in nextSteps, rather than
+                // repeated in full for every file.
+                devkit_1.logger.warn(`[nx-adsp] ${migratePath} (project "${name}") runs drizzle's migrate() with no ` +
+                    `advisory lock, but differs from the generated version — left untouched.`);
+                skipped.push(migratePath);
+                continue;
+            }
+            tree.write(migratePath, after);
+            updated++;
+        }
+        if (updated > 0) {
+            yield (0, devkit_1.formatFiles)(tree);
+            devkit_1.logger.info(`[nx-adsp] Serialized ${updated} generated migrate.ts file(s) with a Postgres advisory lock.`);
+        }
+        if (skipped.length === 0) {
+            return undefined;
+        }
+        return {
+            nextSteps: [
+                `${skipped.length} migration runner(s) still race concurrent init containers: ` +
+                    `${skipped.join(', ')}. Each runs drizzle's migrate() with no advisory lock but ` +
+                    `differs from the generated file, so it was left untouched rather than pattern-edited. ` +
+                    `Wrap each migrate() call in pg_advisory_lock/pg_advisory_unlock on a dedicated ` +
+                    `pool.connect() client, keeping whatever else the file customises — ` +
+                    `express-service's files-postgres/src/migrate.ts template is the reference.`,
+            ],
+            agentContext: skipped.map((path) => `${path} needs the advisory lock applied by hand: it calls drizzle's migrate() with ` +
+                `no pg_advisory_lock, and differs from the file this migration knows how to rewrite. ` +
+                `Preserve its existing customisations.`),
+        };
+    });
+}
+//# sourceMappingURL=add-migrate-advisory-lock.js.map

package/src/migrations/add-migrate-advisory-lock/add-migrate-advisory-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-migrate-advisory-lock.js","sourceRoot":"","sources":["../../../../../../packages/nx-adsp/src/migrations/add-migrate-advisory-lock/add-migrate-advisory-lock.ts"],"names":[],"mappings":"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"}

package/src/migrations/add-migrate-advisory-lock/add-migrate-advisory-lock.md

@@ -0,0 +1,99 @@
+# Apply the Postgres advisory lock to a customised `migrate.ts`
+
+The generator phase rewrote every `src/migrate.ts` it could identify as the
+unmodified file `@abgov/nx-adsp`'s `express-service` generated. It deliberately
+left alone any file that differs, rather than pattern-editing source it cannot
+positively identify. Finishing those files is this step's only job.
+
+## First, check whether there is anything to do
+
+Stop and make no changes if either of these holds:
+
+1. `<advisory_context>` is absent or lists no files. The generator phase either
+   rewrote everything or found nothing to rewrite. **This is the common case.**
+2. Every file it does list already contains `pg_advisory_lock`. Someone applied
+   the fix by hand; re-applying it would double-lock.
+
+Only the paths named in `<advisory_context>` are in scope. Do not search the
+workspace for other candidates, and do not touch a `migrate.ts` the generator
+phase already rewrote — `<generator_output>` and whichever change list Nx
+included above (`<inspect_changes>` or `<files_changed>`) show which those were.
+
+## Why this matters
+
+`drizzle-orm`'s `migrate()` has no protection against concurrent execution
+([drizzle-team/drizzle-orm#874], open, acknowledged upstream). It reads the
+last-applied migration with a plain `SELECT` before opening a transaction, so two
+replicas starting at once can both see "nothing applied yet" and both run the
+same migration. In a deployment this shows up as the second pod's init container
+stuck in `Init:CrashLoopBackOff` on an "already exists" error, while the first
+pod serves traffic normally — so it reads as a flaky deploy rather than a race.
+
+[drizzle-team/drizzle-orm#874]: https://github.com/drizzle-team/drizzle-orm/issues/874
+
+## What to change
+
+For each file in `<advisory_context>`, make these four edits and nothing else.
+
+1. A stable lock key alongside the existing module-level constants:
+
+   ```ts
+   const MIGRATION_LOCK_KEY = 8812345;
+   ```
+
+   Use exactly this value. Advisory locks are scoped per-database, not per
+   Postgres instance, so it only has to be unique within this app's own
+   database — and keeping it identical to the generated file means a service that
+   later regenerates does not end up with two different keys.
+
+2. A dedicated client for the lock, taken from the existing pool immediately
+   after it is created:
+
+   ```ts
+   const lockClient = await pool.connect();
+   ```
+
+   It must be its own connection. Taking the lock on a connection that
+   `migrate()` also uses can deadlock.
+
+3. Acquire the lock as the first statement inside the `try` that wraps
+   `migrate()`:
+
+   ```ts
+   await lockClient.query('SELECT pg_advisory_lock($1)', [MIGRATION_LOCK_KEY]);
+   ```
+
+4. Release it and return the client in the matching `finally`, before the pool
+   is closed:
+
+   ```ts
+   await lockClient.query('SELECT pg_advisory_unlock($1)', [MIGRATION_LOCK_KEY]);
+   lockClient.release();
+   ```
+
+Ordering is the whole point: a lock taken after `migrate()` serializes nothing,
+and one never released strands every later deploy. If the file's structure
+differs enough that these four edits do not map cleanly onto it — no `try`/
+`finally` around `migrate()`, no `Pool`, a different database client — do not
+force them. Leave the file unchanged and say so in your handoff.
+
+## Preserve what the file customises
+
+These files were skipped precisely because a team changed them. Keep every such
+change: a different `MIGRATIONS_FOLDER`, extra logging, a seed step, custom error
+handling, a different formatting style. Add the lock around what is already
+there; do not reformat the file, reorder its imports, or "restore" it toward the
+generated version.
+
+## Verify
+
+- The file still compiles: `npx nx build <project>` for the project that owns it
+  (`migrate.js` is a second webpack bundle emitted by that same build).
+- `pg_advisory_lock` appears before the `migrate()` call, and
+  `pg_advisory_unlock` plus `lockClient.release()` appear in the `finally`
+  before `pool.end()`.
+- The diff for each file contains only the four additions above.
+
+Do not attempt to run the migration against a real database; there is no
+Postgres to connect to here, and the lock's behaviour is already covered by
+`@abgov/nx-adsp`'s own tests.

package/src/migrations/add-migrate-advisory-lock/add-migrate-advisory-lock.spec.ts

@@ -0,0 +1,209 @@
+import { addProjectConfiguration, logger, Tree } from '@nx/devkit';
+import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import migration from './add-migrate-advisory-lock';
+
+// The real generated file, either side of the fix — not a synthetic
+// approximation of it. Turning the first into the second is the migration's
+// entire job, so these are the only fixtures that prove anything.
+const BEFORE = readFileSync(join(__dirname, 'migrate.before.txt'), 'utf-8');
+const AFTER = readFileSync(join(__dirname, 'migrate.after.txt'), 'utf-8');
+
+// The fixtures are the post-formatFiles generated form, so under this
+// workspace's own Prettier config the rewrite is byte-exact and the assertions
+// below can compare directly.
+
+function addService(host: Tree, name: string, migrateContent?: string): void {
+  addProjectConfiguration(host, name, { root: `apps/${name}` });
+  if (migrateContent !== undefined) {
+    host.write(`apps/${name}/src/migrate.ts`, migrateContent);
+  }
+}
+
+describe('nx-adsp add-migrate-advisory-lock migration', () => {
+  let host: Tree;
+  let warn: jest.SpyInstance;
+
+  beforeEach(() => {
+    host = createTreeWithEmptyWorkspace({ layout: 'apps-libs' });
+    warn = jest.spyOn(logger, 'warn').mockImplementation(() => undefined);
+    jest.spyOn(logger, 'info').mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('rewrites the generated pre-fix runner into the locked version', async () => {
+    addService(host, 'api', BEFORE);
+
+    await migration(host);
+
+    expect(host.read('apps/api/src/migrate.ts', 'utf-8')).toEqual(AFTER);
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('acquires the lock before migrating and releases it in the finally block', async () => {
+    addService(host, 'api', BEFORE);
+
+    await migration(host);
+
+    const result = host.read('apps/api/src/migrate.ts', 'utf-8');
+    // Ordering is the whole point — a lock taken after migrate() serializes
+    // nothing, and one never released strands every later deploy.
+    const lockAt = result.indexOf('pg_advisory_lock');
+    const migrateAt = result.indexOf('await migrate(');
+    const unlockAt = result.indexOf('pg_advisory_unlock');
+    const endAt = result.indexOf('await pool.end()');
+    expect(lockAt).toBeGreaterThan(-1);
+    expect(lockAt).toBeLessThan(migrateAt);
+    expect(migrateAt).toBeLessThan(unlockAt);
+    expect(unlockAt).toBeLessThan(endAt);
+    expect(result).toContain('lockClient.release()');
+  });
+
+  it('matches through CRLF line endings and trailing whitespace', async () => {
+    // git autocrlf and editor settings, not a change to the code.
+    addService(
+      host,
+      'api',
+      BEFORE.replace(/\n/g, '\r\n').replace(/\r\n/g, '  \r\n'),
+    );
+
+    await migration(host);
+
+    expect(host.read('apps/api/src/migrate.ts', 'utf-8')).toEqual(AFTER);
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('warns rather than rewriting when the file has been reformatted', async () => {
+    // A workspace whose Prettier uses a narrower print width wraps the `if`
+    // and the migrate() argument list. Semantically the generated file, but not
+    // one this migration can positively identify — so it says so instead of
+    // guessing. See normalize()'s own comment for why that is the safe
+    // direction.
+    const reformatted = BEFORE.replace(
+      '    await migrate(drizzle(pool), { migrationsFolder: MIGRATIONS_FOLDER });',
+      [
+        '    await migrate(drizzle(pool), {',
+        '      migrationsFolder: MIGRATIONS_FOLDER,',
+        '    });',
+      ].join('\n'),
+    );
+    addService(host, 'api', reformatted);
+
+    await migration(host);
+
+    expect(host.read('apps/api/src/migrate.ts', 'utf-8')).toEqual(reformatted);
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('apps/api/src/migrate.ts'),
+    );
+  });
+
+  it('leaves an already-locked runner byte-identical and silent', async () => {
+    addService(host, 'api', AFTER);
+
+    await migration(host);
+
+    expect(host.read('apps/api/src/migrate.ts', 'utf-8')).toEqual(AFTER);
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('is a no-op on a second run', async () => {
+    addService(host, 'api', BEFORE);
+
+    await migration(host);
+    const afterFirst = host.read('apps/api/src/migrate.ts', 'utf-8');
+    await migration(host);
+
+    expect(host.read('apps/api/src/migrate.ts', 'utf-8')).toEqual(afterFirst);
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('warns and leaves a customized runner alone rather than overwriting it', async () => {
+    const customized = BEFORE.replace(
+      "const MIGRATIONS_FOLDER = 'drizzle';",
+      "const MIGRATIONS_FOLDER = 'db/migrations';",
+    );
+    addService(host, 'api', customized);
+
+    await migration(host);
+
+    expect(host.read('apps/api/src/migrate.ts', 'utf-8')).toEqual(customized);
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('apps/api/src/migrate.ts'),
+    );
+  });
+
+  // Nx surfaces nextSteps in the run summary and hands agentContext to the
+  // paired prompt phase, so a skipped file has to reach both — the warning
+  // alone is easy to scroll past, and the prompt has nothing to work from
+  // without agentContext.
+  it('returns the skipped file in both nextSteps and agentContext', async () => {
+    const customized = BEFORE.replace(
+      "const MIGRATIONS_FOLDER = 'drizzle';",
+      "const MIGRATIONS_FOLDER = 'db/migrations';",
+    );
+    addService(host, 'api', customized);
+
+    const result = await migration(host);
+
+    expect(result).toBeDefined();
+    expect(result?.nextSteps).toHaveLength(1);
+    expect(result?.nextSteps[0]).toContain('apps/api/src/migrate.ts');
+    expect(result?.nextSteps[0]).toContain('pg_advisory_lock');
+    expect(result?.agentContext).toEqual([
+      expect.stringContaining('apps/api/src/migrate.ts'),
+    ]);
+  });
+
+  it('returns nothing when every file was rewritten or already correct', async () => {
+    addService(host, 'needs-fix', BEFORE);
+    addService(host, 'already-ok', AFTER);
+
+    await expect(migration(host)).resolves.toBeUndefined();
+  });
+
+  it('names every skipped file, not just the first', async () => {
+    const customized = BEFORE.replace('drizzle', 'db/migrations');
+    addService(host, 'one', customized);
+    addService(host, 'two', customized);
+
+    const result = await migration(host);
+
+    expect(result?.agentContext).toHaveLength(2);
+    expect(result?.nextSteps[0]).toContain('apps/one/src/migrate.ts');
+    expect(result?.nextSteps[0]).toContain('apps/two/src/migrate.ts');
+  });
+
+  it('ignores a migrate.ts that is not drizzle-based, without warning', async () => {
+    const unrelated = 'export function migrate() {\n  return null;\n}\n';
+    addService(host, 'legacy', unrelated);
+
+    await migration(host);
+
+    expect(host.read('apps/legacy/src/migrate.ts', 'utf-8')).toEqual(unrelated);
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('skips a project with no migrate.ts (mongo, or no database)', async () => {
+    addService(host, 'mongo-svc');
+
+    await expect(migration(host)).resolves.toBeUndefined();
+    expect(host.exists('apps/mongo-svc/src/migrate.ts')).toBe(false);
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('handles a mix of projects in one pass', async () => {
+    addService(host, 'needs-fix', BEFORE);
+    addService(host, 'already-ok', AFTER);
+    addService(host, 'no-db');
+
+    await migration(host);
+
+    expect(host.read('apps/needs-fix/src/migrate.ts', 'utf-8')).toEqual(AFTER);
+    expect(host.read('apps/already-ok/src/migrate.ts', 'utf-8')).toEqual(AFTER);
+    expect(warn).not.toHaveBeenCalled();
+  });
+});

package/src/migrations/add-migrate-advisory-lock/migrate.after.txt

@@ -0,0 +1,63 @@
+import { existsSync } from 'fs';
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { migrate } from 'drizzle-orm/node-postgres/migrator';
+import { Pool } from 'pg';
+
+const MIGRATIONS_FOLDER = 'drizzle';
+// Arbitrary, stable key — advisory locks are scoped per-database, not shared
+// across a Postgres instance (confirmed via the pg_locks documentation: "the
+// same advisory lock key can be held simultaneously in different databases
+// ... they don't conflict across DB boundaries"), so this only needs to be
+// unique within this app's own database, not across every app sharing a
+// sandbox Postgres instance.
+const MIGRATION_LOCK_KEY = 8812345;
+
+// Standalone migration runner — the deployment runs this as an init container
+// (`node migrate.js`) before the app starts. It uses only drizzle-orm + pg,
+// both runtime dependencies, so it survives `npm prune --omit=dev` and needs no
+// CLI or native engine in the image. The SQL files in ./drizzle are shipped as
+// build assets alongside this bundle.
+async function main() {
+  // A freshly generated service has no models yet, so there are no migrations
+  // to apply. Skip cleanly instead of failing the init container.
+  if (!existsSync(`${MIGRATIONS_FOLDER}/meta/_journal.json`)) {
+    // eslint-disable-next-line no-console
+    console.log('No migrations to apply.');
+    return;
+  }
+
+  const connectionString = process.env.DATABASE_URL;
+  if (!connectionString) {
+    throw new Error('DATABASE_URL is not set.');
+  }
+
+  const pool = new Pool({ connectionString });
+  // drizzle-orm's migrate() has no protection against concurrent execution
+  // (github.com/drizzle-team/drizzle-orm/issues/874, open, acknowledged by
+  // its maintainers) — it reads the last-applied migration with a plain
+  // SELECT before opening a transaction, so two replicas starting at once can
+  // both see "nothing applied yet" and both try to run the same migration.
+  // A session-scoped advisory lock on a dedicated connection serializes
+  // concurrent runs of this script: whichever loses blocks here until the
+  // winner releases the lock, then proceeds against an already-migrated
+  // database — a safe no-op, since __drizzle_migrations already records it.
+  const lockClient = await pool.connect();
+  try {
+    await lockClient.query('SELECT pg_advisory_lock($1)', [MIGRATION_LOCK_KEY]);
+    await migrate(drizzle(pool), { migrationsFolder: MIGRATIONS_FOLDER });
+    // eslint-disable-next-line no-console
+    console.log('Migrations applied.');
+  } finally {
+    await lockClient.query('SELECT pg_advisory_unlock($1)', [
+      MIGRATION_LOCK_KEY,
+    ]);
+    lockClient.release();
+    await pool.end();
+  }
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error('Migration failed:', err);
+  process.exit(1);
+});

package/src/migrations/add-migrate-advisory-lock/migrate.before.txt

@@ -0,0 +1,41 @@
+import { existsSync } from 'fs';
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { migrate } from 'drizzle-orm/node-postgres/migrator';
+import { Pool } from 'pg';
+
+const MIGRATIONS_FOLDER = 'drizzle';
+
+// Standalone migration runner — the deployment runs this as an init container
+// (`node migrate.js`) before the app starts. It uses only drizzle-orm + pg,
+// both runtime dependencies, so it survives `npm prune --omit=dev` and needs no
+// CLI or native engine in the image. The SQL files in ./drizzle are shipped as
+// build assets alongside this bundle.
+async function main() {
+  // A freshly generated service has no models yet, so there are no migrations
+  // to apply. Skip cleanly instead of failing the init container.
+  if (!existsSync(`${MIGRATIONS_FOLDER}/meta/_journal.json`)) {
+    // eslint-disable-next-line no-console
+    console.log('No migrations to apply.');
+    return;
+  }
+
+  const connectionString = process.env.DATABASE_URL;
+  if (!connectionString) {
+    throw new Error('DATABASE_URL is not set.');
+  }
+
+  const pool = new Pool({ connectionString });
+  try {
+    await migrate(drizzle(pool), { migrationsFolder: MIGRATIONS_FOLDER });
+    // eslint-disable-next-line no-console
+    console.log('Migrations applied.');
+  } finally {
+    await pool.end();
+  }
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error('Migration failed:', err);
+  process.exit(1);
+});