@owlmeans/postgres 0.1.15

package/src/utils/connection.ts

@@ -0,0 +1,64 @@
+import { pgErrorToResourceError, PostgresConnectionError, quoteIdent } from '@owlmeans/postgres-resource'
+import type { PostgresMeta } from '@owlmeans/postgres-resource'
+import type { Pool } from 'pg'
+
+import { DEF_RETRIES, DEF_RETRY_DELAY, TERMINAL_CONNECT_CODES } from '../consts.js'
+
+/**
+ * Retryable means "the server isn't up yet". A driver level failure carries no `code` at
+ * all (`ECONNREFUSED`, DNS) and is exactly the case worth waiting on; a Postgres error
+ * code that names a credential or catalog problem will say the same thing in a minute.
+ */
+const isTransient = (error: unknown): boolean => {
+  const code = (error as { code?: string } | null)?.code
+  if (code == null) {
+    return true
+  }
+
+  return !TERMINAL_CONNECT_CODES.includes(code)
+}
+
+/**
+ * Wait for the server to answer a query, not merely to accept a socket.
+ *
+ * Postgres binds its port before it finishes recovery, so a sidecar or an operator managed
+ * instance routinely accepts a connection and then refuses to run anything. Every OwlMeans
+ * deployment grew its own copy of this loop; this is the one.
+ *
+ * @throws {PostgresConnectionError}
+ */
+export const probe = async (pool: Pool, meta: PostgresMeta, location: string): Promise<void> => {
+  const retries = Math.max(1, meta.retries ?? DEF_RETRIES)
+  const delay = meta.retryDelayMillis ?? DEF_RETRY_DELAY
+  let last: unknown
+
+  for (let attempt = 1; attempt <= retries; ++attempt) {
+    try {
+      await pool.query('SELECT 1')
+
+      return
+    } catch (error) {
+      last = error
+      if (attempt === retries || !isTransient(error)) {
+        break
+      }
+      console.log(`${location}: not ready (${attempt}/${retries}), retrying in ${delay}ms…`)
+      await new Promise(resolve => setTimeout(resolve, delay))
+    }
+  }
+
+  const translated = pgErrorToResourceError(last)
+  const failure = new PostgresConnectionError(`unreachable:${location}:${translated.message}`)
+  failure.cause = last
+
+  throw failure
+}
+
+/** `CREATE SCHEMA IF NOT EXISTS` on a pooled connection. */
+export const ensureSchema = async (pool: Pool, schema: string): Promise<void> => {
+  try {
+    await pool.query(`CREATE SCHEMA IF NOT EXISTS ${quoteIdent(schema)}`)
+  } catch (error) {
+    throw pgErrorToResourceError(error)
+  }
+}

package/tests/bootstrap.spec.ts

@@ -0,0 +1,142 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { PostgresBootstrapError } from '@owlmeans/postgres-resource'
+import { randomNamespace } from '@owlmeans/test-integration'
+import { Pool } from 'pg'
+
+import { DEF_ADMIN_ALIAS } from '@owlmeans/postgres'
+import { capabilities, gate, makeSuite, raw } from './context.js'
+import type { PostgresService } from './context.js'
+
+const suite = makeSuite('bootstrap')
+const closed = gate.skip || !capabilities.bootstrap
+const it = closed ? test.skip : test
+
+const role = randomNamespace('omt_role')
+const database = randomNamespace('omt_db')
+/** Never printed, never persisted — generated per run and dropped with the role. */
+const password = randomNamespace('pw', 24)
+const schema = 'app'
+
+/** The gate's URL is the only statement of where Postgres is; nothing here assumes 5432. */
+const target = (): { host: string, port: number } => {
+  const parsed = new URL(gate.env.POSTGRES_URL ?? 'postgres://127.0.0.1:5432/postgres')
+
+  return {
+    host: decodeURIComponent(parsed.hostname).replace(/^\[|\]$/g, ''),
+    port: parsed.port !== '' ? parseInt(parsed.port, 10) : 5432
+  }
+}
+
+describe('@owlmeans/postgres — admin bootstrap path', () => {
+  if (closed) {
+    test.skip(
+      gate.skip
+        ? gate.reason ?? 'postgres gate closed'
+        : 'connection role has neither CREATEROLE+CREATEDB nor superuser',
+      () => {}
+    )
+
+    return
+  }
+
+  let pg: PostgresService
+
+  beforeAll(async () => {
+    pg = (await suite.boot({ admin: true })).pg
+  })
+
+  afterAll(async () => {
+    /** The admin alias connects lazily, so its pool only exists once bootstrap has run. */
+    suite.collect(pg)
+    await suite.teardown()
+
+    /**
+     * A database and a role outlive the schema the suite owns, so they are dropped here
+     * rather than by the shared teardown — and the role only after everything it owns is
+     * gone, which is what `DROP OWNED BY` guarantees.
+     */
+    await raw(async pool => {
+      await pool.query(`DROP DATABASE IF EXISTS "${database}" WITH (FORCE)`)
+      await pool.query(`DROP OWNED BY "${role}"`).catch(() => undefined)
+      await pool.query(`DROP ROLE IF EXISTS "${role}"`)
+    }).catch(error => console.error(`postgres bootstrap teardown (${role}@${database}):`, error))
+  })
+
+  it('creates the role, its database and its schema', async () => {
+    const report = await pg.bootstrap(DEF_ADMIN_ALIAS, { role, password, database, schema })
+
+    expect(report).toEqual({
+      roleCreated: true,
+      passwordRotated: false,
+      databaseCreated: true,
+      schemaCreated: true,
+      grantsApplied: true
+    })
+  })
+
+  it('lets the new role connect and own its schema', async () => {
+    const pool = new Pool({ ...target(), user: role, password, database, max: 1 })
+    try {
+      /** `ALTER ROLE ... SET search_path` is what puts the role in its own schema on login. */
+      const { rows } = await pool.query<{ schema: string, owner: string, pub: boolean }>(
+        `SELECT current_schema() AS schema, pg_get_userbyid(nspowner) AS owner,
+                has_schema_privilege('public', 'public', 'CREATE') AS pub
+           FROM pg_namespace WHERE nspname = $1`, [schema]
+      )
+      expect(rows[0].schema).toBe(schema)
+      expect(rows[0].owner).toBe(role)
+      /** `REVOKE CREATE ON SCHEMA public FROM PUBLIC` — nothing lands in `public` by accident. */
+      expect(rows[0].pub).toBe(false)
+
+      /** An unqualified table goes to the role's own schema, which it owns outright. */
+      await pool.query('CREATE TABLE probe (id text)')
+      const [{ nspname }] = (await pool.query<{ nspname: string }>(
+        `SELECT n.nspname FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+          WHERE c.relname = 'probe'`
+      )).rows
+      expect(nspname).toBe(schema)
+      await pool.query('DROP TABLE probe')
+    } finally {
+      await pool.end().catch(() => undefined)
+    }
+  })
+
+  it('revokes PUBLIC and grants the role instead', async () => {
+    const [row] = await raw(async pool => (await pool.query<{ pub: boolean, own: boolean }>(
+      `SELECT has_database_privilege('public', $1, 'CONNECT') AS pub,
+              has_database_privilege($2, $1, 'CONNECT') AS own`, [database, role]
+    )).rows)
+
+    expect(row.pub).toBe(false)
+    expect(row.own).toBe(true)
+  })
+
+  it('is idempotent — a second run rotates the password and creates nothing', async () => {
+    const report = await pg.bootstrap(DEF_ADMIN_ALIAS, { role, password, database, schema })
+
+    expect(report.roleCreated).toBe(false)
+    expect(report.databaseCreated).toBe(false)
+    expect(report.passwordRotated).toBe(true)
+    /** `CREATE SCHEMA IF NOT EXISTS` is a no-op, but the grants are re-asserted every time. */
+    expect(report.schemaCreated).toBe(true)
+    expect(report.grantsApplied).toBe(true)
+  })
+
+  it('leaves an existing password alone when asked to', async () => {
+    const report = await pg.bootstrap(
+      DEF_ADMIN_ALIAS, { role, password, database, schema, rotatePassword: false }
+    )
+
+    expect(report.passwordRotated).toBe(false)
+    expect(report.roleCreated).toBe(false)
+  })
+
+  it('refuses an identifier it cannot prove safe, before it connects to anything', async () => {
+    await expect(pg.bootstrap(DEF_ADMIN_ALIAS, { role: 'role"; DROP DATABASE x; --', password }))
+      .rejects.toThrow(SyntaxError)
+    await expect(pg.bootstrap(DEF_ADMIN_ALIAS, { role, password, database: 'has space' }))
+      .rejects.toThrow(SyntaxError)
+    await expect(pg.bootstrap(DEF_ADMIN_ALIAS, { role, password: '' }))
+      .rejects.toThrow(PostgresBootstrapError)
+  })
+})

package/tests/context.ts

@@ -0,0 +1,204 @@
+import { postgresGate, randomNamespace } from '@owlmeans/test-integration'
+import type { IntegrationGate, PostgresEnv } from '@owlmeans/test-integration'
+import { PgAutoSync, resetPlaceholderCache } from '@owlmeans/postgres-resource'
+import type { PostgresResource } from '@owlmeans/postgres-resource'
+import type { ResourceRecord } from '@owlmeans/resource'
+import { config, makeServerContext } from '@owlmeans/server-context'
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+import { Pool } from 'pg'
+
+import { appendPostgres, DEF_ADMIN_ALIAS } from '@owlmeans/postgres'
+import type { PostgresService } from '@owlmeans/postgres'
+
+/**
+ * Integration harness for the Postgres pair.
+ *
+ * Unlike the `mongo-resource` pilot, which only proves the gate/namespace/cleanup pattern
+ * against the raw driver, these suites build a real `ServerContext` and drive
+ * `makePostgresResource` end to end — a resource is meaningless without the db service
+ * that backs it, which is why the specs live in this package rather than the resource one
+ * (the reverse would make `@owlmeans/postgres-resource` dev-depend on its own dependent).
+ */
+export const gate: IntegrationGate<PostgresEnv> = postgresGate()
+
+const url = (): string => gate.env.POSTGRES_URL as string
+
+/** Short lived, single connection pool for setup and assertions outside any context. */
+export const raw = async <R>(fn: (pool: Pool) => Promise<R>): Promise<R> => {
+  const pool = new Pool({ connectionString: url(), max: 1 })
+  try {
+    return await fn(pool)
+  } finally {
+    await pool.end().catch(() => undefined)
+  }
+}
+
+export interface PgCapabilities {
+  /** The connection role can CREATE ROLE and CREATE DATABASE — what the admin path needs. */
+  bootstrap: boolean
+}
+
+/**
+ * Probed once, at module load, because Bun decides `test` vs `test.skip` synchronously and
+ * a suite cannot await its own gate. A role without `CREATEROLE`/`CREATEDB` still runs
+ * everything else — only the bootstrap suite self-skips.
+ */
+export const capabilities: PgCapabilities = gate.skip
+  ? { bootstrap: false }
+  : await raw(async pool => {
+    const { rows } = await pool.query<{ super: boolean, role: boolean, db: boolean }>(
+      `SELECT rolsuper AS "super", rolcreaterole AS role, rolcreatedb AS db
+         FROM pg_roles WHERE rolname = current_user`
+    )
+    const row = rows[0]
+
+    return { bootstrap: row != null && (row.super || (row.role && row.db)) }
+  }).catch(() => ({ bootstrap: false }))
+
+export interface BootOptions {
+  /** Registered in the order given — which is *not* dependency order, deliberately. */
+  resources?: Array<PostgresResource<any>>
+  autoSync?: PgAutoSync
+  /** Also configure a second alias pointing at the same server, for the admin path. */
+  admin?: boolean
+}
+
+export type { PostgresResource, PostgresService }
+
+export interface Booted {
+  context: ServerContext<ServerConfig>
+  pg: PostgresService
+}
+
+export interface PgSuite {
+  /** Postgres SCHEMA this suite owns end to end. Dropped by {@link teardown}. */
+  schema: string
+  boot: (opts?: BootOptions) => Promise<Booted>
+  /**
+   * Track pools a service opened *after* `boot()` returned. Config aliases connect lazily,
+   * so an alias only reached later — the admin one — has no pool at init time.
+   */
+  collect: (pg: PostgresService) => void
+  teardown: () => Promise<void>
+}
+
+/**
+ * One namespace per suite, torn down by that suite's own `afterAll`.
+ *
+ * The shared `registerCleanup`/`runCleanups` queue is process global, and Bun runs every
+ * spec file of a package in one process — so the first file to finish would drop the
+ * namespaces of the files still to come.
+ */
+export const makeSuite = (label: string): PgSuite => {
+  const prefix = process.env.POSTGRES_TEST_DB_PREFIX ?? 'omt'
+  const schema = randomNamespace(`${prefix}_${label}`)
+  const pools: Pool[] = []
+
+  const boot = async (opts: BootOptions = {}): Promise<Booted> => {
+    /**
+     * The cache is keyed by context and a context is never rebooted, so entries from a
+     * previous `boot()` are dead weight rather than a hazard — but a suite that runs ten
+     * boots would otherwise carry all ten.
+     *
+     * Declarations are deliberately *not* reset here. They survive a context switch on
+     * purpose (that is the whole point of keying them by alias), and a `.migration()`
+     * registered before `boot()` would be silently dropped. A spec that wants a clean
+     * slate calls `resetDeclarations(alias)` itself, which is exactly what a spec
+     * simulating a restarted process should have to say out loud.
+     */
+    resetPlaceholderCache()
+
+    const meta = { url: url(), max: 2, retries: 3, retryDelayMillis: 200 }
+    const cfg: ServerConfig = config('pg-test', {
+      dbs: [
+        {
+          service: 'postgres',
+          alias: 'postgres',
+          host: '127.0.0.1',
+          schema,
+          meta: { ...meta, autoSync: opts.autoSync ?? PgAutoSync.Full }
+        },
+        ...(opts.admin === true
+          ? [{ service: 'postgres', alias: DEF_ADMIN_ALIAS, host: '127.0.0.1', meta }]
+          : [])
+      ]
+    } as Partial<ServerConfig>)
+
+    const context = makeServerContext(cfg) as ServerContext<ServerConfig>
+    appendPostgres(context)
+
+    for (const resource of opts.resources ?? []) {
+      context.registerResource(resource as never)
+    }
+
+    context.configure()
+    const pg = context.service<PostgresService>('postgres')
+    try {
+      await context.init()
+    } finally {
+      /**
+       * Captured in `finally` because the suites that assert a *failed* boot — a refused
+       * cast, a throwing migration — open a pool before the failure and would otherwise
+       * leak it for the rest of the run.
+       */
+      collect(pg)
+    }
+
+    return { context, pg }
+  }
+
+  const collect = (pg: PostgresService): void => {
+    for (const pool of Object.values(pg.clients ?? {})) {
+      if (!pools.includes(pool)) {
+        pools.push(pool)
+      }
+    }
+  }
+
+  const teardown = async (): Promise<void> => {
+    if (gate.skip) {
+      return
+    }
+    await raw(async pool => { await pool.query(`DROP SCHEMA IF EXISTS "${schema}" CASCADE`) })
+      .catch(error => console.error(`postgres test teardown (${schema}):`, error))
+    /** After the drop — a pool still holding the schema open makes CASCADE wait. */
+    while (pools.length > 0) {
+      await pools.pop()?.end().catch(() => undefined)
+    }
+  }
+
+  return { schema, boot, collect, teardown }
+}
+
+/** Columns of a table as Postgres currently reports them, `name → "type[ NOT NULL]"`. */
+export const shapeOf = async (
+  pg: PostgresService, schema: string, table: string
+): Promise<Record<string, string>> => {
+  const rows = await pg.query<{ name: string, type: string, not_null: boolean }>(
+    `SELECT a.attname AS name, format_type(a.atttypid, a.atttypmod) AS type, a.attnotnull AS not_null
+       FROM pg_attribute a
+      WHERE a.attrelid = to_regclass($1) AND a.attnum > 0 AND NOT a.attisdropped
+      ORDER BY a.attnum`,
+    [`"${schema}"."${table}"`]
+  )
+
+  return Object.fromEntries(rows.map(row => [row.name, `${row.type}${row.not_null ? ' NOT NULL' : ''}`]))
+}
+
+export interface LedgerRow {
+  alias: string
+  name: string
+  stage: string
+  baseline: boolean
+}
+
+export const ledgerOf = async (pg: PostgresService, schema: string): Promise<LedgerRow[]> =>
+  await pg.query<LedgerRow & Record<string, unknown>>(
+    `SELECT alias, name, stage, baseline FROM "${schema}"."_owlmeans_migrations" ORDER BY name`
+  )
+
+export interface Note extends ResourceRecord {
+  id?: string
+  title: string
+  slug?: string
+}

package/tests/crud.spec.ts

@@ -0,0 +1,227 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { makePostgresResource } from '@owlmeans/postgres-resource'
+import type { PostgresResource } from '@owlmeans/postgres-resource'
+import { RecordExists, UnknownRecordError } from '@owlmeans/resource'
+import type { ResourceRecord } from '@owlmeans/resource'
+
+import { gate, makeSuite, shapeOf } from './context.js'
+import type { PostgresService } from '@owlmeans/postgres'
+
+interface User extends ResourceRecord {
+  id?: string
+  email: string
+  status?: string
+  age?: number
+  tags?: string[]
+  profile?: Record<string, unknown>
+  createdAt?: Date
+}
+
+interface Post extends ResourceRecord {
+  id?: string
+  ownerId: string
+  title: string
+}
+
+const userSchema = {
+  type: 'object',
+  properties: {
+    id: { type: 'string', format: 'uuid' },
+    email: { type: 'string', pg: { type: 'varchar', length: 320, unique: true } },
+    status: { type: 'string', enum: ['active', 'banned'], nullable: true, default: 'active' },
+    age: { type: 'integer', nullable: true },
+    tags: { type: 'array', items: { type: 'string' }, nullable: true },
+    profile: { type: 'object', nullable: true },
+    createdAt: { type: 'object', format: 'date-time', nullable: true, pg: { defaultRaw: 'now()' } }
+  },
+  required: ['id', 'email'],
+  pg: { indexes: [{ name: 'idx_crud_users_status', columns: ['status'] }] }
+} as never
+
+const postSchema = {
+  type: 'object',
+  properties: {
+    id: { type: 'string', format: 'uuid' },
+    ownerId: { type: 'string', format: 'uuid', pg: { references: { resource: 'crud-users', onDelete: 'cascade' } } },
+    title: { type: 'string' }
+  },
+  required: ['id', 'ownerId', 'title']
+} as never
+
+const suite = makeSuite('crud')
+const it = gate.skip ? test.skip : test
+
+describe('@owlmeans/postgres — resource CRUD against a real context', () => {
+  if (gate.skip) {
+    test.skip(gate.reason ?? 'postgres gate closed', () => {})
+
+    return
+  }
+
+  let pg: PostgresService
+  let users: PostgresResource<User>
+  let posts: PostgresResource<Post>
+  let seeded: User
+
+  beforeAll(async () => {
+    const user = makePostgresResource<User, PostgresResource<User>>('crud-users')
+    user.schema = userSchema
+    const post = makePostgresResource<Post, PostgresResource<Post>>('crud-posts')
+    post.schema = postSchema
+
+    /** Posts first: registration order is not dependency order, and must not have to be. */
+    const booted = await suite.boot({ resources: [post, user] })
+    pg = booted.pg
+    users = booted.context.resource<PostgresResource<User>>('crud-users')
+    posts = booted.context.resource<PostgresResource<Post>>('crud-posts')
+
+    seeded = await users.create({ email: 'a@b.c', age: 21, tags: ['x', 'y'], profile: { city: 'Kyiv' } })
+    await posts.create({ ownerId: seeded.id as string, title: 'hello' })
+  })
+
+  afterAll(async () => {
+    await suite.teardown()
+  })
+
+  it('creates the table the AJV schema describes', async () => {
+    expect(users.table.qualified).toBe(`"${suite.schema}"."crud_users"`)
+
+    expect(await shapeOf(pg, suite.schema, 'crud_users')).toEqual({
+      id: 'uuid NOT NULL',
+      email: 'character varying(320) NOT NULL',
+      status: 'text',
+      age: 'integer',
+      tags: 'text[]',
+      profile: 'jsonb',
+      createdAt: 'timestamp with time zone'
+    })
+  })
+
+  it('creates the constraints and indexes the schema implies', async () => {
+    const constraints = await pg.query<{ conname: string, def: string }>(
+      `SELECT conname, pg_get_constraintdef(oid) AS def FROM pg_constraint WHERE conrelid = $1::regclass`,
+      [`"${suite.schema}".crud_users`]
+    )
+    const definitions = constraints.map(row => row.def)
+
+    expect(definitions).toContain('PRIMARY KEY (id)')
+    expect(definitions).toContain('UNIQUE (email)')
+    /** A string enum becomes a CHECK — a native enum can't drop values or be altered in a transaction. */
+    expect(definitions.some(def => def.includes('CHECK') && def.includes("'banned'"))).toBe(true)
+
+    const indexes = await pg.query<{ indexname: string }>(
+      `SELECT indexname FROM pg_indexes WHERE schemaname = $1 AND tablename = $2`,
+      [suite.schema, 'crud_users']
+    )
+    expect(indexes.map(row => row.indexname)).toContain('idx_crud_users_status')
+  })
+
+  /**
+   * The key targets a table another resource owns, and resource `init()` runs in
+   * registration order. It is applied by the Loading middleware instead — the first moment
+   * every table is known to exist.
+   */
+  it('applies a deferred foreign key after every resource has initialized', async () => {
+    const keys = await pg.query<{ def: string }>(
+      `SELECT pg_get_constraintdef(oid) AS def FROM pg_constraint
+        WHERE conrelid = $1::regclass AND contype = 'f'`,
+      [`"${suite.schema}".crud_posts`]
+    )
+
+    expect(keys).toHaveLength(1)
+    expect(keys[0].def).toContain(`REFERENCES ${suite.schema}.crud_users(id)`)
+    expect(keys[0].def).toContain('ON DELETE CASCADE')
+  })
+
+  it('round-trips a record through create and get', async () => {
+    const loaded = await users.get(seeded.id as string)
+
+    expect(loaded.email).toBe('a@b.c')
+    expect(loaded.age).toBe(21)
+    expect(loaded.tags).toEqual(['x', 'y'])
+    expect(loaded.profile).toEqual({ city: 'Kyiv' })
+    /** Schema defaults are applied on the way in, not only in DDL. */
+    expect(loaded.status).toBe('active')
+    /** Drizzle's node-postgres session replaces the driver's date parsers; the marshaller restores them. */
+    expect(loaded.createdAt).toBeInstanceOf(Date)
+  })
+
+  it('loads by a field other than the primary key, and refuses an unknown record', async () => {
+    const byEmail = await users.load('a@b.c', 'email')
+    expect(byEmail?.id).toBe(seeded.id as string)
+
+    expect(await users.load('nobody@nowhere', 'email')).toBeNull()
+    await expect(users.get('nobody@nowhere', 'email')).rejects.toThrow(UnknownRecordError)
+  })
+
+  it('patches by merge where update replaces the whole record', async () => {
+    const patched = await users.patch<User>({ id: seeded.id, age: 22 })
+    expect(patched.age).toBe(22)
+    expect(patched.email).toBe('a@b.c')
+
+    const replaced = await users.update({ id: seeded.id, email: 'a@b.c', status: 'banned' })
+    expect(replaced.status).toBe('banned')
+    /** Mongo's `replaceOne` semantics: a field absent from the record is absent afterwards. */
+    expect(replaced.age ?? null).toBeNull()
+  })
+
+  it('lists by criteria and reports a total independent of the page', async () => {
+    await users.create({ email: 'second@b.c', status: 'banned' })
+    await users.create({ email: 'third@b.c', status: 'active' })
+
+    const banned = await users.list({ status: 'banned' })
+    expect(banned.pager?.total).toBe(2)
+    expect(banned.items.every(item => item.status === 'banned')).toBe(true)
+
+    const paged = await users.list({}, { pager: { page: 0, size: 2 } })
+    expect(paged.items).toHaveLength(2)
+    expect(paged.pager?.total).toBe(3)
+
+    const sorted = await users.list({}, { pager: { sort: [['email', false]] } })
+    expect(sorted.items.map(item => item.email)).toEqual(['a@b.c', 'second@b.c', 'third@b.c'])
+  })
+
+  it('counts and purges by criteria', async () => {
+    expect(await users.count()).toBe(3)
+    expect(await users.count({ status: 'banned' })).toBe(2)
+
+    expect(await users.purge({ email: 'third@b.c' })).toBe(1)
+    expect(await users.count()).toBe(2)
+  })
+
+  it('refuses a caller supplied id in create and accepts one in insert', async () => {
+    await expect(users.create({ id: '00000000-0000-4000-8000-000000000001', email: 'no@b.c' }))
+      .rejects.toThrow(RecordExists)
+
+    const inserted = await users.insert<User>({
+      id: '00000000-0000-4000-8000-000000000002', email: 'explicit@b.c'
+    })
+    expect(inserted.id).toBe('00000000-0000-4000-8000-000000000002')
+    await users.delete(inserted.id as string)
+  })
+
+  it('upserts on an arbiter that is not the primary key', async () => {
+    const upserted = await users.upsert<User>({ email: 'a@b.c', age: 44 }, ['email'])
+
+    expect(upserted.id).toBe(seeded.id as string)
+    expect(upserted.age).toBe(44)
+    expect(await users.count()).toBe(2)
+  })
+
+  it('reports a unique violation as RecordExists', async () => {
+    await expect(users.create({ email: 'a@b.c' })).rejects.toThrow(RecordExists)
+  })
+
+  it('picks a record by deleting it, atomically', async () => {
+    const before = await users.count()
+    expect(await posts.count()).toBe(1)
+
+    const picked = await users.pick(seeded.id as string)
+
+    expect(picked.email).toBe('a@b.c')
+    expect(await users.count()).toBe(before - 1)
+    /** The cascade is the database's, not the resource's — the post goes with its owner. */
+    expect(await posts.count()).toBe(0)
+    await expect(users.pick(seeded.id as string)).rejects.toThrow(UnknownRecordError)
+  })
+})