fix(db): keep a deferred Tin projection from failing a direct run

`db:push` runs the migration file directly, where a deferral has no
migration record to leave unwritten, so a refused extension aborted the
push. The direct entry point now adopts the projection where the database
allows it and logs the refusal otherwise, while the registered runner
still sees the deferral. Also covers continuation after a deferral with a
synthetic migration list, which the registry cannot express while the only
deferring migration is its last entry.

Author: waleedlatif1

packages/db/script-migrations/0019_tin_keyword_projection.test.ts

@@ -3,7 +3,10 @@
  */
 import type { Sql } from 'postgres'
 import { describe, expect, it, vi } from 'vitest'
-import { installTinKeywordProjection } from './0019_tin_keyword_projection'
+import {
+  adoptTinKeywordProjection,
+  installTinKeywordProjection,
+} from './0019_tin_keyword_projection'
 import { ScriptMigrationDeferred } from './types'
 
 /** A session that offers `tin` or not, and answers `CREATE EXTENSION` with `createError`. */
@@ -42,6 +45,20 @@ describe('installTinKeywordProjection', () => {
     }
   )
 
+  it('is a no-op when run directly against a database that refuses the extension', async () => {
+    const { sql, statements } = createSqlHarness({
+      available: true,
+      createError: { code: '42501' },
+    })
+    await expect(adoptTinKeywordProjection(sql)).resolves.toBeUndefined()
+    expect(statements.at(-1)).toBe('CREATE EXTENSION IF NOT EXISTS tin')
+  })
+
+  it('fails a direct run on any other extension error', async () => {
+    const { sql } = createSqlHarness({ available: true, createError: { code: '53100' } })
+    await expect(adoptTinKeywordProjection(sql)).rejects.toEqual({ code: '53100' })
+  })
+
   it('fails the migration on any other extension error', async () => {
     const { sql } = createSqlHarness({ available: true, createError: { code: '53100' } })
     await expect(installTinKeywordProjection(sql)).rejects.toEqual({ code: '53100' })

packages/db/script-migrations/0019_tin_keyword_projection.ts

@@ -233,12 +233,28 @@ export const tinKeywordProjectionMigration: ScriptMigration = {
   up: installTinKeywordProjection,
 }
 
+/**
+ * Installs the projection where this database allows it, treating a refused extension as a no-op:
+ * run directly — `db:push`, or adopting Tin after a cluster gains it — there is no migration
+ * record to leave unwritten, and keyword search keeps the GIN projection either way.
+ */
+export async function adoptTinKeywordProjection(sql: Sql): Promise<void> {
+  try {
+    await installTinKeywordProjection(sql)
+  } catch (error) {
+    if (!(error instanceof ScriptMigrationDeferred)) throw error
+    logger.warn('Tin projection deferred; keyword search keeps the GIN projection', {
+      reason: error.message,
+    })
+  }
+}
+
 if (import.meta.main) {
   const url = process.env.MIGRATION_DATABASE_URL ?? process.env.DATABASE_URL
   if (!url) throw new Error('DATABASE_URL is required to install the Tin keyword projection')
   const sql = postgres(url, { max: 1, max_lifetime: null, onnotice: () => undefined })
   try {
-    await installTinKeywordProjection(sql)
+    await adoptTinKeywordProjection(sql)
   } finally {
     await sql.end()
   }

packages/db/script-migrations/index.test.ts

@@ -4,18 +4,22 @@
 import type { Sql } from 'postgres'
 import { describe, expect, it, vi } from 'vitest'
 import { runScriptMigrations, scriptMigrations } from './index'
+import { type ScriptMigration, ScriptMigrationDeferred } from './types'
 
 const TIN = '0019_tin_keyword_projection'
 
-/** A session where every migration but Tin's is recorded and the database refuses `tin`. */
-function createSqlHarness() {
+/** Every registered migration but Tin's, so Tin is the only pending one. */
+const APPLIED_BEFORE_TIN = scriptMigrations
+  .filter(({ name }) => name !== TIN)
+  .map(({ name }) => name)
+
+/** A session where `applied` is already recorded and the database refuses `tin`. */
+function createSqlHarness(applied: readonly string[]) {
   const recorded: string[] = []
   const run = (strings: TemplateStringsArray, ...values: unknown[]) => {
     const text = strings.join('?').replace(/\s+/g, ' ').trim()
     if (text.startsWith('SELECT name FROM script_migrations')) {
-      return Promise.resolve(
-        scriptMigrations.filter(({ name }) => name !== TIN).map(({ name }) => ({ name }))
-      )
+      return Promise.resolve(applied.map((name) => ({ name })))
     }
     if (text.includes('pg_available_extensions')) return Promise.resolve([{ '?column?': 1 }])
     if (text.startsWith('INSERT INTO script_migrations')) recorded.push(values[0] as string)
@@ -32,8 +36,21 @@ function createSqlHarness() {
 
 describe('runScriptMigrations', () => {
   it('leaves a deferred migration unrecorded without failing the upgrade', async () => {
-    const { sql, recorded } = createSqlHarness()
+    const { sql, recorded } = createSqlHarness(APPLIED_BEFORE_TIN)
     await expect(runScriptMigrations(sql)).resolves.toBeUndefined()
     expect(recorded).toEqual([])
   })
+
+  it('applies and records the migrations that follow a deferred one', async () => {
+    const deferring: ScriptMigration = {
+      name: 'test_deferring',
+      up: async () => {
+        throw new ScriptMigrationDeferred('the database refused the test migration')
+      },
+    }
+    const following: ScriptMigration = { name: 'test_following', up: async () => {} }
+    const { sql, recorded } = createSqlHarness([])
+    await expect(runScriptMigrations(sql, [deferring, following])).resolves.toBeUndefined()
+    expect(recorded).toEqual(['test_following'])
+  })
 })

packages/db/script-migrations/index.ts

@@ -55,10 +55,17 @@ export const scriptMigrations: readonly ScriptMigration[] = [
  * Fails fast: a missing required env var or a throwing `up` aborts the run
  * before the name is recorded, so the migration retries on the next upgrade.
  * A deferred `up` is not recorded either, but lets the later migrations run.
+ *
+ * `migrations` defaults to the registry and exists so a test can apply a
+ * synthetic list: a deferral followed by a later migration is otherwise
+ * uncoverable while the only deferring migration is the last registered entry.
  */
-export async function runScriptMigrations(sql: Sql): Promise<void> {
+export async function runScriptMigrations(
+  sql: Sql,
+  migrations: readonly ScriptMigration[] = scriptMigrations
+): Promise<void> {
   const names = new Set<string>()
-  for (const migration of scriptMigrations) {
+  for (const migration of migrations) {
     if (names.has(migration.name)) {
       throw new Error(`Duplicate script migration name: ${migration.name}`)
     }
@@ -86,7 +93,7 @@ export async function runScriptMigrations(sql: Sql): Promise<void> {
   const appliedRows = await sql<{ name: string }[]>`SELECT name FROM script_migrations`
   const applied = new Set(appliedRows.map((row) => row.name))
 
-  const pending = scriptMigrations.filter((migration) => !applied.has(migration.name))
+  const pending = migrations.filter((migration) => !applied.has(migration.name))
   if (pending.length === 0) {
     console.log('No pending script migrations.')
     return