@dotdo/postgres 0.1.0

package/src/worker/do.test.ts

@@ -0,0 +1,2254 @@
+/**
+ * RED PHASE: PostgresDO Core Tests
+ * Task: postgres-6u6.3 - PostgresDO Core (constructor, initPGlite, executeQuery, fetch handler)
+ *
+ * These tests verify the Durable Object core functionality.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import {
+  createMockPGlite,
+  createMockDurableObjectState,
+} from '../__tests__/utils'
+
+// Mock cloudflare:workers before importing modules that depend on it
+vi.mock('cloudflare:workers', () => ({
+  DurableObject: class DurableObject {
+    ctx: unknown
+    env: unknown
+    constructor(ctx: unknown, env: unknown) {
+      this.ctx = ctx
+      this.env = env
+    }
+  },
+}))
+
+// Mock WASM and data imports that Vite can't handle in test environment
+vi.mock('../pglite-assets/pglite.wasm', () => ({ default: {} }))
+vi.mock('../pglite-assets/pglite.data', () => ({ default: {} }))
+
+// Mock the workers-pglite module to avoid WASM dependencies
+vi.mock('../pglite/workers-pglite', () => ({
+  createWorkersPGLite: vi.fn(),
+  WorkersPGLite: class {},
+}))
+
+import { PostgresDO, createPostgresDO } from './do'
+import type { Env, QueryRequest, QueryResponse, PostgresConfig } from './types'
+
+// Local wrapper to match existing test expectations (uses shared utility)
+const createMockState = () => createMockDurableObjectState({
+  id: 'test-do-id',
+  name: 'test-database',
+})
+
+// Mock Env
+const createMockEnv = (): Env => ({
+  POSTGRES_DO: {} as DurableObjectNamespace,
+  POSTGRES_DEFAULT_DB: 'postgres',
+})
+
+// MOCK REDUCTION HELPERS (postgres-6qei)
+// These helpers use dependency injection via getPGLiteManager().injectInstance()
+// instead of spying on internal createPGliteInstance method.
+
+function createTestDO(options?: {
+  config?: PostgresConfig
+  mockPGliteSetup?: (mock: ReturnType<typeof createMockPGlite>) => void
+}) {
+  const state = createMockState()
+  const env = createMockEnv()
+  const doo = new PostgresDO(state as any, env, options?.config)
+  const mockPGlite = createMockPGlite()
+  if (options?.mockPGliteSetup) {
+    options.mockPGliteSetup(mockPGlite)
+  }
+  doo.getPGLiteManager().injectInstance(mockPGlite)
+  return { doo, mockPGlite, state, env }
+}
+
+function createTestDOWithFactory(options?: {
+  config?: PostgresConfig
+  mockPGliteSetup?: (mock: ReturnType<typeof createMockPGlite>) => void
+}) {
+  const state = createMockState()
+  const env = createMockEnv()
+  const doo = new PostgresDO(state as any, env, options?.config)
+  const mockPGlite = createMockPGlite()
+  if (options?.mockPGliteSetup) {
+    options.mockPGliteSetup(mockPGlite)
+  }
+  doo.getPGLiteManager().setCreatePGLite(() => Promise.resolve(mockPGlite))
+  return { doo, mockPGlite, state, env }
+}
+
+describe('PostgresDO Core', () => {
+  describe('constructor', () => {
+    it('should create a PostgresDO instance', () => {
+      const state = createMockState()
+      const env = createMockEnv()
+      const doo = new PostgresDO(state as any, env)
+      expect(doo).toBeInstanceOf(PostgresDO)
+    })
+
+    it('should store state reference', () => {
+      const state = createMockState()
+      const env = createMockEnv()
+      const doo = new PostgresDO(state as any, env)
+      expect(doo.getState()).toBe(state)
+    })
+
+    it('should store env reference', () => {
+      const state = createMockState()
+      const env = createMockEnv()
+      const doo = new PostgresDO(state as any, env)
+      expect(doo.getEnv()).toBe(env)
+    })
+  })
+
+  describe('initPGlite', () => {
+    it('should initialize PGlite on first call', async () => {
+      const state = createMockState()
+      const env = createMockEnv()
+      const doo = new PostgresDO(state as any, env)
+
+      // Mock the PGlite initialization
+      const mockPGlite = createMockPGlite()
+      vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+      await doo.initPGlite()
+      expect(doo.isInitialized()).toBe(true)
+    })
+
+    it('should not reinitialize if already initialized', async () => {
+      const state = createMockState()
+      const env = createMockEnv()
+      const doo = new PostgresDO(state as any, env)
+
+      const mockPGlite = createMockPGlite()
+      const createSpy = vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+      await doo.initPGlite()
+      await doo.initPGlite()
+
+      expect(createSpy).toHaveBeenCalledTimes(1)
+    })
+
+    it('should use blockConcurrencyWhile for initialization', async () => {
+      const state = createMockState()
+      const env = createMockEnv()
+      const doo = new PostgresDO(state as any, env)
+
+      const mockPGlite = createMockPGlite()
+      vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+      await doo.initPGlite()
+      expect(state.blockConcurrencyWhile).toHaveBeenCalled()
+    })
+  })
+
+  describe('executeQuery', () => {
+    it('should execute a simple SELECT query', async () => {
+      const state = createMockState()
+      const env = createMockEnv()
+      const doo = new PostgresDO(state as any, env)
+
+      const mockPGlite = createMockPGlite()
+      mockPGlite.query.mockResolvedValue({
+        rows: [{ id: 1, name: 'Alice' }],
+        fields: [
+          { name: 'id', dataTypeID: 23 },
+          { name: 'name', dataTypeID: 25 },
+        ],
+        affectedRows: 1,
+      })
+      vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+      const request: QueryRequest = { sql: 'SELECT * FROM users' }
+      const result = await doo.executeQuery(request)
+
+      expect(result.rows).toEqual([{ id: 1, name: 'Alice' }])
+      expect(result.fields).toHaveLength(2)
+      expect(result.rowCount).toBe(1)
+    })
+
+    it('should pass parameters to PGlite', async () => {
+      const state = createMockState()
+      const env = createMockEnv()
+      const doo = new PostgresDO(state as any, env)
+
+      const mockPGlite = createMockPGlite()
+      vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+      const request: QueryRequest = {
+        sql: 'SELECT * FROM users WHERE id = $1',
+        params: [42],
+      }
+      await doo.executeQuery(request)
+
+      expect(mockPGlite.query).toHaveBeenCalledWith(
+        'SELECT * FROM users WHERE id = $1',
+        [42]
+      )
+    })
+
+    it('should apply SQL transform when preserveCase is true', async () => {
+      const state = createMockState()
+      const env = createMockEnv()
+      const doo = new PostgresDO(state as any, env)
+
+      const mockPGlite = createMockPGlite()
+      vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+      const request: QueryRequest = {
+        sql: 'SELECT userId FROM users',
+        preserveCase: true,
+      }
+      await doo.executeQuery(request)
+
+      // The SQL should be transformed to quote identifiers
+      const calledSql = mockPGlite.query.mock.calls[0]?.[0] as string
+      expect(calledSql).toContain('"userId"')
+      expect(calledSql).toContain('"users"')
+    })
+
+    it('should track query duration', async () => {
+      const state = createMockState()
+      const env = createMockEnv()
+      const doo = new PostgresDO(state as any, env)
+
+      const mockPGlite = createMockPGlite()
+      vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+      const request: QueryRequest = { sql: 'SELECT 1' }
+      const result = await doo.executeQuery(request)
+
+      expect(result.durationMs).toBeDefined()
+      expect(typeof result.durationMs).toBe('number')
+    })
+
+    it('should throw error for invalid SQL', async () => {
+      const state = createMockState()
+      const env = createMockEnv()
+      const doo = new PostgresDO(state as any, env)
+
+      const mockPGlite = createMockPGlite()
+      mockPGlite.query.mockRejectedValue(new Error('syntax error at position 1'))
+      vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+      const request: QueryRequest = { sql: 'SELEC * FROM users' }
+
+      await expect(doo.executeQuery(request)).rejects.toThrow('syntax error')
+    })
+
+    it('should auto-initialize PGlite if not initialized', async () => {
+      const state = createMockState()
+      const env = createMockEnv()
+      const doo = new PostgresDO(state as any, env)
+
+      const mockPGlite = createMockPGlite()
+      const initSpy = vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+      expect(doo.isInitialized()).toBe(false)
+
+      await doo.executeQuery({ sql: 'SELECT 1' })
+
+      expect(initSpy).toHaveBeenCalled()
+      expect(doo.isInitialized()).toBe(true)
+    })
+  })
+
+  describe('executeBatch', () => {
+    it('should execute multiple queries', async () => {
+      const state = createMockState()
+      const env = createMockEnv()
+      const doo = new PostgresDO(state as any, env)
+
+      const mockPGlite = createMockPGlite()
+      mockPGlite.query
+        .mockResolvedValueOnce({ rows: [{ a: 1 }], fields: [], affectedRows: 1 })
+        .mockResolvedValueOnce({ rows: [{ b: 2 }], fields: [], affectedRows: 1 })
+      vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+      const results = await doo.executeBatch({
+        queries: [
+          { sql: 'SELECT 1 AS a' },
+          { sql: 'SELECT 2 AS b' },
+        ],
+      })
+
+      expect(results.results).toHaveLength(2)
+      expect(results.results[0].rows).toEqual([{ a: 1 }])
+      expect(results.results[1].rows).toEqual([{ b: 2 }])
+    })
+
+    it('should wrap in transaction when transaction=true', async () => {
+      const state = createMockState()
+      const env = createMockEnv()
+      const doo = new PostgresDO(state as any, env)
+
+      const mockPGlite = createMockPGlite()
+      const queryCalls: string[] = []
+      mockPGlite.query.mockImplementation((sql?: string) => {
+        queryCalls.push(sql ?? '')
+        return Promise.resolve({ rows: [], fields: [], affectedRows: 0 })
+      })
+      vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+      await doo.executeBatch({
+        queries: [{ sql: 'SELECT 1' }],
+        transaction: true,
+      })
+
+      expect(queryCalls[0]).toBe('BEGIN')
+      expect(queryCalls[queryCalls.length - 1]).toBe('COMMIT')
+    })
+
+    it('should rollback on error when transaction=true', async () => {
+      const state = createMockState()
+      const env = createMockEnv()
+      const doo = new PostgresDO(state as any, env)
+
+      const mockPGlite = createMockPGlite()
+      const queryCalls: string[] = []
+      mockPGlite.query.mockImplementation((sql?: string) => {
+        queryCalls.push(sql ?? '')
+        if (sql === 'SELECT 1') {
+          return Promise.reject(new Error('test error'))
+        }
+        return Promise.resolve({ rows: [], fields: [], affectedRows: 0 })
+      })
+      vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+      await expect(doo.executeBatch({
+        queries: [{ sql: 'SELECT 1' }],
+        transaction: true,
+      })).rejects.toThrow('test error')
+
+      expect(queryCalls).toContain('ROLLBACK')
+    })
+  })
+
+  describe('getConfig', () => {
+    it('should return current configuration', async () => {
+      const state = createMockState()
+      const env = createMockEnv()
+      const doo = new PostgresDO(state as any, env)
+
+      const config = doo.getConfig()
+      expect(config).toBeDefined()
+      expect(config.database).toBeDefined()
+    })
+  })
+
+  describe('getStats', () => {
+    it('should return query statistics', async () => {
+      const state = createMockState()
+      const env = createMockEnv()
+      const doo = new PostgresDO(state as any, env)
+
+      const mockPGlite = createMockPGlite()
+      vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+      await doo.executeQuery({ sql: 'SELECT 1' })
+      await doo.executeQuery({ sql: 'SELECT 2' })
+
+      const stats = doo.getStats()
+      expect(stats.queryCount).toBe(2)
+      expect(stats.totalDurationMs).toBeGreaterThanOrEqual(0)
+    })
+  })
+
+  describe('createPostgresDO factory', () => {
+    it('should create a PostgresDO class with custom config', () => {
+      const PostgresDOClass = createPostgresDO({
+        database: 'mydb',
+        extensions: ['vector'],
+        preserveCase: true,
+      })
+
+      const state = createMockState()
+      const env = createMockEnv()
+      const doo = new PostgresDOClass(state as any, env)
+
+      expect(doo).toBeInstanceOf(PostgresDO)
+      expect(doo.getConfig().database).toBe('mydb')
+      expect(doo.getConfig().extensions).toContain('vector')
+      expect(doo.getConfig().preserveCase).toBe(true)
+    })
+  })
+
+  describe('Graceful Shutdown and Connection Draining', () => {
+    describe('shutdown status', () => {
+      it('should start with running status', () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        expect(doo.getShutdownStatus()).toBe('running')
+        expect(doo.isShuttingDown()).toBe(false)
+      })
+
+      it('should track active query count', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        // Create a slow mock PGlite that delays query execution
+        const mockPGlite = createMockPGlite()
+        let resolveQuery: () => void
+        const queryPromise = new Promise<void>((resolve) => {
+          resolveQuery = resolve
+        })
+        mockPGlite.query.mockImplementation(async () => {
+          await queryPromise
+          return { rows: [], fields: [], affectedRows: 0 }
+        })
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+        // Start a query but don't await it
+        const queryExecution = doo.executeQuery({ sql: 'SELECT pg_sleep(1)' })
+
+        // Give time for query to start
+        await new Promise((r) => setTimeout(r, 10))
+
+        expect(doo.getActiveQueryCount()).toBe(1)
+
+        // Resolve the query and wait for it
+        resolveQuery!()
+        await queryExecution
+
+        expect(doo.getActiveQueryCount()).toBe(0)
+      })
+
+      it('should return active query info', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        let resolveQuery: () => void
+        const queryPromise = new Promise<void>((resolve) => {
+          resolveQuery = resolve
+        })
+        mockPGlite.query.mockImplementation(async () => {
+          await queryPromise
+          return { rows: [], fields: [], affectedRows: 0 }
+        })
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+        const queryExecution = doo.executeQuery({ sql: 'SELECT * FROM users WHERE id = 1' })
+        await new Promise((r) => setTimeout(r, 10))
+
+        const activeQueries = doo.getActiveQueries()
+        expect(activeQueries.length).toBe(1)
+        expect(activeQueries[0].sql).toContain('SELECT * FROM users')
+        expect(activeQueries[0].durationMs).toBeGreaterThanOrEqual(0)
+
+        resolveQuery!()
+        await queryExecution
+      })
+    })
+
+    describe('shutdown configuration', () => {
+      it('should have default shutdown config', () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const config = doo.getShutdownConfig()
+        expect(config.gracePeriodMs).toBe(30000)
+        expect(config.drainCheckIntervalMs).toBe(100)
+        expect(config.closeTimeoutMs).toBe(5000)
+      })
+
+      it('should allow setting shutdown config', () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        doo.setShutdownConfig({
+          gracePeriodMs: 60000,
+          drainCheckIntervalMs: 50,
+        })
+
+        const config = doo.getShutdownConfig()
+        expect(config.gracePeriodMs).toBe(60000)
+        expect(config.drainCheckIntervalMs).toBe(50)
+        expect(config.closeTimeoutMs).toBe(5000) // unchanged
+      })
+    })
+
+    describe('shutdown event listeners', () => {
+      it('should register and unregister event listeners', () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const listener = vi.fn()
+        const unsubscribe = doo.onShutdownEvent(listener)
+
+        expect(typeof unsubscribe).toBe('function')
+
+        // Unsubscribe and verify no errors
+        unsubscribe()
+      })
+
+      it('should prevent memory leak by limiting listener count', () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        // Simulate adding many listeners without cleanup (memory leak scenario)
+        const listenerCount = 150 // More than the default limit of 100
+        const cleanupFns: (() => void)[] = []
+
+        for (let i = 0; i < listenerCount; i++) {
+          const cleanup = doo.onShutdownEvent(() => {})
+          cleanupFns.push(cleanup)
+        }
+
+        // The listener count should be capped at maxListeners (default: 100)
+        const actualListenerCount = doo.getShutdownListenerCount()
+        expect(actualListenerCount).toBeLessThanOrEqual(100)
+      })
+
+      it('should warn when approaching listener limit', () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+        // Add listeners to reach 80% of the limit (80 out of 100)
+        for (let i = 0; i < 85; i++) {
+          doo.onShutdownEvent(() => {})
+        }
+
+        // Should have warned about approaching limit
+        expect(consoleSpy).toHaveBeenCalledWith(
+          expect.stringContaining('Approaching shutdown event listener limit')
+        )
+
+        consoleSpy.mockRestore()
+      })
+
+      it('should support configurable maxListeners', () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        // Configure custom max listeners
+        doo.setShutdownConfig({ maxListeners: 50 })
+
+        // Add more listeners than the custom limit
+        for (let i = 0; i < 60; i++) {
+          doo.onShutdownEvent(() => {})
+        }
+
+        // Should be capped at custom limit
+        const actualListenerCount = doo.getShutdownListenerCount()
+        expect(actualListenerCount).toBeLessThanOrEqual(50)
+      })
+
+      it('should emit shutdown events', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        const events: { type: string; details?: Record<string, unknown> }[] = []
+        doo.onShutdownEvent((event) => {
+          events.push({ type: event.type, details: event.details })
+        })
+
+        await doo.shutdown({ gracePeriodMs: 100 })
+
+        expect(events.some((e) => e.type === 'shutdown_initiated')).toBe(true)
+        expect(events.some((e) => e.type === 'drain_started')).toBe(true)
+        expect(events.some((e) => e.type === 'drain_completed')).toBe(true)
+        expect(events.some((e) => e.type === 'shutdown_completed')).toBe(true)
+      })
+    })
+
+    describe('graceful shutdown', () => {
+      it('should set status to draining then shutdown', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        const statuses: string[] = []
+        doo.onShutdownEvent((event) => {
+          statuses.push(doo.getShutdownStatus())
+        })
+
+        await doo.shutdown({ gracePeriodMs: 100 })
+
+        expect(doo.getShutdownStatus()).toBe('shutdown')
+        expect(statuses).toContain('draining')
+      })
+
+      it('should close PGlite during shutdown', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        await doo.shutdown({ gracePeriodMs: 100 })
+
+        expect(mockPGlite.close).toHaveBeenCalled()
+      })
+
+      it('should reject new queries after shutdown', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        await doo.shutdown({ gracePeriodMs: 100 })
+
+        await expect(doo.executeQuery({ sql: 'SELECT 1' })).rejects.toThrow(
+          'PostgresDO is shut down and cannot accept new requests'
+        )
+      })
+
+      it('should only perform shutdown once if called multiple times', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        const shutdownEvents: string[] = []
+        doo.onShutdownEvent((event) => shutdownEvents.push(event.type))
+
+        // Call shutdown multiple times
+        const promise1 = doo.shutdown({ gracePeriodMs: 100 })
+        const promise2 = doo.shutdown()
+        const promise3 = doo.shutdown({ gracePeriodMs: 200 })
+
+        // Wait for all to complete
+        await Promise.all([promise1, promise2, promise3])
+
+        // Verify shutdown_initiated only happened once
+        const initiatedCount = shutdownEvents.filter((e) => e === 'shutdown_initiated').length
+        expect(initiatedCount).toBe(1)
+
+        // Verify shutdown_completed only happened once
+        const completedCount = shutdownEvents.filter((e) => e === 'shutdown_completed').length
+        expect(completedCount).toBe(1)
+
+        // Verify PGlite.close was only called once
+        expect(mockPGlite.close).toHaveBeenCalledTimes(1)
+      })
+    })
+
+    describe('connection draining', () => {
+      it('should wait for in-flight queries to complete', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        let resolveQuery: () => void
+        const queryPromise = new Promise<void>((resolve) => {
+          resolveQuery = resolve
+        })
+        mockPGlite.query.mockImplementation(async () => {
+          await queryPromise
+          return { rows: [], fields: [], affectedRows: 0 }
+        })
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        // Start a query but don't await it yet
+        const queryExecution = doo.executeQuery({ sql: 'SELECT 1' })
+        await new Promise((r) => setTimeout(r, 10))
+
+        expect(doo.getActiveQueryCount()).toBe(1)
+
+        // Start shutdown (won't complete until query finishes)
+        const shutdownPromise = doo.shutdown({ gracePeriodMs: 5000 })
+
+        expect(doo.getShutdownStatus()).toBe('draining')
+
+        // Resolve the query
+        resolveQuery!()
+        await queryExecution
+
+        // Now shutdown should complete
+        await shutdownPromise
+
+        expect(doo.getShutdownStatus()).toBe('shutdown')
+      })
+
+      it('should force shutdown after grace period', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        // This query will never resolve
+        mockPGlite.query.mockImplementation(() => new Promise(() => {}))
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        // Start a query that never completes
+        doo.executeQuery({ sql: 'SELECT pg_sleep(9999)' }).catch(() => {})
+        await new Promise((r) => setTimeout(r, 10))
+
+        expect(doo.getActiveQueryCount()).toBe(1)
+
+        const events: string[] = []
+        doo.onShutdownEvent((event) => events.push(event.type))
+
+        // Shutdown with very short grace period
+        await doo.shutdown({
+          gracePeriodMs: 50,
+          drainCheckIntervalMs: 10,
+        })
+
+        expect(events).toContain('forced_shutdown')
+        expect(doo.getShutdownStatus()).toBe('shutdown')
+      })
+
+      it('should emit query_completed_during_drain event', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        let resolveQuery: () => void
+        const queryPromise = new Promise<void>((resolve) => {
+          resolveQuery = resolve
+        })
+        mockPGlite.query.mockImplementation(async () => {
+          await queryPromise
+          return { rows: [], fields: [], affectedRows: 0 }
+        })
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        // Start a query
+        const queryExecution = doo.executeQuery({ sql: 'SELECT 1' })
+        await new Promise((r) => setTimeout(r, 10))
+
+        const events: { type: string; details?: Record<string, unknown> }[] = []
+        doo.onShutdownEvent((event) => events.push({ type: event.type, details: event.details }))
+
+        // Start shutdown
+        const shutdownPromise = doo.shutdown({ gracePeriodMs: 5000 })
+
+        // Wait for draining to start
+        await new Promise((r) => setTimeout(r, 20))
+
+        // Complete the query
+        resolveQuery!()
+        await queryExecution
+
+        await shutdownPromise
+
+        const drainEvent = events.find((e) => e.type === 'query_completed_during_drain')
+        expect(drainEvent).toBeDefined()
+        expect(drainEvent?.details?.remainingQueries).toBe(0)
+      })
+    })
+
+    describe('websocket handling during shutdown', () => {
+      it('should close websockets during shutdown', async () => {
+        const mockWebSocket = {
+          close: vi.fn(),
+        }
+        const state = createMockState()
+        state.getWebSockets.mockReturnValue([mockWebSocket])
+
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        await doo.shutdown({ gracePeriodMs: 100 })
+
+        expect(mockWebSocket.close).toHaveBeenCalledWith(1001, 'Server shutting down')
+      })
+
+      it('should emit websocket_closed_during_drain event', async () => {
+        const mockWebSocket = {
+          close: vi.fn(),
+        }
+        const state = createMockState()
+        state.getWebSockets.mockReturnValue([mockWebSocket])
+
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        const events: string[] = []
+        doo.onShutdownEvent((event) => events.push(event.type))
+
+        await doo.shutdown({ gracePeriodMs: 100 })
+
+        expect(events).toContain('websocket_closed_during_drain')
+      })
+
+      it('should handle websockets that are already closed', async () => {
+        const mockWebSocket = {
+          close: vi.fn(() => {
+            throw new Error('WebSocket already closed')
+          }),
+        }
+        const state = createMockState()
+        state.getWebSockets.mockReturnValue([mockWebSocket])
+
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        // Should not throw
+        await doo.shutdown({ gracePeriodMs: 100 })
+
+        expect(doo.getShutdownStatus()).toBe('shutdown')
+      })
+    })
+
+    describe('PGlite close timeout', () => {
+      it('should timeout PGlite close if it takes too long', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        // PGlite close that never resolves
+        mockPGlite.close.mockImplementation(() => new Promise(() => {}))
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+        await doo.shutdown({
+          gracePeriodMs: 50,
+          closeTimeoutMs: 50,
+        })
+
+        expect(doo.getShutdownStatus()).toBe('shutdown')
+        consoleSpy.mockRestore()
+      })
+    })
+
+    describe('isShuttingDown', () => {
+      it('should return true when draining', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        let resolveClose: () => void
+        mockPGlite.close.mockImplementation(
+          () =>
+            new Promise((resolve) => {
+              resolveClose = resolve as () => void
+            })
+        )
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        const shutdownPromise = doo.shutdown({ gracePeriodMs: 100 })
+        await new Promise((r) => setTimeout(r, 10))
+
+        expect(doo.isShuttingDown()).toBe(true)
+
+        resolveClose!()
+        await shutdownPromise
+      })
+
+      it('should return true when shutdown', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        await doo.shutdown({ gracePeriodMs: 100 })
+
+        expect(doo.isShuttingDown()).toBe(true)
+        expect(doo.getShutdownStatus()).toBe('shutdown')
+      })
+    })
+  })
+
+  describe('Auto-Migration on First Connection', () => {
+    describe('schema version tracking', () => {
+      it('should return version 0 for fresh database', async () => {
+        const state = createMockState()
+        state.storage.get.mockResolvedValue(undefined)
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const version = await doo.getSchemaVersion()
+        expect(version).toBe(0)
+      })
+
+      it('should return stored version', async () => {
+        const state = createMockState()
+        state.storage.get.mockResolvedValue(5)
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const version = await doo.getSchemaVersion()
+        expect(version).toBe(5)
+      })
+
+      it('should detect fresh database', async () => {
+        const state = createMockState()
+        state.storage.get.mockResolvedValue(undefined)
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const isFresh = await doo.isFreshDatabase()
+        expect(isFresh).toBe(true)
+      })
+
+      it('should detect non-fresh database', async () => {
+        const state = createMockState()
+        state.storage.get.mockResolvedValue(1)
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const isFresh = await doo.isFreshDatabase()
+        expect(isFresh).toBe(false)
+      })
+    })
+
+    describe('ensureMigrated', () => {
+      it('should return null when no migrations configured', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        const result = await doo.ensureMigrated()
+        expect(result).toBeNull()
+        expect(doo.isMigrated()).toBe(true)
+      })
+
+      it('should run migrations on fresh database', async () => {
+        const state = createMockState()
+        state.storage.get.mockResolvedValue(undefined) // Fresh DB
+        const env = createMockEnv()
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            autoMigrate: false, // Disable auto-migrate to test ensureMigrated directly
+            migrations: [
+              {
+                id: '001_initial',
+                name: 'Initial schema',
+                version: 1,
+                sql: 'CREATE TABLE users (id SERIAL PRIMARY KEY)',
+              },
+            ],
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const mockPGlite = createMockPGlite()
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        const result = await doo.ensureMigrated()
+
+        expect(result).not.toBeNull()
+        expect(result?.success).toBe(true)
+        expect(result?.migrationsRun).toBe(1)
+        expect(state.storage.put).toHaveBeenCalledWith('__postgres_schema_version__', 1)
+      })
+
+      it('should skip already applied migrations', async () => {
+        const state = createMockState()
+        state.storage.get.mockResolvedValue(1) // Already at version 1
+        const env = createMockEnv()
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            autoMigrate: false, // Disable auto-migrate to test ensureMigrated directly
+            migrations: [
+              {
+                id: '001_initial',
+                name: 'Initial schema',
+                version: 1,
+                sql: 'CREATE TABLE users (id SERIAL PRIMARY KEY)',
+              },
+            ],
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const mockPGlite = createMockPGlite()
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        const result = await doo.ensureMigrated()
+
+        expect(result).not.toBeNull()
+        expect(result?.success).toBe(true)
+        expect(result?.migrationsSkipped).toBe(1)
+        expect(result?.migrationsRun).toBe(0)
+      })
+
+      it('should run only pending migrations', async () => {
+        const state = createMockState()
+        // Track the schema version in storage
+        let storedVersion: number = 1
+        state.storage.get.mockImplementation(async (key: string) => {
+          if (key === '__postgres_schema_version__') return storedVersion
+          return undefined
+        })
+        state.storage.put.mockImplementation(async (key: string, value: unknown) => {
+          if (key === '__postgres_schema_version__') storedVersion = value as number
+        })
+        const env = createMockEnv()
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            autoMigrate: false, // Disable auto-migrate to test ensureMigrated directly
+            migrations: [
+              {
+                id: '001_initial',
+                name: 'Initial schema',
+                version: 1,
+                sql: 'CREATE TABLE users (id SERIAL PRIMARY KEY)',
+              },
+              {
+                id: '002_add_email',
+                name: 'Add email column',
+                version: 2,
+                sql: 'ALTER TABLE users ADD COLUMN email TEXT',
+              },
+            ],
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const mockPGlite = createMockPGlite()
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        const result = await doo.ensureMigrated()
+
+        expect(result?.success).toBe(true)
+        expect(result?.migrationsRun).toBe(1) // Only migration 2
+        expect(result?.migrationsSkipped).toBe(1) // Migration 1 skipped
+        expect(result?.fromVersion).toBe(1)
+        expect(result?.toVersion).toBe(2)
+      })
+    })
+
+    describe('migration error handling', () => {
+      it('should handle migration failures gracefully', async () => {
+        const state = createMockState()
+        state.storage.get.mockResolvedValue(undefined)
+        const env = createMockEnv()
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            migrations: [
+              {
+                id: '001_bad',
+                name: 'Bad migration',
+                version: 1,
+                sql: 'INVALID SQL SYNTAX',
+              },
+            ],
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const mockPGlite = createMockPGlite()
+        mockPGlite.exec.mockRejectedValue(new Error('syntax error'))
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        const result = await doo.ensureMigrated()
+
+        expect(result?.success).toBe(false)
+        expect(result?.results[0].success).toBe(false)
+        expect(result?.results[0].error).toContain('syntax error')
+        expect(doo.isMigrated()).toBe(false)
+      })
+
+      it('should rollback on migration failure', async () => {
+        const state = createMockState()
+        state.storage.get.mockResolvedValue(undefined)
+        const env = createMockEnv()
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            migrations: [
+              {
+                id: '001_bad',
+                name: 'Bad migration',
+                version: 1,
+                sql: 'INVALID SQL',
+              },
+            ],
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const mockPGlite = createMockPGlite()
+        const queryCalls: string[] = []
+        mockPGlite.query.mockImplementation((sql?: string) => {
+          queryCalls.push(sql ?? '')
+          return Promise.resolve({ rows: [], fields: [], affectedRows: 0 })
+        })
+        mockPGlite.exec.mockRejectedValue(new Error('syntax error'))
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        await doo.ensureMigrated()
+
+        expect(queryCalls).toContain('BEGIN')
+        expect(queryCalls).toContain('ROLLBACK')
+      })
+    })
+
+    describe('migration progress callbacks', () => {
+      it('should call onProgress for each migration phase', async () => {
+        const state = createMockState()
+        state.storage.get.mockResolvedValue(undefined)
+        const env = createMockEnv()
+
+        const progressEvents: Array<{ phase: string; migration: { id: string } }> = []
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            migrations: [
+              {
+                id: '001_initial',
+                name: 'Initial schema',
+                version: 1,
+                sql: 'CREATE TABLE users (id SERIAL PRIMARY KEY)',
+              },
+            ],
+            onProgress: (event) => {
+              progressEvents.push({ phase: event.phase, migration: { id: event.migration.id } })
+            },
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const mockPGlite = createMockPGlite()
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        await doo.ensureMigrated()
+
+        expect(progressEvents.some((e) => e.phase === 'starting')).toBe(true)
+        expect(progressEvents.some((e) => e.phase === 'executing')).toBe(true)
+        expect(progressEvents.some((e) => e.phase === 'completed')).toBe(true)
+      })
+
+      it('should call onProgress with failed phase on error', async () => {
+        const state = createMockState()
+        state.storage.get.mockResolvedValue(undefined)
+        const env = createMockEnv()
+
+        const progressEvents: Array<{ phase: string; error?: string }> = []
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            migrations: [
+              {
+                id: '001_bad',
+                name: 'Bad migration',
+                version: 1,
+                sql: 'INVALID SQL',
+              },
+            ],
+            onProgress: (event) => {
+              progressEvents.push({ phase: event.phase, error: event.error })
+            },
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const mockPGlite = createMockPGlite()
+        mockPGlite.exec.mockRejectedValue(new Error('syntax error'))
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+        await doo.initPGlite()
+
+        await doo.ensureMigrated()
+
+        const failedEvent = progressEvents.find((e) => e.phase === 'failed')
+        expect(failedEvent).toBeDefined()
+        expect(failedEvent?.error).toContain('syntax error')
+      })
+    })
+
+    describe('auto-migration during initialization', () => {
+      it('should run migrations automatically when autoMigrate is not set (defaults to true)', async () => {
+        const state = createMockState()
+        state.storage.get.mockResolvedValue(undefined)
+        const env = createMockEnv()
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            migrations: [
+              {
+                id: '001_initial',
+                name: 'Initial schema',
+                version: 1,
+                sql: 'CREATE TABLE users (id SERIAL PRIMARY KEY)',
+              },
+            ],
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const mockPGlite = createMockPGlite()
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+        await doo.initPGlite()
+
+        // Migration should have run automatically
+        expect(doo.isMigrated()).toBe(true)
+        expect(state.storage.put).toHaveBeenCalledWith('__postgres_schema_version__', 1)
+      })
+
+      it('should skip auto-migration when autoMigrate is false', async () => {
+        const state = createMockState()
+        state.storage.get.mockResolvedValue(undefined)
+        const env = createMockEnv()
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            autoMigrate: false,
+            migrations: [
+              {
+                id: '001_initial',
+                name: 'Initial schema',
+                version: 1,
+                sql: 'CREATE TABLE users (id SERIAL PRIMARY KEY)',
+              },
+            ],
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const mockPGlite = createMockPGlite()
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+        await doo.initPGlite()
+
+        // Migration should NOT have run
+        expect(doo.isMigrated()).toBe(false)
+        expect(state.storage.put).not.toHaveBeenCalledWith('__postgres_schema_version__', 1)
+      })
+    })
+
+    describe('concurrent migration protection', () => {
+      it('should deduplicate concurrent ensureMigrated calls', async () => {
+        const state = createMockState()
+        state.storage.get.mockResolvedValue(undefined)
+        const env = createMockEnv()
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            autoMigrate: false, // Disable auto-migrate to control manually
+            migrations: [
+              {
+                id: '001_initial',
+                name: 'Initial schema',
+                version: 1,
+                sql: 'CREATE TABLE users (id SERIAL PRIMARY KEY)',
+              },
+            ],
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const mockPGlite = createMockPGlite()
+        let execCallCount = 0
+        mockPGlite.exec.mockImplementation(async () => {
+          execCallCount++
+          await new Promise((r) => setTimeout(r, 10))
+          return { rows: [], fields: [] }
+        })
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+        await doo.initPGlite()
+
+        // Call ensureMigrated multiple times concurrently
+        const [result1, result2, result3] = await Promise.all([
+          doo.ensureMigrated(),
+          doo.ensureMigrated(),
+          doo.ensureMigrated(),
+        ])
+
+        // All should return the same result (first two return the running promise)
+        // The migration SQL should only be executed once
+        expect(execCallCount).toBe(1)
+
+        // Results should be consistent
+        expect(result1?.success || result1 === null).toBe(true)
+      })
+    })
+  })
+
+  describe('WAL Initialization Race Condition', () => {
+    describe('initWAL concurrent calls', () => {
+      it('should only initialize WAL once when called concurrently', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        // Spy on the WAL facade's initialize method
+        let initializeCallCount = 0
+        const mockWALFacade = {
+          initialize: vi.fn(async () => {
+            initializeCallCount++
+            // Add small delay to simulate async work and increase race window
+            await new Promise((r) => setTimeout(r, 20))
+          }),
+          isEnabled: vi.fn(() => true),
+          setEnabled: vi.fn(),
+          getConfig: vi.fn(() => ({})),
+          setConfig: vi.fn(),
+          getStats: vi.fn(() => ({ entriesInBuffer: 0, totalEntriesFlushed: 0, lastFlushAt: null })),
+        }
+
+        vi.spyOn(doo, 'getWALFacade').mockReturnValue(mockWALFacade as any)
+
+        // Call initWAL concurrently 10 times
+        const promises = Array.from({ length: 10 }, () => doo.initWAL())
+        await Promise.all(promises)
+
+        // Assert: initialize() should only be called ONCE
+        expect(initializeCallCount).toBe(1)
+        expect(mockWALFacade.initialize).toHaveBeenCalledTimes(1)
+      })
+
+      it('should return the same promise for concurrent calls', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        let initializeCallCount = 0
+        const mockWALFacade = {
+          initialize: vi.fn(async () => {
+            initializeCallCount++
+            await new Promise((r) => setTimeout(r, 10))
+          }),
+          isEnabled: vi.fn(() => true),
+          setEnabled: vi.fn(),
+          getConfig: vi.fn(() => ({})),
+          setConfig: vi.fn(),
+          getStats: vi.fn(() => ({ entriesInBuffer: 0, totalEntriesFlushed: 0, lastFlushAt: null })),
+        }
+
+        vi.spyOn(doo, 'getWALFacade').mockReturnValue(mockWALFacade as any)
+
+        // Start multiple initWAL calls before any complete
+        const promise1 = doo.initWAL()
+        const promise2 = doo.initWAL()
+        const promise3 = doo.initWAL()
+
+        // All promises should complete successfully
+        await Promise.all([promise1, promise2, promise3])
+
+        // Only one actual initialization should have occurred
+        expect(initializeCallCount).toBe(1)
+      })
+
+      it('should allow re-initialization after previous completes if needed', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        let initializeCallCount = 0
+        const mockWALFacade = {
+          initialize: vi.fn(async () => {
+            initializeCallCount++
+          }),
+          isEnabled: vi.fn(() => true),
+          setEnabled: vi.fn(),
+          getConfig: vi.fn(() => ({})),
+          setConfig: vi.fn(),
+          getStats: vi.fn(() => ({ entriesInBuffer: 0, totalEntriesFlushed: 0, lastFlushAt: null })),
+        }
+
+        vi.spyOn(doo, 'getWALFacade').mockReturnValue(mockWALFacade as any)
+
+        // First call
+        await doo.initWAL()
+        expect(initializeCallCount).toBe(1)
+
+        // Second call after first completes - should still only have 1 init
+        // (because the guard pattern caches the promise)
+        await doo.initWAL()
+        expect(initializeCallCount).toBe(1)
+      })
+    })
+  })
+
+  describe('Lazy Migration (on-demand strategy)', () => {
+    describe('getMigrationStrategy', () => {
+      it('should return "on-create" by default', () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        expect(doo.getMigrationStrategy()).toBe('on-create')
+      })
+
+      it('should return configured strategy', () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            migrations: [],
+            strategy: 'on-demand',
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        expect(doo.getMigrationStrategy()).toBe('on-demand')
+      })
+    })
+
+    describe('getMigrationState', () => {
+      it('should return null when no state exists', async () => {
+        const state = createMockState()
+        state.storage.get.mockResolvedValue(undefined)
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const migrationState = await doo.getMigrationState()
+        expect(migrationState).toBeNull()
+      })
+
+      it('should return stored migration state', async () => {
+        const state = createMockState()
+        const storedState = {
+          status: 'completed',
+          version: 3,
+          lastAttemptAt: '2024-01-01T00:00:00Z',
+          durationMs: 150,
+        }
+        state.storage.get.mockResolvedValue(storedState)
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const migrationState = await doo.getMigrationState()
+        expect(migrationState).toEqual(storedState)
+      })
+    })
+
+    describe('needsLazyMigration', () => {
+      it('should return false for on-create strategy', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            migrations: [{ id: '1', name: 'test', version: 1, sql: 'SELECT 1' }],
+            strategy: 'on-create',
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const needs = await doo.needsLazyMigration()
+        expect(needs).toBe(false)
+      })
+
+      it('should return false when no migrations configured', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            migrations: [],
+            strategy: 'on-demand',
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const needs = await doo.needsLazyMigration()
+        expect(needs).toBe(false)
+      })
+
+      it('should return true when no migration state exists', async () => {
+        const state = createMockState()
+        state.storage.get.mockResolvedValue(undefined)
+        const env = createMockEnv()
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            migrations: [{ id: '1', name: 'test', version: 1, sql: 'SELECT 1' }],
+            strategy: 'on-demand',
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const needs = await doo.needsLazyMigration()
+        expect(needs).toBe(true)
+      })
+
+      it('should return false when migrations completed and up to date', async () => {
+        const state = createMockState()
+        state.storage.get.mockResolvedValue({
+          status: 'completed',
+          version: 1,
+          lastAttemptAt: '2024-01-01T00:00:00Z',
+        })
+        const env = createMockEnv()
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            migrations: [{ id: '1', name: 'test', version: 1, sql: 'SELECT 1' }],
+            strategy: 'on-demand',
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const needs = await doo.needsLazyMigration()
+        expect(needs).toBe(false)
+      })
+
+      it('should return true when new migrations available', async () => {
+        const state = createMockState()
+        state.storage.get.mockResolvedValue({
+          status: 'completed',
+          version: 1,
+          lastAttemptAt: '2024-01-01T00:00:00Z',
+        })
+        const env = createMockEnv()
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            migrations: [
+              { id: '1', name: 'test1', version: 1, sql: 'SELECT 1' },
+              { id: '2', name: 'test2', version: 2, sql: 'SELECT 2' },
+            ],
+            strategy: 'on-demand',
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const needs = await doo.needsLazyMigration()
+        expect(needs).toBe(true)
+      })
+
+      it('should return true when previous migration failed', async () => {
+        const state = createMockState()
+        state.storage.get.mockResolvedValue({
+          status: 'failed',
+          version: 0,
+          lastAttemptAt: '2024-01-01T00:00:00Z',
+          error: 'Previous error',
+        })
+        const env = createMockEnv()
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            migrations: [{ id: '1', name: 'test', version: 1, sql: 'SELECT 1' }],
+            strategy: 'on-demand',
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const needs = await doo.needsLazyMigration()
+        expect(needs).toBe(true)
+      })
+    })
+
+    describe('on-demand migration during query', () => {
+      it('should skip migrations during initPGlite for on-demand strategy', async () => {
+        const state = createMockState()
+        state.storage.get.mockResolvedValue(undefined) // No schema version
+        const env = createMockEnv()
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            migrations: [{ id: '1', name: 'test', version: 1, sql: 'CREATE TABLE test (id INT)' }],
+            strategy: 'on-demand',
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const mockPGlite = createMockPGlite()
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+        await doo.initPGlite()
+
+        // Migration should NOT have been called during init
+        // The exec/query should not have been called for migration SQL
+        const queryCalls = mockPGlite.query.mock.calls as [string, unknown[]][]
+        const migrationQueries = queryCalls.filter(([sql]) =>
+          sql && (sql.includes('CREATE TABLE test') || sql.includes('BEGIN'))
+        )
+        expect(migrationQueries).toHaveLength(0)
+      })
+
+      it('should run migrations on first query for on-demand strategy', async () => {
+        const state = createMockState()
+        let storageData: Record<string, unknown> = {}
+        state.storage.get.mockImplementation((key: string) => Promise.resolve(storageData[key]))
+        state.storage.put.mockImplementation((key: string, value: unknown) => {
+          storageData[key] = value
+          return Promise.resolve()
+        })
+        const env = createMockEnv()
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            migrations: [{ id: '1', name: 'test', version: 1, sql: 'CREATE TABLE test (id INT)' }],
+            strategy: 'on-demand',
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const mockPGlite = createMockPGlite()
+        // Mock all queries that migrations need - BEGIN, the migration SQL, COMMIT
+        mockPGlite.query.mockResolvedValue({ rows: [], fields: [], affectedRows: 0 })
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+        // Initialize without running migrations
+        await doo.initPGlite()
+
+        // First query should trigger migrations
+        await doo.executeQuery({ sql: 'SELECT 1' })
+
+        // Migration state should now be saved
+        const migrationState = storageData['__postgres_migration_state__'] as { status: string; version: number }
+        expect(migrationState).toBeDefined()
+        expect(migrationState.status).toBe('completed')
+        expect(migrationState.version).toBe(1)
+      })
+
+      it('should not run migrations on subsequent queries', async () => {
+        const state = createMockState()
+        let storageData: Record<string, unknown> = {
+          '__postgres_migration_state__': {
+            status: 'completed',
+            version: 1,
+            lastAttemptAt: '2024-01-01T00:00:00Z',
+          },
+        }
+        state.storage.get.mockImplementation((key: string) => Promise.resolve(storageData[key]))
+        state.storage.put.mockImplementation((key: string, value: unknown) => {
+          storageData[key] = value
+          return Promise.resolve()
+        })
+        const env = createMockEnv()
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            migrations: [{ id: '1', name: 'test', version: 1, sql: 'CREATE TABLE test (id INT)' }],
+            strategy: 'on-demand',
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const mockPGlite = createMockPGlite()
+        let execCallCount = 0
+        mockPGlite.exec.mockImplementation(() => {
+          execCallCount++
+          return Promise.resolve({ rows: [], fields: [] })
+        })
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+        await doo.initPGlite()
+
+        // Run multiple queries
+        await doo.executeQuery({ sql: 'SELECT 1' })
+        await doo.executeQuery({ sql: 'SELECT 2' })
+        await doo.executeQuery({ sql: 'SELECT 3' })
+
+        // exec should NOT have been called for migrations (already completed)
+        expect(execCallCount).toBe(0)
+      })
+    })
+
+    describe('rpcQuery with on-demand migrations', () => {
+      it('should run migrations before first RPC query', async () => {
+        const state = createMockState()
+        let storageData: Record<string, unknown> = {}
+        state.storage.get.mockImplementation((key: string) => Promise.resolve(storageData[key]))
+        state.storage.put.mockImplementation((key: string, value: unknown) => {
+          storageData[key] = value
+          return Promise.resolve()
+        })
+        const env = createMockEnv()
+        const config: PostgresConfig = {
+          database: 'test',
+          migrations: {
+            migrations: [{ id: '1', name: 'test', version: 1, sql: 'CREATE TABLE test (id INT)' }],
+            strategy: 'on-demand',
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const mockPGlite = createMockPGlite()
+        // Mock all queries that migrations need
+        mockPGlite.query.mockResolvedValue({ rows: [], fields: [], affectedRows: 0 })
+        vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+        await doo.initPGlite()
+
+        // RPC query should trigger migrations
+        await doo.rpcQuery('SELECT 1')
+
+        // Migration state should be saved
+        const migrationState = storageData['__postgres_migration_state__'] as { status: string }
+        expect(migrationState).toBeDefined()
+        expect(migrationState.status).toBe('completed')
+      })
+    })
+  })
+
+  // ============================================================================
+  // RED PHASE: Initialization Decoupling Tests
+  // Task: postgres-ud8w.1 - [RED] Add tests for initialization decoupling
+  //
+  // Tests for decoupling DO and PGLite initialization:
+  // 1. DO can be created without PGLite
+  // 2. PGLite can be created without DO context
+  // 3. Lazy initialization of PGLite
+  // 4. Proper initialization ordering
+  // 5. Error handling when dependencies missing
+  // 6. Dependency injection for testability
+  // 7. Factory pattern for PGLite creation
+  // ============================================================================
+
+  describe('Initialization Decoupling', () => {
+    describe('DO creation without PGLite', () => {
+      it('should create DO instance without initializing PGLite', () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        // DO should be created
+        expect(doo).toBeInstanceOf(PostgresDO)
+        // PGLite should NOT be initialized
+        expect(doo.isInitialized()).toBe(false)
+      })
+
+      it('should allow accessing DO methods before PGLite initialization', () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        // These methods should work without PGLite
+        expect(doo.getState()).toBe(state)
+        expect(doo.getEnv()).toBe(env)
+        expect(doo.getConfig()).toBeDefined()
+        expect(doo.getShutdownStatus()).toBe('running')
+        expect(doo.isInitialized()).toBe(false)
+      })
+
+      it('should return null from getPGLiteManager.getInstanceOrNull() before initialization', () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const manager = doo.getPGLiteManager()
+        expect(manager.getInstanceOrNull()).toBeNull()
+      })
+
+      it('should throw from getPGLiteManager.getInstance() before initialization', () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const manager = doo.getPGLiteManager()
+        expect(() => manager.getInstance()).toThrow('PGLite not initialized')
+      })
+    })
+
+    describe('PGLiteManager independence from DO', () => {
+      it('should allow creating PGLiteManager without DO context', async () => {
+        // Import PGLiteManager directly
+        const { PGLiteManager } = await import('./do-pglite-manager')
+
+        // Create manager without any DO
+        const manager = new PGLiteManager({
+          database: 'test-db',
+          debug: false,
+        })
+
+        expect(manager).toBeDefined()
+        expect(manager.isInitialized()).toBe(false)
+      })
+
+      it('should allow injecting custom PGLite factory for testing', async () => {
+        const { PGLiteManager } = await import('./do-pglite-manager')
+        const mockPGlite = createMockPGlite()
+
+        const manager = new PGLiteManager({
+          database: 'test-db',
+          createPGLite: () => Promise.resolve(mockPGlite),
+        })
+
+        await manager.initialize()
+
+        expect(manager.isInitialized()).toBe(true)
+        expect(manager.getInstance()).toBe(mockPGlite)
+      })
+
+      it('should allow injecting pre-created PGLite instance', async () => {
+        const { PGLiteManager } = await import('./do-pglite-manager')
+        const mockPGlite = createMockPGlite()
+
+        const manager = new PGLiteManager({ database: 'test-db' })
+        manager.injectInstance(mockPGlite)
+
+        expect(manager.isInitialized()).toBe(true)
+        expect(manager.getInstance()).toBe(mockPGlite)
+      })
+
+      it('should allow setting factory after construction', async () => {
+        const { PGLiteManager } = await import('./do-pglite-manager')
+        const mockPGlite = createMockPGlite()
+
+        const manager = new PGLiteManager({ database: 'test-db' })
+        manager.setCreatePGLite(() => Promise.resolve(mockPGlite))
+        await manager.initialize()
+
+        expect(manager.isInitialized()).toBe(true)
+        expect(manager.getInstance()).toBe(mockPGlite)
+      })
+    })
+
+    describe('Lazy initialization', () => {
+      it('should defer PGLite creation until first use', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        const createSpy = vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+        // PGLite should not be created yet
+        expect(createSpy).not.toHaveBeenCalled()
+        expect(doo.isInitialized()).toBe(false)
+
+        // First query triggers initialization
+        await doo.executeQuery({ sql: 'SELECT 1' })
+
+        // Now PGLite should be created
+        expect(createSpy).toHaveBeenCalledTimes(1)
+        expect(doo.isInitialized()).toBe(true)
+      })
+
+      it('should not re-initialize on subsequent queries', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        const createSpy = vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+        // Multiple queries
+        await doo.executeQuery({ sql: 'SELECT 1' })
+        await doo.executeQuery({ sql: 'SELECT 2' })
+        await doo.executeQuery({ sql: 'SELECT 3' })
+
+        // Should only initialize once
+        expect(createSpy).toHaveBeenCalledTimes(1)
+      })
+
+      it('should support explicit initialization before first use', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        const createSpy = vi.spyOn(doo as any, 'createPGliteInstance').mockResolvedValue(mockPGlite)
+
+        // Explicit initialization
+        await doo.initPGlite()
+
+        expect(doo.isInitialized()).toBe(true)
+        expect(createSpy).toHaveBeenCalledTimes(1)
+
+        // Subsequent query should not re-initialize
+        await doo.executeQuery({ sql: 'SELECT 1' })
+        expect(createSpy).toHaveBeenCalledTimes(1)
+      })
+    })
+
+    describe('Initialization ordering', () => {
+      it('should initialize components in correct order: factory -> plugins -> migrations', async () => {
+        const state = createMockState()
+        state.storage.get.mockResolvedValue(undefined)
+        const env = createMockEnv()
+        const config: PostgresConfig = {
+          database: 'test',
+          plugins: { vector: true },
+          migrations: {
+            migrations: [{ id: '1', name: 'test', version: 1, sql: 'SELECT 1' }],
+          },
+        }
+        const doo = new PostgresDO(state as any, env, config)
+
+        const executionOrder: string[] = []
+        const mockPGlite = createMockPGlite()
+
+        // Track when PGLite is created
+        vi.spyOn(doo as any, 'createPGliteInstance').mockImplementation(async () => {
+          executionOrder.push('pglite_created')
+          return mockPGlite
+        })
+
+        // Track when plugins are loaded
+        vi.spyOn(doo as any, 'runPluginAutoCreate').mockImplementation(async () => {
+          executionOrder.push('plugins_loaded')
+        })
+
+        await doo.initPGlite()
+
+        // PGLite should be created before plugins
+        expect(executionOrder.indexOf('pglite_created')).toBeLessThan(
+          executionOrder.indexOf('plugins_loaded')
+        )
+      })
+
+      it('should handle concurrent initialization calls safely', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        let initCount = 0
+        vi.spyOn(doo as any, 'createPGliteInstance').mockImplementation(async () => {
+          initCount++
+          await new Promise((r) => setTimeout(r, 10))
+          return mockPGlite
+        })
+
+        // Start multiple concurrent initializations
+        const promises = [
+          doo.initPGlite(),
+          doo.initPGlite(),
+          doo.initPGlite(),
+        ]
+
+        await Promise.all(promises)
+
+        // Should only actually initialize once
+        expect(initCount).toBe(1)
+      })
+    })
+
+    describe('Dependency injection for testability', () => {
+      it('should allow injecting mock PGLite via manager', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        mockPGlite.query.mockResolvedValue({
+          rows: [{ result: 42 }],
+          fields: [{ name: 'result', dataTypeID: 23 }],
+          affectedRows: 1,
+        })
+
+        // Inject mock directly into manager
+        doo.getPGLiteManager().injectInstance(mockPGlite)
+
+        // Query should use the injected mock
+        const result = await doo.executeQuery({ sql: 'SELECT 42 as result' })
+
+        expect(result.rows).toEqual([{ result: 42 }])
+        expect(mockPGlite.query).toHaveBeenCalled()
+      })
+
+      it('should allow setting factory function on manager', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        let factoryCalled = false
+
+        doo.getPGLiteManager().setCreatePGLite(async () => {
+          factoryCalled = true
+          return mockPGlite
+        })
+
+        await doo.initPGlite()
+
+        expect(factoryCalled).toBe(true)
+        expect(doo.isInitialized()).toBe(true)
+      })
+
+      it('should override default WASM loading with custom factory', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const mockPGlite = createMockPGlite()
+        const customFactory = vi.fn().mockResolvedValue(mockPGlite)
+
+        doo.getPGLiteManager().setCreatePGLite(customFactory)
+        await doo.initPGlite()
+
+        // Custom factory should be used instead of default WASM loading
+        expect(customFactory).toHaveBeenCalled()
+      })
+    })
+
+    describe('Error handling when dependencies missing', () => {
+      it('should throw descriptive error when trying to execute query without initialization and factory fails', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        vi.spyOn(doo as any, 'createPGliteInstance').mockRejectedValue(
+          new Error('WASM module not found')
+        )
+
+        await expect(doo.executeQuery({ sql: 'SELECT 1' })).rejects.toThrow(
+          'WASM module not found'
+        )
+      })
+
+      it('should provide clear error when getInstance called before init', async () => {
+        const { PGLiteManager } = await import('./do-pglite-manager')
+        const manager = new PGLiteManager({ database: 'test' })
+
+        expect(() => manager.getInstance()).toThrow('PGLite not initialized')
+      })
+
+      it('should handle factory returning null gracefully', async () => {
+        const { PGLiteManager } = await import('./do-pglite-manager')
+        const manager = new PGLiteManager({
+          database: 'test',
+          createPGLite: () => Promise.resolve(null as any),
+        })
+
+        // Should throw during initialization when factory returns null
+        await expect(manager.initialize()).rejects.toThrow()
+      })
+
+      it('should propagate factory errors with context', async () => {
+        const state = createMockState()
+        const env = createMockEnv()
+        const doo = new PostgresDO(state as any, env)
+
+        const originalError = new Error('Custom factory failed')
+        doo.getPGLiteManager().setCreatePGLite(() => Promise.reject(originalError))
+
+        try {
+          await doo.initPGlite()
+          expect.fail('Should have thrown')
+        } catch (error) {
+          expect(error).toBe(originalError)
+        }
+      })
+    })
+
+    describe('Manager reset and cleanup', () => {
+      it('should allow resetting manager state', async () => {
+        const { PGLiteManager } = await import('./do-pglite-manager')
+        const mockPGlite = createMockPGlite()
+
+        const manager = new PGLiteManager({
+          database: 'test',
+          createPGLite: () => Promise.resolve(mockPGlite),
+        })
+
+        await manager.initialize()
+        expect(manager.isInitialized()).toBe(true)
+
+        manager.reset()
+        expect(manager.isInitialized()).toBe(false)
+        expect(manager.getInstanceOrNull()).toBeNull()
+      })
+
+      it('should allow re-initialization after reset', async () => {
+        const { PGLiteManager } = await import('./do-pglite-manager')
+        const mockPGlite1 = createMockPGlite()
+        const mockPGlite2 = createMockPGlite()
+        let callCount = 0
+
+        const manager = new PGLiteManager({
+          database: 'test',
+          createPGLite: () => Promise.resolve(callCount++ === 0 ? mockPGlite1 : mockPGlite2),
+        })
+
+        // First initialization
+        await manager.initialize()
+        expect(manager.getInstance()).toBe(mockPGlite1)
+
+        // Reset
+        manager.reset()
+
+        // Re-initialize
+        await manager.initialize()
+        expect(manager.getInstance()).toBe(mockPGlite2)
+      })
+
+      it('should close PGLite instance on manager close', async () => {
+        const { PGLiteManager } = await import('./do-pglite-manager')
+        const mockPGlite = createMockPGlite()
+
+        const manager = new PGLiteManager({
+          database: 'test',
+          createPGLite: () => Promise.resolve(mockPGlite),
+        })
+
+        await manager.initialize()
+        await manager.close()
+
+        expect(mockPGlite.close).toHaveBeenCalled()
+        expect(manager.isInitialized()).toBe(false)
+      })
+    })
+
+    describe('Liveness check without full initialization', () => {
+      it('should return false for liveness check before initialization', async () => {
+        const { PGLiteManager } = await import('./do-pglite-manager')
+        const manager = new PGLiteManager({ database: 'test' })
+
+        const isAlive = await manager.checkLiveness()
+        expect(isAlive).toBe(false)
+      })
+
+      it('should return true for liveness check after successful initialization', async () => {
+        const { PGLiteManager } = await import('./do-pglite-manager')
+        const mockPGlite = createMockPGlite()
+        mockPGlite.query.mockResolvedValue({
+          rows: [{ alive: 1 }],
+          fields: [],
+          affectedRows: 0,
+        })
+
+        const manager = new PGLiteManager({
+          database: 'test',
+          createPGLite: () => Promise.resolve(mockPGlite),
+        })
+
+        await manager.initialize()
+        const isAlive = await manager.checkLiveness()
+        expect(isAlive).toBe(true)
+      })
+
+      it('should return false for liveness check if query fails', async () => {
+        const { PGLiteManager } = await import('./do-pglite-manager')
+        const mockPGlite = createMockPGlite()
+        mockPGlite.query.mockRejectedValue(new Error('Query failed'))
+
+        const manager = new PGLiteManager({
+          database: 'test',
+          createPGLite: () => Promise.resolve(mockPGlite),
+        })
+
+        await manager.initialize()
+        const isAlive = await manager.checkLiveness()
+        expect(isAlive).toBe(false)
+      })
+    })
+  })
+})
+
+// MOCK REDUCTION EXAMPLES (postgres-6qei)
+// These tests demonstrate the recommended pattern using helper functions.
+describe('PostgresDO with Mock Reduction Helpers', () => {
+  describe('Query execution (using createTestDO)', () => {
+    it('should execute queries using injected mock', async () => {
+      const { doo } = createTestDO({
+        mockPGliteSetup: (mock) => {
+          mock.query.mockResolvedValue({
+            rows: [{ id: 1, name: 'Alice' }],
+            fields: [{ name: 'id', dataTypeID: 23 }],
+            affectedRows: 1,
+          })
+        },
+      })
+      const result = await doo.executeQuery({ sql: 'SELECT * FROM users' })
+      expect(result.rows).toEqual([{ id: 1, name: 'Alice' }])
+    })
+
+    it('should pass parameters correctly', async () => {
+      const { doo, mockPGlite } = createTestDO()
+      await doo.executeQuery({
+        sql: 'SELECT * FROM users WHERE id = $1',
+        params: [42],
+      })
+      expect(mockPGlite.query).toHaveBeenCalledWith(
+        'SELECT * FROM users WHERE id = $1',
+        [42]
+      )
+    })
+  })
+
+  describe('Initialization (using createTestDOWithFactory)', () => {
+    it('should initialize PGlite on first call', async () => {
+      const { doo } = createTestDOWithFactory()
+      expect(doo.isInitialized()).toBe(false)
+      await doo.initPGlite()
+      expect(doo.isInitialized()).toBe(true)
+    })
+
+    it('should prevent double initialization', async () => {
+      let factoryCallCount = 0
+      const state = createMockState()
+      const env = createMockEnv()
+      const doo = new PostgresDO(state as any, env)
+      const mockPGlite = createMockPGlite()
+      doo.getPGLiteManager().setCreatePGLite(async () => {
+        factoryCallCount++
+        return mockPGlite
+      })
+      await doo.initPGlite()
+      await doo.initPGlite()
+      expect(factoryCallCount).toBe(1)
+    })
+  })
+
+  describe('Shutdown (using createTestDO)', () => {
+    it('should close PGlite during shutdown', async () => {
+      const { doo, mockPGlite } = createTestDO()
+      await doo.shutdown({ gracePeriodMs: 100 })
+      expect(mockPGlite.close).toHaveBeenCalled()
+      expect(doo.getShutdownStatus()).toBe('shutdown')
+    })
+
+    it('should reject queries after shutdown', async () => {
+      const { doo } = createTestDO()
+      await doo.shutdown({ gracePeriodMs: 100 })
+      await expect(doo.executeQuery({ sql: 'SELECT 1' }))
+        .rejects.toThrow('PostgresDO is shut down')
+    })
+  })
+})