@stacksjs/database 0.70.256 → 0.70.258

package/dist/auth-tables.js

@@ -45,7 +45,7 @@ export async function ensureUsersAuthColumns(sql, options = {}) {
   }
 }
 export async function migrateAuthTables(options = {}) {
-  const dbDriver = getDbDriver(), sql = sqlHelpers(dbDriver), { isPostgres, boolTrue, now, pkColumn, nullableTimestamp } = sql;
+  const dbDriver = getDbDriver(), sql = sqlHelpers(dbDriver), { isPostgres, boolTrue, now, pkColumn, nullableTimestamp, datetime } = sql;
   if (options.verbose)
     log.info(`Creating auth tables for ${dbDriver}...`);
   try {
@@ -61,7 +61,7 @@ export async function migrateAuthTables(options = {}) {
         personal_access_client BOOLEAN NOT NULL DEFAULT ${sql.boolFalse},
         password_client BOOLEAN NOT NULL DEFAULT ${sql.boolFalse},
         revoked BOOLEAN NOT NULL DEFAULT ${sql.boolFalse},
-        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+        created_at ${datetime} DEFAULT CURRENT_TIMESTAMP,
         updated_at ${nullableTimestamp}
       )
     `).execute();
@@ -77,7 +77,7 @@ export async function migrateAuthTables(options = {}) {
         scopes TEXT,
         revoked BOOLEAN NOT NULL DEFAULT ${sql.boolFalse},
         expires_at ${nullableTimestamp},
-        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+        created_at ${datetime} DEFAULT CURRENT_TIMESTAMP,
         updated_at ${nullableTimestamp}
       )
     `).execute();
@@ -91,7 +91,7 @@ export async function migrateAuthTables(options = {}) {
         token TEXT NOT NULL,
         revoked BOOLEAN NOT NULL DEFAULT ${sql.boolFalse},
         expires_at ${nullableTimestamp},
-        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        created_at ${datetime} DEFAULT CURRENT_TIMESTAMP
       )
     `).execute();
     await createTokenIndex("idx_oauth_refresh_tokens_token", "oauth_refresh_tokens", "token");
@@ -102,7 +102,7 @@ export async function migrateAuthTables(options = {}) {
         ${pkColumn},
         email VARCHAR(255) NOT NULL,
         token VARCHAR(255) NOT NULL,
-        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        created_at ${datetime} DEFAULT CURRENT_TIMESTAMP
       )
     `).execute();
     try {
@@ -124,7 +124,7 @@ export async function migrateAuthTables(options = {}) {
         backup_eligible BOOLEAN NOT NULL DEFAULT ${sql.boolFalse},
         backup_status BOOLEAN NOT NULL DEFAULT ${sql.boolFalse},
         transports TEXT,
-        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+        created_at ${datetime} DEFAULT CURRENT_TIMESTAMP,
         last_used_at ${nullableTimestamp}
       )
     `).execute();
@@ -141,8 +141,8 @@ export async function migrateAuthTables(options = {}) {
         user_id INTEGER NOT NULL,
         challenge TEXT NOT NULL,
         purpose VARCHAR(20) NOT NULL,
-        expires_at TIMESTAMP NOT NULL,
-        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        expires_at ${datetime} NOT NULL,
+        created_at ${datetime} DEFAULT CURRENT_TIMESTAMP
       )
     `).execute();
     try {
@@ -156,8 +156,8 @@ export async function migrateAuthTables(options = {}) {
       CREATE TABLE IF NOT EXISTS two_factor_challenges (
         id VARCHAR(255) PRIMARY KEY,
         user_id INTEGER NOT NULL,
-        expires_at TIMESTAMP NOT NULL,
-        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        expires_at ${datetime} NOT NULL,
+        created_at ${datetime} DEFAULT CURRENT_TIMESTAMP
       )
     `).execute();
     try {
@@ -171,8 +171,8 @@ export async function migrateAuthTables(options = {}) {
       CREATE TABLE IF NOT EXISTS two_factor_pending_secrets (
         user_id INTEGER PRIMARY KEY,
         secret VARCHAR(255) NOT NULL,
-        expires_at TIMESTAMP NOT NULL,
-        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        expires_at ${datetime} NOT NULL,
+        created_at ${datetime} DEFAULT CURRENT_TIMESTAMP
       )
     `).execute();
     if (options.verbose)

package/dist/database.js

@@ -1,3 +1,4 @@
+import { toQueryBuilderDialect } from "./dialect";
 import { QB_SNAPSHOT_DIR } from "./utils";
 import { createQueryBuilder, setConfig } from "@stacksjs/query-builder";
 import { env as stacksEnv } from "@stacksjs/env";
@@ -41,7 +42,7 @@ export class Database {
       return;
     setConfig({
       snapshotDir: QB_SNAPSHOT_DIR,
-      dialect: this._options.driver,
+      dialect: toQueryBuilderDialect(this._options.driver),
       database: this._options.connection,
       verbose: this._options.verbose,
       timestamps: this._options.timestamps,

package/dist/datetime-columns.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The framework-owned tables whose datetime columns this guarantee covers.
+ *
+ * Model-backed tables are deliberately absent: their columns come from the
+ * migration generator, which is a separate path with its own column types.
+ */
+export declare function frameworkDatetimeTables(): string[];
+/**
+ * Every `TIMESTAMP` column still present on a framework table.
+ *
+ * Reads `information_schema` rather than `SHOW COLUMNS` so the query is a
+ * single round-trip and can be filtered to the current schema.
+ */
+export declare function findTimestampColumns(): Promise<TimestampColumn[]>;
+/**
+ * The `MODIFY` that converts one column, preserving its nullability, default
+ * and any `ON UPDATE CURRENT_TIMESTAMP` clause.
+ *
+ * Identifiers come from `information_schema` and are re-validated here before
+ * being spliced into DDL, which cannot take a placeholder.
+ */
+export declare function modifyToDatetimeSql(column: TimestampColumn): string;
+/**
+ * Convert every remaining `TIMESTAMP` column on a framework table to
+ * `DATETIME`. MySQL-only and idempotent — once converted the
+ * `information_schema` query returns nothing and this is a single cheap
+ * SELECT.
+ */
+export declare function ensureUtcDatetimeColumns(options?: { verbose?: boolean }): Promise<{ success: boolean, converted: number, error?: string }>;
+declare interface TimestampColumn {
+  table: string
+  column: string
+  nullable: boolean
+  columnDefault: string | null
+  extra: string
+}

package/dist/datetime-columns.js

@@ -0,0 +1,85 @@
+import process from "node:process";
+import { log } from "@stacksjs/logging";
+import { env as envVars } from "@stacksjs/env";
+import { db } from "./utils";
+import { dialectCapabilities } from "./dialect";
+import { traitTableNames } from "./trait-tables";
+function getDbDriver() {
+  return process.env.DB_CONNECTION || envVars.DB_CONNECTION || "sqlite";
+}
+export function frameworkDatetimeTables() {
+  return [
+    ...traitTableNames(),
+    "passkeys",
+    "password_resets",
+    "oauth_clients",
+    "oauth_access_tokens",
+    "oauth_refresh_tokens",
+    "two_factor_challenges",
+    "two_factor_pending_secrets",
+    "webauthn_challenges",
+    "roles",
+    "permissions",
+    "user_roles",
+    "user_permissions",
+    "role_permissions",
+    "notifications",
+    "notification_preferences",
+    "notification_deliveries"
+  ];
+}
+export async function findTimestampColumns() {
+  const tables = frameworkDatetimeTables(), placeholders = tables.map(() => "?").join(", ");
+  return (await db.unsafe(`SELECT TABLE_NAME, COLUMN_NAME, IS_NULLABLE, COLUMN_DEFAULT, EXTRA
+    FROM information_schema.COLUMNS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME IN (${placeholders})
+      AND (
+        DATA_TYPE = 'timestamp'
+        OR (DATA_TYPE = 'varchar' AND COLUMN_NAME IN ('created_at', 'updated_at'))
+      )`, tables).execute()).map((row) => ({
+    table: String(row.TABLE_NAME ?? row.table_name),
+    column: String(row.COLUMN_NAME ?? row.column_name),
+    nullable: String(row.IS_NULLABLE ?? row.is_nullable).toUpperCase() === "YES",
+    columnDefault: row.COLUMN_DEFAULT ?? row.column_default ?? null,
+    extra: String(row.EXTRA ?? row.extra ?? "")
+  }));
+}
+export function modifyToDatetimeSql(column) {
+  const safe = /^[a-z_]\w*$/i;
+  if (!safe.test(column.table) || !safe.test(column.column))
+    throw Error(`[datetime-columns] Refusing to alter unsafe identifier: ${column.table}.${column.column}`);
+  let ddl = `ALTER TABLE \`${column.table}\` MODIFY \`${column.column}\` DATETIME`;
+  ddl += column.nullable ? " NULL" : " NOT NULL";
+  if (column.columnDefault !== null) {
+    const isFunction = /^CURRENT_TIMESTAMP(\(\d*\))?$/i.test(String(column.columnDefault));
+    ddl += isFunction ? ` DEFAULT ${column.columnDefault}` : ` DEFAULT '${String(column.columnDefault).replace(/'/g, "''")}'`;
+  }
+  if (/on update CURRENT_TIMESTAMP/i.test(column.extra))
+    ddl += " ON UPDATE CURRENT_TIMESTAMP";
+  return ddl;
+}
+export async function ensureUtcDatetimeColumns(options = {}) {
+  const driver = getDbDriver();
+  if (dialectCapabilities(driver).wire !== "mysql")
+    return { success: !0, converted: 0 };
+  try {
+    const columns = await findTimestampColumns();
+    if (columns.length === 0) {
+      if (options.verbose)
+        log.info("No TIMESTAMP columns left to convert");
+      return { success: !0, converted: 0 };
+    }
+    for (const column of columns) {
+      if (options.verbose)
+        log.info(`Converting ${column.table}.${column.column} to DATETIME...`);
+      await db.unsafe(modifyToDatetimeSql(column)).execute();
+    }
+    log.debug(`[datetime-columns] Converted ${columns.length} TIMESTAMP column(s) to DATETIME`);
+    return { success: !0, converted: columns.length };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    log.error(`Failed to convert TIMESTAMP columns to DATETIME: ${message}`);
+    return { success: !1, converted: 0, error: message };
+  }
+}

package/dist/ddl-constraints.d.ts

@@ -0,0 +1,31 @@
+/** Find capability violations in one file's SQL. */
+export declare function auditDdlSql(sql: string, file: string, dialect: string): DdlViolation[];
+/** Audit a whole migration directory against the target dialect's capabilities. */
+export declare function auditDdlConstraints(options: {
+  dir: string
+  dialect: string
+}): DdlConstraintAudit;
+/**
+ * The user-facing explanation.
+ *
+ * Grouped by capability rather than by file: twenty foreign keys across
+ * eighteen files are one decision to make, not twenty, and listing them
+ * per-file buries that.
+ */
+export declare function formatDdlConstraintError(audit: DdlConstraintAudit, dialect: string, dir: string): string;
+/** Environment escape hatch, matching the dialect auditor's. */
+export declare const DDL_CONSTRAINT_OVERRIDE_ENV: 'STACKS_ALLOW_DDL_CONSTRAINT_VIOLATIONS';
+export declare interface DdlViolation {
+  capability: DdlCapability
+  construct: string
+  file: string
+  line: number
+  snippet: string
+}
+export declare interface DdlConstraintAudit {
+  total: number
+  violations: DdlViolation[]
+  empty: boolean
+}
+/** The capability a construct requires. */
+export type DdlCapability = 'foreignKeys' | 'autoIncrement' | 'createIndexIfNotExists';

package/dist/ddl-constraints.js

@@ -0,0 +1,111 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { dialectCapabilities } from "./dialect";
+import { stripSqlNoise } from "./migration-dialect";
+const CONSTRUCTS = [
+  { capability: "foreignKeys", pattern: /\bFOREIGN\s+KEY\b/i, label: "FOREIGN KEY" },
+  { capability: "foreignKeys", pattern: /\bREFERENCES\b/i, label: "REFERENCES" },
+  { capability: "autoIncrement", pattern: /\bAUTO_INCREMENT\b(?!\s*=)/i, label: "AUTO_INCREMENT" },
+  { capability: "createIndexIfNotExists", pattern: /\bCREATE\s+(?:UNIQUE\s+)?INDEX\s+IF\s+NOT\s+EXISTS\b/i, label: "CREATE INDEX IF NOT EXISTS" }
+];
+function supports(caps, capability) {
+  switch (capability) {
+    case "foreignKeys":
+      return caps.supportsForeignKeys;
+    case "autoIncrement":
+      return caps.supportsAutoIncrement;
+    case "createIndexIfNotExists":
+      return caps.supportsCreateIndexIfNotExists;
+  }
+}
+export function auditDdlSql(sql, file, dialect) {
+  const caps = dialectCapabilities(dialect), lines = stripSqlNoise(sql).split(`
+`), rawLines = sql.split(`
+`), found = [];
+  for (let index = 0;index < lines.length; index++)
+    for (const { capability, pattern, label } of CONSTRUCTS) {
+      if (supports(caps, capability))
+        continue;
+      if (pattern.test(lines[index] ?? ""))
+        found.push({
+          capability,
+          construct: label,
+          file,
+          line: index + 1,
+          snippet: (rawLines[index] ?? "").trim().slice(0, 120)
+        });
+    }
+  return found;
+}
+export function auditDdlConstraints(options) {
+  const { dir, dialect } = options;
+  if (!existsSync(dir))
+    return { total: 0, violations: [], empty: !0 };
+  let files;
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith(".sql")).sort();
+  } catch {
+    return { total: 0, violations: [], empty: !0 };
+  }
+  const violations = [];
+  for (const file of files) {
+    let sql;
+    try {
+      sql = readFileSync(join(dir, file), "utf8");
+    } catch {
+      continue;
+    }
+    violations.push(...auditDdlSql(sql, file, dialect));
+  }
+  return { total: files.length, violations, empty: files.length === 0 };
+}
+export const DDL_CONSTRAINT_OVERRIDE_ENV = "STACKS_ALLOW_DDL_CONSTRAINT_VIOLATIONS";
+const REMEDIES = {
+  foreignKeys: [
+    "Distributed engines cannot enforce a foreign key across shards, so referential",
+    "integrity has to move into the application. Regenerate the corpus for this",
+    "dialect \u2014 the generator emits the backing index without the constraint \u2014 and",
+    "rely on the model relationships plus `buddy doctor` (which reports orphan rows)",
+    "instead of database-level cascades."
+  ].join(`
+`),
+  autoIncrement: [
+    "Every shard would hand out the same AUTO_INCREMENT values and collide, so the",
+    "primary key has to come from somewhere else. Add `useUuid: true` to the model",
+    "traits for an application-generated key, or back the table with a sequence in",
+    "an unsharded keyspace and reference it from the VSchema."
+  ].join(`
+`),
+  createIndexIfNotExists: [
+    "MySQL has no `CREATE INDEX IF NOT EXISTS` form and rejects it as a syntax",
+    "error. Regenerate the corpus for this dialect: the generator emits a bare",
+    "`CREATE INDEX` and treats the duplicate-key error on replay as success."
+  ].join(`
+`)
+};
+export function formatDdlConstraintError(audit, dialect, dir) {
+  const byCapability = new Map;
+  for (const violation of audit.violations) {
+    const bucket = byCapability.get(violation.capability) ?? [];
+    bucket.push(violation);
+    byCapability.set(violation.capability, bucket);
+  }
+  const lines = [
+    `The migration files in ${dir} use SQL features that ${dialect} does not implement.`,
+    "",
+    "Nothing was migrated, so the database is unchanged.",
+    ""
+  ];
+  for (const [capability, found] of byCapability) {
+    const files = new Set(found.map((v) => v.file));
+    lines.push(`${found.length} use(s) of ${found[0]?.construct} across ${files.size} file(s), for example:`);
+    for (const violation of found.slice(0, 3))
+      lines.push(`  ${violation.file}:${violation.line}  ${violation.snippet}`);
+    lines.push("");
+    lines.push(REMEDIES[capability]);
+    lines.push("");
+  }
+  lines.push(`If you know this corpus is correct, re-run with ${DDL_CONSTRAINT_OVERRIDE_ENV}=1 to proceed anyway.`);
+  return lines.join(`
+`);
+}

package/dist/dialect.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Look up a dialect's capabilities.
+ *
+ * Unknown dialects resolve to SQLite. That mirrors the fallback every call
+ * site already had (`isSqlite = !isPostgres && !isMysql`) and keeps an
+ * unrecognized `DB_CONNECTION` value behaving as it did before this module
+ * existed, rather than throwing during module load in an app that is merely
+ * misconfigured.
+ */
+export declare function dialectCapabilities(dialect: string): DialectCapabilities;
+/** Whether the framework has an explicit capability row for this dialect. */
+export declare function isKnownDialect(dialect: string): boolean;
+/** Every dialect with a capability row, for CLI help and validation messages. */
+export declare function knownDialects(): string[];
+/**
+ * Whether a dialect speaks the MySQL wire protocol.
+ *
+ * This is the check that governs SQL *rendering* — placeholders, quoting,
+ * `NOW()` vs `datetime('now')`. It deliberately says nothing about DDL
+ * feature support; ask `dialectCapabilities()` for that. Conflating the two
+ * is what let SingleStore's lack of foreign keys hide behind a `true`.
+ */
+export declare function isMysqlWire(dialect: string): boolean;
+/** Whether a dialect speaks the PostgreSQL wire protocol. */
+export declare function isPostgresWire(dialect: string): boolean;
+/**
+ * Collapse a Stacks dialect to the one bun-query-builder renders for.
+ *
+ * Stacks tracks dialects that the query builder has no separate renderer
+ * for, because they differ only in DDL. Passing such a name straight
+ * through would make the query builder fall back to its own default and
+ * render the wrong SQL, so every path into `setConfig` goes through here.
+ */
+export declare function toQueryBuilderDialect(dialect: string): QueryBuilderDialect;
+export declare interface DialectCapabilities {
+  dialect: string
+  wire: SqlWireProtocol
+  queryBuilderDialect: QueryBuilderDialect
+  defaultPort?: number
+  identifierQuote: '`' | '"'
+  supportsForeignKeys: boolean
+  supportsAutoIncrement: boolean
+  supportsAtomicMultiTableTransactions: boolean
+  requiresOnlineDdl: boolean
+  supportsCreateIndexIfNotExists: boolean
+}
+/**
+ * Dialect capability table.
+ *
+ * Every dialect-conditional branch in the framework used to be an inline
+ * string comparison — `driver === 'mysql' || driver === 'singlestore'` in
+ * sql-helpers, a second copy in utils' `getDialect()`, a third in
+ * driver-config's connection-string switch, a fourth in the migration
+ * corpus auditor. Adding a dialect meant finding all of them, and missing
+ * one degraded silently: a MySQL-wire dialect that fell through to the
+ * SQLite branch emitted `datetime('now')` and `AUTOINCREMENT` at a MySQL
+ * server and only failed at execution time.
+ *
+ * This module is the single place that knows what a dialect can do. The
+ * branches above now ask it instead of re-deriving the answer, so a new
+ * entry in `CAPABILITIES` is the whole change.
+ *
+ * The distinction that matters most here is **wire protocol vs. feature
+ * set**. Several dialects speak the MySQL wire protocol and share its DML
+ * rendering (backtick quoting, `?` placeholders, `LAST_INSERT_ID()`,
+ * `ON DUPLICATE KEY UPDATE`) while diverging sharply in what DDL they
+ * accept. SingleStore takes MySQL's wire and rejects its foreign keys.
+ * Treating "is MySQL" as one boolean is what made that divergence hard to
+ * express, so `wire` and the `supports*` flags are tracked separately.
+ */
+/**
+ * The connection protocol a dialect speaks. Determines placeholder style,
+ * identifier quoting, and which connection URL scheme dials it.
+ */
+export type SqlWireProtocol = 'mysql' | 'postgres' | 'sqlite';
+/**
+ * The dialect string handed to bun-query-builder. Several Stacks dialects
+ * collapse onto one of these — the query builder only needs to know how to
+ * render SQL, and a dialect that is wire- and DML-identical to MySQL wants
+ * MySQL's renderer even when Stacks tracks it separately for DDL purposes.
+ */
+export type QueryBuilderDialect = 'sqlite' | 'mysql' | 'singlestore' | 'vitess' | 'postgres';

package/dist/dialect.js

@@ -0,0 +1,79 @@
+const CAPABILITIES = {
+  sqlite: {
+    dialect: "sqlite",
+    wire: "sqlite",
+    queryBuilderDialect: "sqlite",
+    identifierQuote: '"',
+    supportsForeignKeys: !0,
+    supportsAutoIncrement: !0,
+    supportsAtomicMultiTableTransactions: !0,
+    requiresOnlineDdl: !1,
+    supportsCreateIndexIfNotExists: !0
+  },
+  mysql: {
+    dialect: "mysql",
+    wire: "mysql",
+    queryBuilderDialect: "mysql",
+    defaultPort: 3306,
+    identifierQuote: "`",
+    supportsForeignKeys: !0,
+    supportsAutoIncrement: !0,
+    supportsAtomicMultiTableTransactions: !0,
+    requiresOnlineDdl: !1,
+    supportsCreateIndexIfNotExists: !1
+  },
+  singlestore: {
+    dialect: "singlestore",
+    wire: "mysql",
+    queryBuilderDialect: "singlestore",
+    defaultPort: 3306,
+    identifierQuote: "`",
+    supportsForeignKeys: !1,
+    supportsAutoIncrement: !0,
+    supportsAtomicMultiTableTransactions: !1,
+    requiresOnlineDdl: !1,
+    supportsCreateIndexIfNotExists: !1
+  },
+  vitess: {
+    dialect: "vitess",
+    wire: "mysql",
+    queryBuilderDialect: "vitess",
+    defaultPort: 15306,
+    identifierQuote: "`",
+    supportsForeignKeys: !1,
+    supportsAutoIncrement: !1,
+    supportsAtomicMultiTableTransactions: !1,
+    requiresOnlineDdl: !0,
+    supportsCreateIndexIfNotExists: !1
+  },
+  postgres: {
+    dialect: "postgres",
+    wire: "postgres",
+    queryBuilderDialect: "postgres",
+    defaultPort: 5432,
+    identifierQuote: '"',
+    supportsForeignKeys: !0,
+    supportsAutoIncrement: !0,
+    supportsAtomicMultiTableTransactions: !0,
+    requiresOnlineDdl: !1,
+    supportsCreateIndexIfNotExists: !0
+  }
+};
+export function dialectCapabilities(dialect) {
+  return CAPABILITIES[dialect] ?? CAPABILITIES.sqlite;
+}
+export function isKnownDialect(dialect) {
+  return dialect in CAPABILITIES;
+}
+export function knownDialects() {
+  return Object.keys(CAPABILITIES);
+}
+export function isMysqlWire(dialect) {
+  return dialectCapabilities(dialect).wire === "mysql";
+}
+export function isPostgresWire(dialect) {
+  return dialectCapabilities(dialect).wire === "postgres";
+}
+export function toQueryBuilderDialect(dialect) {
+  return dialectCapabilities(dialect).queryBuilderDialect;
+}

package/dist/driver-config.d.ts

@@ -1,3 +1,4 @@
+import type { NetworkedConnectionOptions, PoolOptions, ReadPolicyOptions, ReplicaOptions } from '@stacksjs/types';
 import type { StacksDialect } from '@stacksjs/query-builder';
 /**
  * Get the connection string for a given driver and configuration
@@ -45,6 +46,15 @@ export declare function detectDriver(): StacksDialect;
  *     charset: 'utf8mb4',
  *     ssl: false
  *   },
+ *   vitess: {
+ *     name: 'stacks',
+ *     host: '127.0.0.1',
+ *     port: 15306,
+ *     username: 'root',
+ *     password: '',
+ *     prefix: '',
+ *     ssl: false
+ *   },
  *   postgres: {
  *     name: 'stacks',
  *     host: '127.0.0.1',
@@ -57,7 +67,7 @@ export declare function detectDriver(): StacksDialect;
  * }
  * ```
  */
-export declare const driverDefaults: Record<StacksDialect, Partial<SqliteConfig | MysqlConfig | SinglestoreConfig | PostgresConfig | DynamoDbConfig>>;
+export declare const driverDefaults: Record<StacksDialect, Partial<SqliteConfig | MysqlConfig | SinglestoreConfig | VitessConfig | PostgresConfig | DynamoDbConfig>>;
 /**
  * SQLite specific configuration
  */
@@ -66,9 +76,13 @@ export declare interface SqliteConfig {
   prefix?: string
 }
 /**
- * MySQL specific configuration
+ * MySQL specific configuration.
+ *
+ * Extends `NetworkedConnectionConfig` for `pool` and `replicas` — both are
+ * meaningless for the embedded SQLite dialect, which is why they live on a
+ * base the client-server shapes extend rather than on every connection.
  */
-export declare interface MysqlConfig {
+export declare interface MysqlConfig extends NetworkedConnectionConfig {
   name: string
   host?: string
   port?: number
@@ -86,7 +100,7 @@ export declare interface MysqlConfig {
  * SHARD KEY / SORT KEY, no foreign keys) — handled by the migration generator,
  * not by the connection layer.
  */
-export declare interface SinglestoreConfig {
+export declare interface SinglestoreConfig extends NetworkedConnectionConfig {
   name: string
   host?: string
   port?: number
@@ -96,10 +110,33 @@ export declare interface SinglestoreConfig {
   charset?: string
   ssl?: boolean
 }
+/**
+ * Vitess specific configuration.
+ *
+ * Vitess is a sharding layer in front of MySQL. The application connects to
+ * vtgate, which speaks the MySQL wire protocol, so this shares MySQL's
+ * connection shape. Two things differ and both matter:
+ *
+ *  - the default port is vtgate's 15306, not mysqld's 3306. Connecting to
+ *    3306 on a Vitess cluster reaches an individual tablet's underlying
+ *    MySQL and silently bypasses sharding altogether.
+ *  - `name` is a KEYSPACE, not a database. It is the unit Vitess shards,
+ *    and it is what the VSchema is written against.
+ */
+export declare interface VitessConfig extends NetworkedConnectionConfig {
+  name: string
+  host?: string
+  port?: number
+  username?: string
+  password?: string
+  prefix?: string
+  ssl?: boolean
+  tabletType?: 'primary' | 'replica' | 'rdonly'
+}
 /**
  * PostgreSQL specific configuration
  */
-export declare interface PostgresConfig {
+export declare interface PostgresConfig extends NetworkedConnectionConfig {
   name: string
   host?: string
   port?: number
@@ -135,6 +172,7 @@ export declare interface DatabaseConnections {
   sqlite?: SqliteConfig
   mysql?: MysqlConfig
   singlestore?: SinglestoreConfig
+  vitess?: VitessConfig
   postgres?: PostgresConfig
   dynamodb?: DynamoDbConfig
 }
@@ -146,4 +184,16 @@ export declare interface FullDatabaseConfig {
   connections: DatabaseConnections
   migrations?: string
   migrationLocks?: string
+  reads?: ReadPolicyConfig
 }
+/**
+ * Connection pool, replica, and read-policy shapes.
+ *
+ * Defined in `@stacksjs/types` (the package `config/database.ts` is typed
+ * against) and aliased here so the database package has one name for them
+ * and users never see two subtly different definitions of the same block.
+ */
+export type PoolConfig = PoolOptions;
+export type ReplicaConfig = ReplicaOptions;
+export type ReadPolicyConfig = ReadPolicyOptions;
+export type NetworkedConnectionConfig = NetworkedConnectionOptions;