@otwdesign/db-core 1.0.2 → 1.2.0

package/src/drivers/postgres.ts

@@ -3,6 +3,7 @@ import { connect } from 'node:net'
 import type { FieldDef, Pool, PoolClient, PoolConfig } from 'pg'
 import { ConnectionError, DbAdminError, QueryError } from '../errors.ts'
 import {
+  DATABASES_SQL,
   detail,
   dialect,
   INFO_SQL,
@@ -21,6 +22,7 @@ import type {
   ApplyResult,
   Capabilities,
   Change,
+  DatabaseList,
   Driver,
   QueryOptions,
   QueryResult,
@@ -50,47 +52,117 @@ interface Modules {
   Cursor: typeof CursorClass
 }
 
-let modules: Promise<Modules> | undefined
+/**
+ * Imports pg and pg-cursor, as `() => Promise.all([import('pg'), import('pg-cursor')])` does.
+ * Each may be its import's namespace or the package's own export.
+ */
+export type PostgresModules = () => Promise<readonly [pg: unknown, pgCursor: unknown]>
 
-/** pg and pg-cursor, imported on the first PostgreSQL connection, so other hosts never load them. */
-function loadModules(): Promise<Modules> {
-  // Imported where the host runs, not bundled: a site installs only the drivers it uses, and a
-  // bundler (Next.js) mustn't fail on one it doesn't have.
-  modules ??= Promise.all([
+/** How a PostgreSQL driver gets the packages it runs on. */
+export interface PostgresOptions {
+  /**
+   * Where pg and pg-cursor come from. By default they're imported where the app runs, from the
+   * app's own dependencies. A package that brings them as its own dependencies and is bundled into
+   * the app, such as the OTW CMS plugin, passes its own imports: the app's bundler resolves those
+   * from that package, which pnpm requires, since it keeps a package's dependencies beside it.
+   */
+  modules?: PostgresModules
+}
+
+// Imported where the app runs, not bundled: an app installs only the drivers it uses, and a
+// bundler (Next.js) mustn't fail on one it doesn't have.
+const fromApp: PostgresModules = () =>
+  Promise.all([
     import(/* webpackIgnore: true */ /* turbopackIgnore: true */ 'pg'),
     import(/* webpackIgnore: true */ /* turbopackIgnore: true */ 'pg-cursor'),
-  ]).then(
-    ([pg, cursor]) => ({ Pool: pg.Pool, Cursor: cursor.default }),
-    (error: unknown) => {
-      modules = undefined
-      throw new DbAdminError(
-        `PostgreSQL connections need the pg and pg-cursor packages: npm install pg pg-cursor (${(error as Error).message})`,
-        500,
-        'driver-missing',
-      )
-    },
-  )
-  return modules
+  ])
+
+let appModules: Promise<Modules> | undefined
+
+/** pg and pg-cursor, imported on the first PostgreSQL connection, so other hosts never load them. */
+function loadModules(given: PostgresModules | undefined): Promise<Modules> {
+  if (given) return load(given, 'Could not load pg and pg-cursor')
+  appModules ??= load(
+    fromApp,
+    'PostgreSQL connections need the pg and pg-cursor packages, installed in the app: npm install pg pg-cursor',
+  ).catch((error: unknown) => {
+    appModules = undefined
+    throw error
+  })
+  return appModules
+}
+
+async function load(modules: PostgresModules, failure: string): Promise<Modules> {
+  let pg: unknown, cursor: unknown
+  try {
+    ;[pg, cursor] = await modules()
+  } catch (error) {
+    throw new DbAdminError(`${failure}: ${(error as Error).message}`, 500, 'driver-missing')
+  }
+  // A CommonJS package's import has its export as the default, and pg's ESM entry names Pool too.
+  const exports = pg as { Pool?: typeof Pool; default?: { Pool?: typeof Pool } }
+  const PoolClass = exports.Pool ?? exports.default?.Pool
+  const Cursor = (cursor as { default?: unknown } | undefined)?.default ?? cursor
+  if (typeof PoolClass !== 'function' || typeof Cursor !== 'function') {
+    throw new DbAdminError(`${failure}: they aren't pg's and pg-cursor's`, 500, 'driver-missing')
+  }
+  return { Pool: PoolClass, Cursor: Cursor as typeof CursorClass }
+}
+
+/** A placeholder host for a URL with none, as pg's own parser uses: `user@/db?host=/socket`. */
+const NO_HOST = '___otw_db_no_host___'
+
+/**
+ * `url` at another of its server's databases: its path swapped for `database`, its login, host and
+ * settings kept. pg reads the path back with decodeURI, which leaves `?` and `#` escaped, so a
+ * name with either can't be carried.
+ */
+export function postgresUrlAt(url: string, database: string): string {
+  if (/[?#]/.test(database)) {
+    throw new DbAdminError(
+      `The database "${database}" can't be opened: a connection URL can't name a database with ? or #.`,
+      400,
+      'bad-database',
+    )
+  }
+  const hostless = url.includes('@/')
+  let parsed: URL
+  try {
+    parsed = new URL(hostless ? url.replace('@/', `@${NO_HOST}/`) : url)
+  } catch {
+    // Not the URL itself, which may hold a password.
+    throw new DbAdminError(
+      "The connection's URL can't be moved to another database.",
+      500,
+      'bad-url',
+    )
+  }
+  parsed.pathname = `/${encodeURI(database)}`
+  return hostless ? parsed.href.replace(`@${NO_HOST}/`, '@/') : parsed.href
 }
 
 /**
  * A PostgreSQL driver for `url`. It connects on first use, with a pool of up to three
  * connections, each closed after 10 s unused; an admin tool needs few.
  */
-export function postgresDriver(url: string): Driver {
-  return new PostgresDriver(url)
+export function postgresDriver(url: string, options: PostgresOptions = {}): Driver {
+  return new PostgresDriver(url, options.modules)
 }
 
 class PostgresDriver implements Driver {
   readonly kind = 'postgres'
   readonly capabilities: Capabilities = { schemas: true, transactionalDdl: true, cancel: true }
   readonly sql = { identifier: quote, literal }
+  readonly #url: string
   readonly #config: PoolConfig
+  readonly #modules: PostgresModules | undefined
   #pool: Promise<{ pool: Pool; modules: Modules }> | undefined
   /** Type names by OID, filled as results bring new ones. */
   readonly #typeNames = new Map<number, string>()
 
-  constructor(url: string) {
+  constructor(url: string, modules: PostgresModules | undefined) {
+    this.#url = url
+    this.#modules = modules
     this.#config = {
       connectionString: url,
       max: 3,
@@ -101,12 +173,19 @@ class PostgresDriver implements Driver {
   }
 
   #open(): Promise<{ pool: Pool; modules: Modules }> {
-    this.#pool ??= loadModules().then((modules) => {
-      const pool = new modules.Pool(this.#config)
-      // An idle connection the server drops would otherwise take the whole process with it.
-      pool.on('error', (error) => console.error('otw-db: a PostgreSQL connection failed', error))
-      return { pool, modules }
-    })
+    this.#pool ??= loadModules(this.#modules).then(
+      (modules) => {
+        const pool = new modules.Pool(this.#config)
+        // An idle connection the server drops would otherwise take the whole process with it.
+        pool.on('error', (error) => console.error('otw-db: a PostgreSQL connection failed', error))
+        return { pool, modules }
+      },
+      (error: unknown) => {
+        // Nothing opened: the next call tries again.
+        this.#pool = undefined
+        throw error
+      },
+    )
     return this.#pool
   }
 
@@ -179,6 +258,18 @@ class PostgresDriver implements Driver {
     return this.#run(sql, undefined, options)
   }
 
+  async databases(): Promise<DatabaseList> {
+    const rows = await this.#catalog<{ name: string; current: string }>(DATABASES_SQL)
+    return {
+      current: rows.find((row) => row.current === 't')?.name ?? '',
+      databases: rows.map((row) => row.name),
+    }
+  }
+
+  withDatabase(name: string): Driver {
+    return new PostgresDriver(postgresUrlAt(this.#url, name), this.#modules)
+  }
+
   async apply(
     { schema, table }: { schema: string; table: string },
     changes: readonly Change[],
@@ -332,7 +423,9 @@ class PostgresDriver implements Driver {
   async close(): Promise<void> {
     const opened = this.#pool
     this.#pool = undefined
-    if (opened) await (await opened).pool.end()
+    // One that failed to open has nothing to close.
+    const pool = await opened?.catch(() => undefined)
+    await pool?.pool.end()
   }
 }
 

package/src/handler.ts

@@ -82,6 +82,10 @@ const QUERY_ID = /^[A-Za-z0-9_-]{1,64}$/
 const MAX_FILTERS = 20
 const MAX_CHANGES = 1_000
 const MAX_LIST = 1_000
+/** A connection's other databases kept open at once; the one used longest ago closes first. */
+const MAX_DATABASES = 8
+/** PostgreSQL's NAMEDATALEN, less its terminator: the longest database name, in bytes. */
+const MAX_DATABASE_NAME = 63
 const OPERATORS: ReadonlySet<string> = new Set<FilterOperator>([
   '=',
   '<>',
@@ -127,6 +131,8 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
   const limits = { ...DEFAULT_LIMITS, ...options.limits }
   const audit = options.audit === false ? undefined : (options.audit ?? logAudit)
   const drivers = new Map<string, Driver>()
+  /** Each connection's other databases' drivers, the one used last at the end. */
+  const others = new Map<string, Map<string, Driver>>()
   const running = new Map<string, { viewer: string; controller: AbortController }>()
   const open = options.driver ?? openDriver
   const loadUi = options.ui === false ? undefined : (options.ui ?? defaultUi)
@@ -141,14 +147,55 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
     return found
   }
 
-  /** The connection by name, with this viewer's access to it; unknown and hidden look the same. */
-  function reach(viewer: Viewer, name: unknown): { connection: ConnectionConfig; access: Access } {
+  /**
+   * The driver for one of the connection's other databases. The 8 used last stay open; opening a
+   * ninth closes the one used longest ago, so a viewer can't keep pools open without end.
+   */
+  function driverAt(connection: ConnectionConfig, database: string): Driver {
+    let open = others.get(connection.name)
+    if (!open) others.set(connection.name, (open = new Map()))
+    let found = open.get(database)
+    if (found) open.delete(database)
+    else found = driver(connection).withDatabase!(database)
+    open.set(database, found)
+    if (open.size > MAX_DATABASES) {
+      const [oldest, evicted] = open.entries().next().value!
+      open.delete(oldest)
+      evicted.close().catch((error: unknown) => {
+        console.error(`otw-db: could not close database "${oldest}" of "${connection.name}"`, error)
+      })
+    }
+    return found
+  }
+
+  /**
+   * The connection by name, with this viewer's access to it and the driver for `database`: one of
+   * the server's other databases, or the connection's own when none is named. Unknown and hidden
+   * connections look the same.
+   */
+  function reach(
+    viewer: Viewer,
+    name: unknown,
+    database?: unknown,
+  ): { connection: ConnectionConfig; access: Access; db: Driver; database?: string } {
     const connection = typeof name === 'string' ? connections.get(name) : undefined
     const access = connection ? accessOf(viewer, connection) : null
     if (!connection || !access) {
       throw new DbAdminError(`There's no connection "${String(name)}".`, 404, 'unknown-connection')
     }
-    return { connection, access }
+    if (database === undefined || database === null || database === '') {
+      return { connection, access, db: driver(connection) }
+    }
+    const named = databaseName(database)
+    if (!opensOthers(connection)) throw oneDatabase(connection)
+    return { connection, access, db: driverAt(connection, named), database: named }
+  }
+
+  /** Whether the connection may open its server's other databases, and its driver can. */
+  function opensOthers(connection: ConnectionConfig): boolean {
+    if (connection.databases === 'one') return false
+    const opened = driver(connection)
+    return typeof opened.databases === 'function' && typeof opened.withDatabase === 'function'
   }
 
   async function record(event: Omit<AuditEvent, 'at'>): Promise<void> {
@@ -176,7 +223,10 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
           // A kind without a driver yet is listed, but can't be opened.
           let capabilities: Driver['capabilities'] | null = null
           try {
-            capabilities = driver(connection).capabilities
+            capabilities = {
+              ...driver(connection).capabilities,
+              databases: opensOthers(connection),
+            }
           } catch (error) {
             if (!(error instanceof DbAdminError)) throw error
           }
@@ -188,12 +238,25 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
         return { connections: visible }
       },
     },
+    {
+      method: 'GET',
+      path: '/api/databases',
+      async run(request, viewer) {
+        const { connection, db } = reach(
+          viewer,
+          new URL(request.url).searchParams.get('connection'),
+        )
+        if (!opensOthers(connection)) throw oneDatabase(connection)
+        return await db.databases!()
+      },
+    },
     {
       method: 'GET',
       path: '/api/tables',
       async run(request, viewer) {
-        const { connection } = reach(viewer, new URL(request.url).searchParams.get('connection'))
-        return { tables: await driver(connection).tables() }
+        const params = new URL(request.url).searchParams
+        const { db } = reach(viewer, params.get('connection'), params.get('database'))
+        return { tables: await db.tables() }
       },
     },
     {
@@ -201,8 +264,8 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
       path: '/api/table',
       async run(request, viewer) {
         const params = new URL(request.url).searchParams
-        const { connection } = reach(viewer, params.get('connection'))
-        const table = await driver(connection).table(
+        const { db } = reach(viewer, params.get('connection'), params.get('database'))
+        const table = await db.table(
           text(params.get('schema'), 'schema'),
           text(params.get('name'), 'name'),
         )
@@ -214,8 +277,9 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
       method: 'GET',
       path: '/api/info',
       async run(request, viewer) {
-        const { connection } = reach(viewer, new URL(request.url).searchParams.get('connection'))
-        return { info: await driver(connection).info() }
+        const params = new URL(request.url).searchParams
+        const { db } = reach(viewer, params.get('connection'), params.get('database'))
+        return { info: await db.info() }
       },
     },
     {
@@ -223,7 +287,7 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
       path: '/api/count',
       async run(request, viewer) {
         const body = await json(request)
-        const { connection } = reach(viewer, body.connection)
+        const { connection, db, database } = reach(viewer, body.connection, body.database)
         const target = {
           schema: text(body.schema, 'schema'),
           table: text(body.table, 'table'),
@@ -232,13 +296,14 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
         const started = performance.now()
         const statement = `count ${target.schema}.${target.table}`
         try {
-          const rows = await driver(connection).count(target, {
+          const rows = await db.count(target, {
             timeoutMs: limits.timeoutMs,
             signal: request.signal,
           })
           await record({
             viewer: viewer.id,
             connection: connection.name,
+            ...(database ? { database } : {}),
             action: 'count',
             statement,
             durationMs: Math.round(performance.now() - started),
@@ -249,6 +314,7 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
           await record({
             viewer: viewer.id,
             connection: connection.name,
+            ...(database ? { database } : {}),
             action: 'count',
             statement,
             durationMs: Math.round(performance.now() - started),
@@ -263,18 +329,19 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
       path: '/api/rows',
       async run(request, viewer) {
         const body = await json(request)
-        const { connection } = reach(viewer, body.connection)
+        const { connection, db, database } = reach(viewer, body.connection, body.database)
         const page = rowsRequest(body)
         const started = performance.now()
         const statement = `${page.schema}.${page.table}`
         try {
-          const result = await driver(connection).rows(page, {
+          const result = await db.rows(page, {
             timeoutMs: limits.timeoutMs,
             signal: request.signal,
           })
           await record({
             viewer: viewer.id,
             connection: connection.name,
+            ...(database ? { database } : {}),
             action: 'rows',
             statement,
             durationMs: result.durationMs,
@@ -285,6 +352,7 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
           await record({
             viewer: viewer.id,
             connection: connection.name,
+            ...(database ? { database } : {}),
             action: 'rows',
             statement,
             durationMs: Math.round(performance.now() - started),
@@ -299,7 +367,7 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
       path: '/api/query',
       async run(request, viewer) {
         const body = await json(request)
-        const { connection, access } = reach(viewer, body.connection)
+        const { connection, access, db, database } = reach(viewer, body.connection, body.database)
         const sql = text(body.sql, 'sql')
         const maxRows =
           body.maxRows === undefined
@@ -318,7 +386,7 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
         }
         const started = performance.now()
         try {
-          const result = await driver(connection).query(sql, {
+          const result = await db.query(sql, {
             access,
             maxRows,
             timeoutMs: limits.timeoutMs,
@@ -327,6 +395,7 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
           await record({
             viewer: viewer.id,
             connection: connection.name,
+            ...(database ? { database } : {}),
             action: 'query',
             statement: sql,
             durationMs: result.durationMs,
@@ -337,6 +406,7 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
           await record({
             viewer: viewer.id,
             connection: connection.name,
+            ...(database ? { database } : {}),
             action: 'query',
             statement: sql,
             durationMs: Math.round(performance.now() - started),
@@ -354,7 +424,7 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
       path: '/api/apply',
       async run(request, viewer) {
         const body = await json(request)
-        const { connection, access } = reach(viewer, body.connection)
+        const { connection, access, db, database } = reach(viewer, body.connection, body.database)
         const target = { schema: text(body.schema, 'schema'), table: text(body.table, 'table') }
         const changes = changesOf(body.changes)
         const dryRun = body.dryRun === true
@@ -363,7 +433,7 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
         }
         const started = performance.now()
         try {
-          const result = await driver(connection).apply(target, changes, {
+          const result = await db.apply(target, changes, {
             timeoutMs: limits.timeoutMs,
             dryRun,
           })
@@ -371,6 +441,7 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
             await record({
               viewer: viewer.id,
               connection: connection.name,
+              ...(database ? { database } : {}),
               action: 'apply',
               statement: result.statements.join(';\n'),
               durationMs: Math.round(performance.now() - started),
@@ -383,6 +454,7 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
             await record({
               viewer: viewer.id,
               connection: connection.name,
+              ...(database ? { database } : {}),
               action: 'apply',
               statement: `${changes.length} changes to ${target.schema}.${target.table}`,
               durationMs: Math.round(performance.now() - started),
@@ -398,12 +470,11 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
       path: '/api/export',
       async run(request, viewer) {
         const body = await json(request)
-        const { connection } = reach(viewer, body.connection)
+        const { connection, db, database } = reach(viewer, body.connection, body.database)
         const format = formatOf(body.format)
         const page = rowsRequest({ ...body, limit: undefined, offset: undefined })
-        const opened = driver(connection)
         const started = performance.now()
-        const batches = opened.export(page, { timeoutMs: limits.timeoutMs })
+        const batches = db.export(page, { timeoutMs: limits.timeoutMs })
         // Read the first batch before answering, so a bad table or filter is a proper error.
         const first = await batches.next()
         let replayed = false
@@ -419,11 +490,12 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
           format,
           replay,
           page,
-          opened.sql,
+          db.sql,
           (rows, error) =>
             void record({
               viewer: viewer.id,
               connection: connection.name,
+              ...(database ? { database } : {}),
               action: 'export',
               statement: `${page.schema}.${page.table} as ${format}`,
               durationMs: Math.round(performance.now() - started),
@@ -541,8 +613,9 @@ export function createDbAdmin(options: DbAdminOptions): DbAdmin {
       return reply(404, { error: { code: 'not-found', message: 'Not found.' } })
     },
     async close() {
-      const open = [...drivers.values()]
+      const open = [...drivers.values(), ...[...others.values()].flatMap((o) => [...o.values()])]
       drivers.clear()
+      others.clear()
       await Promise.all(open.map((d) => d.close()))
     },
   }
@@ -576,6 +649,26 @@ async function defaultUi(): Promise<UiAssets> {
   return assets
 }
 
+function oneDatabase(connection: ConnectionConfig): DbAdminError {
+  return new DbAdminError(
+    `Connection "${connection.name}" opens its own database only.`,
+    400,
+    'one-database',
+  )
+}
+
+/** A database's name as PostgreSQL takes it: up to 63 bytes, with no NUL. */
+function databaseName(value: unknown): string {
+  if (
+    typeof value !== 'string' ||
+    value.includes('\0') ||
+    new TextEncoder().encode(value).length > MAX_DATABASE_NAME
+  ) {
+    throw bad('"database" is a database’s name.')
+  }
+  return value
+}
+
 function accessOf(viewer: Viewer, connection: ConnectionConfig): Access | null {
   const granted = viewer.access ? viewer.access(connection) : connection.access
   if (!granted) return null

package/src/index.ts

@@ -1,9 +1,9 @@
 export { connectionsFromEnv, driverKind } from './connections.ts'
-export { openDriver } from './drivers/index.ts'
+export { openDriver, type DriverOptions } from './drivers/index.ts'
 export { backtick, mysqlDriver, mysqlLiteral } from './drivers/mysql.ts'
 export { sqliteDriver, sqliteLiteral, sqlitePath } from './drivers/sqlite.ts'
 export { pgliteDriver, type PGliteLike, type PGliteQueryable } from './drivers/pglite.ts'
-export { postgresDriver } from './drivers/postgres.ts'
+export { postgresDriver, type PostgresModules, type PostgresOptions } from './drivers/postgres.ts'
 export { literal as literalPostgres, quote as quotePostgres } from './drivers/postgres-catalog.ts'
 export { ConnectionError, DbAdminError, QueryError } from './errors.ts'
 export { EXPORT_TYPES, exportStream, type ExportBatch } from './export.ts'

package/src/types.ts

@@ -20,6 +20,12 @@ export interface ConnectionConfig {
   tag?: ConnectionTag
   /** Shown wherever people run SQL on it, such as what a heavy statement does to the host. */
   warning?: string
+  /**
+   * Which of its server's databases it opens, where a connection opens one database at a time
+   * (PostgreSQL): `all`, the default, every one its login may connect to, the URL's first; `one`,
+   * the URL's only, for a login with more privileges than the tool should show.
+   */
+  databases?: 'all' | 'one'
 }
 
 /** A connection's environment, as a color: production red, staging orange, and so on. */
@@ -36,6 +42,11 @@ export interface Capabilities {
    * runs on the host's own thread.
    */
   cancel: boolean
+  /**
+   * The server's other databases open from the connection, by name. The API sets it: a driver
+   * offers them with `databases()` and `withDatabase()`, and a connection may be pinned to its own.
+   */
+  databases?: boolean
 }
 
 /** What a schema-tree entry is: SQLite and MySQL have tables and views, PostgreSQL the rest too. */
@@ -195,6 +206,14 @@ export interface ServerInfo {
   user: string
 }
 
+/** The databases a connection's login may open on its server, for the database picker. */
+export interface DatabaseList {
+  /** The one the driver opened. */
+  current: string
+  /** By name, the current one among them. */
+  databases: string[]
+}
+
 /** How many rows one statement may send back, and how long it may run. */
 export interface Limits {
   /** Rows sent back at most; the rest are cut, and the result says so. */
@@ -242,6 +261,16 @@ export interface Driver {
   readonly sql: SqlDialect
   /** One statement. */
   query(sql: string, options: QueryOptions): Promise<QueryResult>
+  /**
+   * The server's databases its login may open, where a connection opens one at a time
+   * (PostgreSQL). Absent where it has one (SQLite) or shows the rest as schemas (MySQL).
+   */
+  databases?(): Promise<DatabaseList>
+  /**
+   * A driver for another of the server's databases, with the same login and settings. It connects
+   * on first use; whoever asked for it closes it.
+   */
+  withDatabase?(name: string): Driver
   close(): Promise<void>
 }
 
@@ -261,6 +290,8 @@ export interface AuditEvent {
   at: string
   viewer: string
   connection: string
+  /** The database it ran on, when it wasn't the connection's own. */
+  database?: string
   action: 'query' | 'rows' | 'count' | 'apply' | 'export' | 'cancel'
   /** The SQL run, or for `rows`, the table read. */
   statement: string