@tylix/orm 0.5.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tylix/orm",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
@@ -16,7 +16,7 @@
     "test": "node --test src/**/*.test.js"
   },
   "dependencies": {
-    "@tylix/shared": "^0.5.0",
+    "@tylix/shared": "^0.5.1",
     "mongodb": "^6.5.0",
     "mysql2": "^3.23.1",
     "pg": "^8.11.0"

package/src/adapters/DatabaseError.d.ts

@@ -0,0 +1,52 @@
+export type DatabaseDriver = 'mysql' | 'postgres' | 'sqlite' | 'mongodb';
+
+export type DatabaseErrorKind =
+    | 'connection_failed'
+    | 'auth_failed'
+    | 'unknown_database'
+    | 'missing_table'
+    | 'missing_column'
+    | 'duplicate_key'
+    | 'not_null'
+    | 'foreign_key'
+    | 'data_too_long'
+    | 'syntax'
+    | 'unsupported_query'
+    | 'driver_missing'
+    | 'unknown';
+
+export interface DatabaseErrorOptions {
+    driver?: DatabaseDriver | null;
+    kind?: DatabaseErrorKind;
+    title?: string | null;
+    hint?: string | null;
+    code?: string | number | null;
+    detail?: string | null;
+    table?: string | null;
+    column?: string | null;
+    sql?: string | null;
+    params?: unknown[];
+    cause?: unknown;
+}
+
+export declare class DatabaseError extends Error {
+    constructor(message: string, options?: DatabaseErrorOptions);
+    driver: DatabaseDriver | null;
+    kind: DatabaseErrorKind;
+    title: string | null;
+    hint: string | null;
+    code: string | number | null;
+    detail: string | null;
+    table: string | null;
+    column: string | null;
+    sql: string | null;
+    params: unknown[];
+    cause: unknown;
+    toJSON(): Record<string, unknown>;
+}
+
+export declare function normalizeDatabaseError(
+    driver: DatabaseDriver,
+    err: unknown,
+    context?: { sql?: string | null; params?: unknown[] },
+): DatabaseError;

package/src/adapters/DatabaseError.js

@@ -0,0 +1,336 @@
+const DRIVER_LABELS = {
+  mysql: 'MySQL',
+  postgres: 'PostgreSQL',
+  sqlite: 'SQLite',
+  mongodb: 'MongoDB',
+}
+
+/**
+ * Thrown by every database adapter instead of the raw driver error.
+ * Same shape for MySQL, PostgreSQL, SQLite and MongoDB, so the server
+ * and the debug page never need to know which driver is in use.
+ */
+export class DatabaseError extends Error {
+  constructor(
+    message,
+    {
+      driver = null,
+      kind = 'unknown',
+      title = null,
+      hint = null,
+      code = null,
+      detail = null,
+      table = null,
+      column = null,
+      sql = null,
+      params = [],
+      cause = null,
+    } = {},
+  ) {
+    super(message)
+    this.name = 'DatabaseError'
+    this.driver = driver
+    this.kind = kind
+    this.title = title
+    this.hint = hint
+    this.code = code
+    this.detail = detail
+    this.table = table
+    this.column = column
+    this.sql = sql
+    this.params = params
+    this.cause = cause
+  }
+
+  // Safe-to-serialize view used by the debug response. The stack is
+  // added by the server, only when debug mode is on.
+  toJSON() {
+    return {
+      name: this.name,
+      driver: this.driver,
+      kind: this.kind,
+      title: this.title,
+      message: this.message,
+      hint: this.hint,
+      code: this.code,
+      detail: this.detail,
+      table: this.table,
+      column: this.column,
+      sql: this.sql,
+      params: (this.params ?? []).map(safeParam),
+    }
+  }
+}
+
+function safeParam(value) {
+  if (typeof value === 'bigint') return value.toString()
+  if (value instanceof Date) return value.toISOString()
+  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(value)) {
+    return `<${value.length} bytes>`
+  }
+  if (typeof value === 'string' && value.length > 200) {
+    return `${value.slice(0, 200)}… (${value.length} chars)`
+  }
+  return value
+}
+
+// ---------------------------------------------------------------
+// What each kind means, in plain language, and how to fix it.
+// ---------------------------------------------------------------
+
+const KIND_INFO = {
+  connection_failed: ({ driver }) => ({
+    title: `Cannot connect to ${DRIVER_LABELS[driver] ?? 'the database'}`,
+    hint: 'Make sure the database server is running, and that the host, port and file/URL in your .env are correct.',
+  }),
+  auth_failed: () => ({
+    title: 'Database login was rejected',
+    hint: 'The username or password is wrong. Check DATABASE_USER and DATABASE_PASSWORD in your .env.',
+  }),
+  unknown_database: () => ({
+    title: 'The database does not exist',
+    hint: 'Create the database first, or fix DATABASE_NAME in your .env.',
+  }),
+  missing_table: ({ table }) => ({
+    title: table ? `Table "${table}" does not exist` : 'Table does not exist',
+    hint: 'The migration that creates this table has not run yet. Run `npx tylix migrate`, or check the table name for typos.',
+  }),
+  missing_column: ({ column, table }) => ({
+    title: column
+      ? `Column "${column}" does not exist${table ? ` on "${table}"` : ''}`
+      : 'Column does not exist',
+    hint: 'Either a migration adding this column has not run (try `npx tylix migrate`), or the column name is misspelled in your model or query.',
+  }),
+  duplicate_key: ({ detail }) => ({
+    title: 'A unique rule was violated',
+    hint: `${detail ? `${detail}. ` : ''}A row with this value already exists. Check the existing data, or validate for duplicates before inserting.`,
+  }),
+  not_null: ({ column }) => ({
+    title: column ? `"${column}" cannot be empty` : 'A required value is missing',
+    hint: 'This column is NOT NULL and no value was given. Make sure the form or payload sends it, or give the column a default in the migration.',
+  }),
+  foreign_key: () => ({
+    title: 'A relationship (foreign key) rule was violated',
+    hint: 'Either you referenced a row that does not exist, or you are deleting a row that other rows still point to.',
+  }),
+  data_too_long: ({ column }) => ({
+    title: column ? `Value is too long for "${column}"` : 'Value is too long for its column',
+    hint: 'Shorten the value, or change the column to a larger type (for example `text` instead of `string`).',
+  }),
+  syntax: () => ({
+    title: 'The SQL has a syntax error',
+    hint: 'Look at the SQL below. The database stopped at the spot it quotes in the message.',
+  }),
+  unsupported_query: () => ({
+    title: 'This adapter cannot run that query',
+    hint: 'MongoAdapter only understands a limited set of simple query shapes. Use the model query builder, or extend parseQuery().',
+  }),
+  driver_missing: () => ({
+    title: 'SQLite support is not available',
+    hint: 'SQLite uses the built-in node:sqlite module, which needs Node.js 22.5 or newer. Upgrade Node, or pick another database.',
+  }),
+  unknown: ({ driver }) => ({
+    title: `${DRIVER_LABELS[driver] ?? 'Database'} error`,
+    hint: null,
+  }),
+}
+
+// ---------------------------------------------------------------
+// Per-driver classifiers. Each returns { kind, table, column, detail }.
+// ---------------------------------------------------------------
+
+const lastSegment = (name) => (name ? name.split('.').pop() : null)
+
+function splitQualified(name) {
+  if (!name) return { table: null, column: null }
+  const parts = name.split('.')
+  if (parts.length < 2) return { table: null, column: parts[0] }
+  return { table: parts[parts.length - 2], column: parts[parts.length - 1] }
+}
+
+const MYSQL_KINDS = {
+  ER_NO_SUCH_TABLE: 'missing_table',
+  ER_BAD_TABLE_ERROR: 'missing_table',
+  ER_BAD_FIELD_ERROR: 'missing_column',
+  ER_DUP_ENTRY: 'duplicate_key',
+  ER_BAD_NULL_ERROR: 'not_null',
+  ER_NO_DEFAULT_FOR_FIELD: 'not_null',
+  ER_NO_REFERENCED_ROW_2: 'foreign_key',
+  ER_ROW_IS_REFERENCED_2: 'foreign_key',
+  ER_PARSE_ERROR: 'syntax',
+  ER_ACCESS_DENIED_ERROR: 'auth_failed',
+  ER_BAD_DB_ERROR: 'unknown_database',
+  ER_DATA_TOO_LONG: 'data_too_long',
+  ECONNREFUSED: 'connection_failed',
+  ENOTFOUND: 'connection_failed',
+  ETIMEDOUT: 'connection_failed',
+  ECONNRESET: 'connection_failed',
+  PROTOCOL_CONNECTION_LOST: 'connection_failed',
+}
+
+function classifyMysql(err, message) {
+  const kind = MYSQL_KINDS[err.code] ?? 'unknown'
+  let table = null
+  let column = null
+  let detail = null
+  let m
+
+  if ((m = /Table '([^']+)' doesn't exist/.exec(message))) {
+    table = lastSegment(m[1])
+  }
+  m =
+    /Unknown column '([^']+)'/.exec(message) ||
+    /Column '([^']+)' cannot be null/.exec(message) ||
+    /Field '([^']+)' doesn't have a default value/.exec(message) ||
+    /Data too long for column '([^']+)'/.exec(message)
+  if (m) column = m[1]
+  if ((m = /Duplicate entry '(.*)' for key '(.*)'/.exec(message))) {
+    detail = `Value "${m[1]}" already exists for key ${m[2]}`
+  }
+  return { kind, table, column, detail }
+}
+
+const PG_KINDS = {
+  '42P01': 'missing_table',
+  '42703': 'missing_column',
+  '23505': 'duplicate_key',
+  '23502': 'not_null',
+  '23503': 'foreign_key',
+  '42601': 'syntax',
+  '22001': 'data_too_long',
+  '28P01': 'auth_failed',
+  '28000': 'auth_failed',
+  '3D000': 'unknown_database',
+  ECONNREFUSED: 'connection_failed',
+  ENOTFOUND: 'connection_failed',
+  ETIMEDOUT: 'connection_failed',
+  ECONNRESET: 'connection_failed',
+}
+
+function classifyPostgres(err, message) {
+  const kind = PG_KINDS[err.code] ?? 'unknown'
+  let table = err.table ?? null
+  let column = err.column ?? null
+  let m
+
+  if (!table && (m = /relation "([^"]+)" does not exist/.exec(message))) {
+    table = lastSegment(m[1])
+  }
+  if (!table && (m = /of relation "([^"]+)"/.exec(message))) table = m[1]
+  if (!column && (m = /column "([^"]+)"/.exec(message))) column = m[1]
+
+  return { kind, table, column, detail: err.detail ?? null }
+}
+
+function classifySqlite(err, message) {
+  let m
+
+  if (/node:sqlite/.test(message)) {
+    return { kind: 'driver_missing', table: null, column: null, detail: null }
+  }
+  if ((m = /no such table: (\S+)/.exec(message))) {
+    return { kind: 'missing_table', table: lastSegment(m[1]), column: null, detail: null }
+  }
+  if ((m = /table (\S+) has no column named (\S+)/.exec(message))) {
+    return { kind: 'missing_column', table: m[1], column: m[2], detail: null }
+  }
+  if ((m = /no such column: (\S+)/.exec(message))) {
+    return { kind: 'missing_column', table: null, column: m[1], detail: null }
+  }
+  if ((m = /UNIQUE constraint failed: (.+)/.exec(message))) {
+    const { table, column } = splitQualified(m[1].split(',')[0].trim())
+    return { kind: 'duplicate_key', table, column, detail: `Unique rule on ${m[1]}` }
+  }
+  if ((m = /NOT NULL constraint failed: (\S+)/.exec(message))) {
+    const { table, column } = splitQualified(m[1])
+    return { kind: 'not_null', table, column, detail: null }
+  }
+  if (/FOREIGN KEY constraint failed/.test(message)) {
+    return { kind: 'foreign_key', table: null, column: null, detail: null }
+  }
+  if (/syntax error/i.test(message)) {
+    return { kind: 'syntax', table: null, column: null, detail: null }
+  }
+  if (/unable to open database file/i.test(message)) {
+    return { kind: 'connection_failed', table: null, column: null, detail: null }
+  }
+  return { kind: 'unknown', table: null, column: null, detail: null }
+}
+
+function classifyMongo(err, message) {
+  const none = { table: null, column: null, detail: null }
+  let m
+
+  if (err.code === 11000) {
+    const table = (m = /collection: (\S+)/.exec(message)) ? lastSegment(m[1]) : null
+    const detail = err.keyValue
+      ? `Value ${JSON.stringify(err.keyValue)} already exists`
+      : null
+    return { kind: 'duplicate_key', table, column: null, detail }
+  }
+  if (
+    /^Mongo(ServerSelection|Network|NetworkTimeout|Parse)Error$/.test(err.name) ||
+    err.code === 'ECONNREFUSED' ||
+    err.code === 'ENOTFOUND'
+  ) {
+    return { kind: 'connection_failed', ...none }
+  }
+  if (err.code === 18 || err.codeName === 'AuthenticationFailed') {
+    return { kind: 'auth_failed', ...none }
+  }
+  if (
+    /does not recognize this query shape|cannot handle query type|Unsupported where operator/.test(
+      message,
+    )
+  ) {
+    return { kind: 'unsupported_query', ...none }
+  }
+  return { kind: 'unknown', ...none }
+}
+
+const CLASSIFIERS = {
+  mysql: classifyMysql,
+  postgres: classifyPostgres,
+  sqlite: classifySqlite,
+  mongodb: classifyMongo,
+}
+
+/**
+ * Turns any driver error into a DatabaseError. Adapters call this in
+ * their catch blocks. Already-normalized errors pass through untouched.
+ */
+export function normalizeDatabaseError(driver, err, { sql = null, params = [] } = {}) {
+  if (err instanceof DatabaseError) return err
+
+  // mysql2 can throw an AggregateError with an empty message when
+  // "localhost" resolves to several addresses and all refuse.
+  const message =
+    err?.sqlMessage || err?.message || err?.code || String(err) || 'Unknown database error'
+
+  const classify = CLASSIFIERS[driver]
+  const info = classify
+    ? classify(err ?? {}, message)
+    : { kind: 'unknown', table: null, column: null, detail: null }
+
+  const { title, hint } = (KIND_INFO[info.kind] ?? KIND_INFO.unknown)({
+    driver,
+    ...info,
+  })
+
+    const error = new DatabaseError(message, {
+    driver,
+    kind: info.kind,
+    title,
+    hint,
+    code: err?.code ?? err?.codeName ?? null,
+    detail: info.detail,
+    table: info.table,
+    column: info.column,
+    sql,
+    params,
+    cause: err,
+  })
+  // Start the stack at whoever called the adapter, not inside this factory.
+  Error.captureStackTrace?.(error, normalizeDatabaseError)
+  return error
+}

package/src/adapters/MongoAdapter.js

@@ -1,5 +1,6 @@
 import { MongoClient } from 'mongodb'
 import { DatabaseAdapter } from './DatabaseAdapter.js'
+import { normalizeDatabaseError } from './DatabaseError.js'
 
 export function parseQuery(sql) {
   const trimmed = sql.trim().replace(/\s+/g, ' ')
@@ -26,10 +27,6 @@ export function parseQuery(sql) {
     return { type: 'findOne', table: match[1], field: match[2] }
   }
 
-  if ((match = /^SELECT \* FROM (\w+) WHERE (\w+) = \?$/i.exec(trimmed))) {
-    return { type: 'findOne', table: match[1], field: match[2] }
-  }
-
   if ((match = /^SELECT \* FROM (\w+)$/i.exec(trimmed))) {
     return { type: 'findAll', table: match[1] }
   }
@@ -71,9 +68,22 @@ export class MongoAdapter extends DatabaseAdapter {
   }
 
   async connect() {
-    this.client = new MongoClient(this.url)
-    await this.client.connect()
-    this.db = this.client.db(this.dbName)
+    try {
+      // Fail after 5s instead of the driver's default 30s, so a stopped
+      // MongoDB server shows up quickly.
+      this.client = new MongoClient(this.url, { serverSelectionTimeoutMS: 5000 })
+      await this.client.connect()
+      this.db = this.client.db(this.dbName)
+    } catch (err) {
+      const error = normalizeDatabaseError('mongodb', err)
+      // Never print credentials: mongodb://user:pass@host -> mongodb://***@host
+      const safeUrl = String(this.url).replace(/\/\/[^@/]*@/, '//***@')
+      error.detail = `Tried ${safeUrl}, database "${this.dbName}"`
+      await this.client?.close().catch(() => {})
+      this.client = null
+      this.db = null
+      throw error
+    }
     return this
   }
 
@@ -95,6 +105,18 @@ export class MongoAdapter extends DatabaseAdapter {
     }
   }
 
+  // Wraps any Mongo operation so failures become DatabaseErrors.
+  // `sql` is whatever text best describes what was attempted: the
+  // SQL-like string for run/get/all, or an equivalent db.x.find(...)
+  // description for query/count/paginate.
+  async guard(ctx, fn) {
+    try {
+      return await fn()
+    } catch (err) {
+      throw normalizeDatabaseError('mongodb', err, ctx)
+    }
+  }
+
   async nextId(table) {
     const counters = this.db.collection('__tylix_counters')
     const result = await counters.findOneAndUpdate(
@@ -107,6 +129,10 @@ export class MongoAdapter extends DatabaseAdapter {
 
   async run(sql, params = []) {
     this.ensureConnected()
+    return this.guard({ sql, params }, () => this._run(sql, params))
+  }
+
+  async _run(sql, params) {
     const query = parseQuery(sql)
 
     if (query.type === 'createTable') {
@@ -179,100 +205,121 @@ export class MongoAdapter extends DatabaseAdapter {
 
   async get(sql, params = []) {
     this.ensureConnected()
-    const query = parseQuery(sql)
-
-    if (query.type === 'findOne') {
-      const doc = await this.db
-        .collection(query.table)
-        .findOne({ [query.field]: params[0] }, { projection: { _id: 0 } })
-      return doc ?? null
-    }
+    return this.guard({ sql, params }, async () => {
+      const query = parseQuery(sql)
+
+      if (query.type === 'findOne') {
+        const doc = await this.db
+          .collection(query.table)
+          .findOne({ [query.field]: params[0] }, { projection: { _id: 0 } })
+        return doc ?? null
+      }
 
-    throw new Error(`get() cannot handle query type "${query.type}"`)
+      throw new Error(`get() cannot handle query type "${query.type}"`)
+    })
   }
 
   async all(sql, params = []) {
     this.ensureConnected()
-    const query = parseQuery(sql)
-
-    if (query.type === 'findAll') {
-      return this.db
-        .collection(query.table)
-        .find({}, { projection: { _id: 0 } })
-        .toArray()
-    }
+    return this.guard({ sql, params }, async () => {
+      const query = parseQuery(sql)
+
+      if (query.type === 'findAll') {
+        return this.db
+          .collection(query.table)
+          .find({}, { projection: { _id: 0 } })
+          .toArray()
+      }
 
-    if (query.type === 'findOne') {
-      return this.db
-        .collection(query.table)
-        .find({ [query.field]: params[0] }, { projection: { _id: 0 } })
-        .toArray()
-    }
+      if (query.type === 'findOne') {
+        return this.db
+          .collection(query.table)
+          .find({ [query.field]: params[0] }, { projection: { _id: 0 } })
+          .toArray()
+      }
 
-    throw new Error(`all() cannot handle query type "${query.type}"`)
+      throw new Error(`all() cannot handle query type "${query.type}"`)
+    })
   }
 
   async count(table) {
     this.ensureConnected()
-    return this.db.collection(table).countDocuments()
+    return this.guard({ sql: `db.${table}.countDocuments()` }, () =>
+      this.db.collection(table).countDocuments(),
+    )
   }
 
   async paginate(table, limit, offset) {
     this.ensureConnected()
-    return this.db
-      .collection(table)
-      .find({}, { projection: { _id: 0 } })
-      .sort({ id: 1 })
-      .skip(offset)
-      .limit(limit)
-      .toArray()
+    return this.guard(
+      {
+        sql: `db.${table}.find({}).sort({"id":1}).skip(${offset}).limit(${limit})`,
+      },
+      () =>
+        this.db
+          .collection(table)
+          .find({}, { projection: { _id: 0 } })
+          .sort({ id: 1 })
+          .skip(offset)
+          .limit(limit)
+          .toArray(),
+    )
   }
 
   async listTables() {
     this.ensureConnected()
-    const collections = await this.db.listCollections().toArray()
-    return collections.map((c) => c.name)
+    return this.guard({ sql: 'db.listCollections()' }, async () => {
+      const collections = await this.db.listCollections().toArray()
+      return collections.map((c) => c.name)
+    })
   }
 
-  columnType() {
-    return null
-  }
-}
+  async query(table, { wheres = [], orders = [], limitValue, offsetValue } = {}) {
+    this.ensureConnected()
 
-MongoAdapter.prototype.query = async function (
-  table,
-  { wheres = [], orders = [], limitValue, offsetValue } = {},
-) {
-  this.ensureConnected()
-
-  const filter = {}
-  for (const w of wheres) {
-    if (w.operator === '=') filter[w.field] = w.value
-    else if (w.operator === '!=') filter[w.field] = { $ne: w.value }
-    else if (w.operator === '>') filter[w.field] = { $gt: w.value }
-    else if (w.operator === '<') filter[w.field] = { $lt: w.value }
-    else if (w.operator === '>=') filter[w.field] = { $gte: w.value }
-    else if (w.operator === '<=') filter[w.field] = { $lte: w.value }
-    else
-      throw new Error(
-        `Unsupported where operator "${w.operator}" for MongoAdapter`,
-      )
-  }
+    const filter = {}
+    const sort = {}
+    const description = () => {
+      let text = `db.${table}.find(${JSON.stringify(filter)})`
+      if (Object.keys(sort).length) text += `.sort(${JSON.stringify(sort)})`
+      if (offsetValue !== undefined) text += `.skip(${offsetValue})`
+      if (limitValue !== undefined) text += `.limit(${limitValue})`
+      return text
+    }
 
-  let cursor = this.db
-    .collection(table)
-    .find(filter, { projection: { _id: 0 } })
+    return this.guard({ get sql() { return description() } }, async () => {
+      for (const w of wheres) {
+        if (w.operator === '=') filter[w.field] = w.value
+        else if (w.operator === '!=') filter[w.field] = { $ne: w.value }
+        else if (w.operator === '>') filter[w.field] = { $gt: w.value }
+        else if (w.operator === '<') filter[w.field] = { $lt: w.value }
+        else if (w.operator === '>=') filter[w.field] = { $gte: w.value }
+        else if (w.operator === '<=') filter[w.field] = { $lte: w.value }
+        else
+          throw new Error(
+            `Unsupported where operator "${w.operator}" for MongoAdapter`,
+          )
+      }
 
-  if (orders.length > 0) {
-    const sort = {}
-    orders.forEach((o) => {
-      sort[o.field] = o.direction.toUpperCase() === 'DESC' ? -1 : 1
+      let cursor = this.db
+        .collection(table)
+        .find(filter, { projection: { _id: 0 } })
+
+      if (orders.length > 0) {
+        orders.forEach((o) => {
+          sort[o.field] = o.direction.toUpperCase() === 'DESC' ? -1 : 1
+        })
+        cursor = cursor.sort(sort)
+      }
+
+      if (offsetValue !== undefined) cursor = cursor.skip(offsetValue)
+      if (limitValue !== undefined) cursor = cursor.limit(limitValue)
+
+      return cursor.toArray()
     })
-    cursor = cursor.sort(sort)
   }
 
-  if (offsetValue !== undefined) cursor = cursor.skip(offsetValue)
-  if (limitValue !== undefined) cursor = cursor.limit(limitValue)
-
-  return cursor.toArray()
-}
+  columnType() {
+    return null
+  }
+}

package/src/adapters/MysqlAdapter.js

@@ -1,5 +1,6 @@
 import mysql from 'mysql2/promise'
 import { DatabaseAdapter } from './DatabaseAdapter.js'
+import { normalizeDatabaseError } from './DatabaseError.js'
 
 const COLUMN_TYPES = {
   increments: 'INT AUTO_INCREMENT PRIMARY KEY',
@@ -31,19 +32,28 @@ export class MysqlAdapter extends DatabaseAdapter {
     this.connection = null
   }
 
- async connect() {
-  this.connection = mysql.createPool({
-    ...this.config,
-    waitForConnections: true,
-    connectionLimit: 10,
-    queueLimit: 0,
-    enableKeepAlive: true,
-    keepAliveInitialDelay: 10000,
-  })
-  const conn = await this.connection.getConnection() // fail fast on bad credentials
-  conn.release()
-  return this
-}
+  async connect() {
+    this.connection = mysql.createPool({
+      ...this.config,
+      waitForConnections: true,
+      connectionLimit: 10,
+      queueLimit: 0,
+      enableKeepAlive: true,
+      keepAliveInitialDelay: 10000,
+    })
+    try {
+      const conn = await this.connection.getConnection() // fail fast on bad credentials
+      conn.release()
+    } catch (err) {
+      const error = normalizeDatabaseError('mysql', err)
+      const { host, port, user, database } = this.config
+      error.detail = `Tried ${host}:${port} as "${user}", database "${database}"`
+      await this.connection.end().catch(() => {})
+      this.connection = null
+      throw error
+    }
+    return this
+  }
 
   async close() {
     if (this.connection) {
@@ -62,51 +72,51 @@ export class MysqlAdapter extends DatabaseAdapter {
     }
   }
 
-  async run(sql, params = []) {
+  // The one place every statement runs through, so every MySQL failure
+  // is translated into a DatabaseError that carries the SQL.
+  async execute(sql, params = []) {
     this.ensureConnected()
     const converted = params.map(toMysqlDateTime)
-    const [result] = await this.connection.execute(sql, converted)
+    try {
+      const [result] = await this.connection.execute(sql, converted)
+      return result
+    } catch (err) {
+      throw normalizeDatabaseError('mysql', err, { sql, params: converted })
+    }
+  }
+
+  async run(sql, params = []) {
+    const result = await this.execute(sql, params)
     return { ...result, lastInsertRowid: result.insertId }
   }
 
   async get(sql, params = []) {
-    this.ensureConnected()
-    const converted = params.map(toMysqlDateTime)
-    const [rows] = await this.connection.execute(sql, converted)
+    const rows = await this.execute(sql, params)
     return rows[0] ?? null
   }
 
   async all(sql, params = []) {
-    this.ensureConnected()
-    const converted = params.map(toMysqlDateTime)
-    const [rows] = await this.connection.execute(sql, converted)
-    return rows
+    return this.execute(sql, params)
   }
 
   async count(table) {
-    this.ensureConnected()
-    const [rows] = await this.connection.execute(
-      `SELECT COUNT(*) as count FROM ${table}`,
-    )
+    const rows = await this.execute(`SELECT COUNT(*) as count FROM ${table}`)
     return Number(rows[0].count)
   }
 
   async paginate(table, limit, offset) {
-    this.ensureConnected()
     // mysql2 does not support ? placeholders for LIMIT/OFFSET reliably
     // across versions, so these are inlined after being forced to
     // integers here (never from raw user input) to avoid injection.
     const safeLimit = Number.isInteger(limit) ? limit : parseInt(limit, 10)
     const safeOffset = Number.isInteger(offset) ? offset : parseInt(offset, 10)
-    const [rows] = await this.connection.execute(
+    return this.execute(
       `SELECT * FROM ${table} ORDER BY id ASC LIMIT ${safeLimit} OFFSET ${safeOffset}`,
     )
-    return rows
   }
 
   async listTables() {
-    this.ensureConnected()
-    const [rows] = await this.connection.execute('SHOW TABLES')
+    const rows = await this.execute('SHOW TABLES')
     return rows.map((r) => Object.values(r)[0])
   }
 

package/src/adapters/PostgresAdapter.js

@@ -1,5 +1,6 @@
 import pg from 'pg'
 import { DatabaseAdapter } from './DatabaseAdapter.js'
+import { normalizeDatabaseError } from './DatabaseError.js'
 
 const COLUMN_TYPES = {
   increments: 'SERIAL PRIMARY KEY',
@@ -38,8 +39,24 @@ export class PostgresAdapter extends DatabaseAdapter {
 
   async connect() {
     this.pool = new pg.Pool(this.config)
+    try {
+      // pg connects lazily, so test it now. A wrong password or a
+      // stopped server should fail at startup, not on the first request.
+      const client = await this.pool.connect()
+      client.release()
+    } catch (err) {
+      const error = normalizeDatabaseError('postgres', err)
+      const { host, port, user, database } = this.config
+      error.detail = this.config.connectionString
+        ? 'Using DATABASE_URL connection string'
+        : `Tried ${host}:${port} as "${user}", database "${database}"`
+      await this.pool.end().catch(() => {})
+      this.pool = null
+      throw error
+    }
     return this
   }
+
   async close() {
     if (this.pool) {
       await this.pool.end()
@@ -57,39 +74,43 @@ export class PostgresAdapter extends DatabaseAdapter {
     }
   }
 
-  async run(sql, params = []) {
+  // The one place every statement runs through. `sql` here is the final
+  // SQL (with $1, $2 placeholders), exactly what PostgreSQL received.
+  async execute(sql, params = []) {
     this.ensureConnected()
-    const finalSql = toPositionalPlaceholders(ensureReturningId(sql))
-    const result = await this.pool.query(finalSql, params)
+    try {
+      return await this.pool.query(sql, params)
+    } catch (err) {
+      throw normalizeDatabaseError('postgres', err, { sql, params })
+    }
+  }
+
+  async run(sql, params = []) {
+    const result = await this.execute(
+      toPositionalPlaceholders(ensureReturningId(sql)),
+      params,
+    )
     const lastInsertRowid = result.rows[0]?.id
     return { ...result, lastInsertRowid }
   }
 
   async get(sql, params = []) {
-    this.ensureConnected()
-    const finalSql = toPositionalPlaceholders(sql)
-    const result = await this.pool.query(finalSql, params)
+    const result = await this.execute(toPositionalPlaceholders(sql), params)
     return result.rows[0] ?? null
   }
 
   async all(sql, params = []) {
-    this.ensureConnected()
-    const finalSql = toPositionalPlaceholders(sql)
-    const result = await this.pool.query(finalSql, params)
+    const result = await this.execute(toPositionalPlaceholders(sql), params)
     return result.rows
   }
 
   async count(table) {
-    this.ensureConnected()
-    const result = await this.pool.query(
-      `SELECT COUNT(*) as count FROM ${table}`,
-    )
+    const result = await this.execute(`SELECT COUNT(*) as count FROM ${table}`)
     return Number(result.rows[0].count)
   }
 
   async paginate(table, limit, offset) {
-    this.ensureConnected()
-    const result = await this.pool.query(
+    const result = await this.execute(
       `SELECT * FROM ${table} ORDER BY id ASC LIMIT $1 OFFSET $2`,
       [limit, offset],
     )
@@ -97,8 +118,7 @@ export class PostgresAdapter extends DatabaseAdapter {
   }
 
   async listTables() {
-    this.ensureConnected()
-    const result = await this.pool.query(
+    const result = await this.execute(
       "SELECT tablename FROM pg_tables WHERE schemaname = 'public'",
     )
     return result.rows.map((r) => r.tablename)
@@ -113,4 +133,4 @@ export class PostgresAdapter extends DatabaseAdapter {
     }
     return sql
   }
-}
+}

package/src/adapters/SqliteAdapter.js

@@ -1,4 +1,5 @@
 import { DatabaseAdapter } from './DatabaseAdapter.js'
+import { normalizeDatabaseError } from './DatabaseError.js'
 
 const COLUMN_TYPES = {
   increments: 'INTEGER PRIMARY KEY AUTOINCREMENT',
@@ -20,8 +21,14 @@ export class SqliteAdapter extends DatabaseAdapter {
   }
 
   async connect() {
-    const { DatabaseSync } = await import('node:sqlite')
-    this.db = new DatabaseSync(this.filename)
+    try {
+      const { DatabaseSync } = await import('node:sqlite')
+      this.db = new DatabaseSync(this.filename)
+    } catch (err) {
+      const error = normalizeDatabaseError('sqlite', err)
+      error.detail = `Database file: ${this.filename}`
+      throw error
+    }
     return this
   }
 
@@ -42,45 +49,48 @@ export class SqliteAdapter extends DatabaseAdapter {
     }
   }
 
-  async run(sql, params = []) {
+  // The one place every statement runs through. SQLite reports most
+  // mistakes (missing table or column, bad syntax) when the statement
+  // is prepared, so prepare() is inside the try as well.
+  execute(method, sql, params = []) {
     this.ensureConnected()
-    const stmt = this.db.prepare(sql)
-    return stmt.run(...params)
+    try {
+      return this.db.prepare(sql)[method](...params)
+    } catch (err) {
+      throw normalizeDatabaseError('sqlite', err, { sql, params })
+    }
+  }
+
+  async run(sql, params = []) {
+    return this.execute('run', sql, params)
   }
 
   async get(sql, params = []) {
-    this.ensureConnected()
-    const stmt = this.db.prepare(sql)
-    return stmt.get(...params) ?? null
+    return this.execute('get', sql, params) ?? null
   }
 
   async all(sql, params = []) {
-    this.ensureConnected()
-    const stmt = this.db.prepare(sql)
-    return stmt.all(...params)
+    return this.execute('all', sql, params)
   }
 
   async count(table) {
-    this.ensureConnected()
-    const row = this.db.prepare(`SELECT COUNT(*) as count FROM ${table}`).get()
+    const row = this.execute('get', `SELECT COUNT(*) as count FROM ${table}`)
     return row.count
   }
 
   async paginate(table, limit, offset) {
-    this.ensureConnected()
-    const stmt = this.db.prepare(
+    return this.execute(
+      'all',
       `SELECT * FROM ${table} ORDER BY id ASC LIMIT ? OFFSET ?`,
+      [limit, offset],
     )
-    return stmt.all(limit, offset)
   }
 
   async listTables() {
-    this.ensureConnected()
-    const rows = this.db
-      .prepare(
-        "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'",
-      )
-      .all()
+    const rows = this.execute(
+      'all',
+      "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'",
+    )
     return rows.map((r) => r.name)
   }
 
@@ -93,4 +103,4 @@ export class SqliteAdapter extends DatabaseAdapter {
     }
     return sql
   }
-}
+}