@stacksjs/database 0.70.255 → 0.70.257

package/dist/trait-tables.d.ts

@@ -0,0 +1,126 @@
+import { sqlHelpers } from './sql-helpers';
+/**
+ * The tables {@link migrateTraitTables} owns.
+ *
+ * The single source of truth for this set: the reset paths in
+ * `drivers/defaults/traits.ts` drop exactly these, so a table added here is
+ * dropped by `migrate:fresh` without a second list to remember.
+ */
+export declare function traitTableNames(): string[];
+/**
+ * `commentables` — comments attached polymorphically to an owning model.
+ * `commentables_id` + `commentables_type` identify the owner (e.g. 123 /
+ * 'posts'). Columns match `CommentablesTable` and the writes in
+ * `cms/src/commentables/store.ts` and `orm/src/traits/commentable.ts`.
+ *
+ * `approved_at` / `rejected_at` hold epoch milliseconds, which overflows a
+ * 32-bit INTEGER on Postgres and MySQL — hence BIGINT. SQLite gives every
+ * INTEGER 64 bits, so the same declaration is correct there too.
+ *
+ * This is a distinct table from `comments`: `comments` is a model-backed
+ * table, `commentables` is the polymorphic trait table.
+ */
+export declare function commentablesTableSql(sql: SqlHelpers): string;
+/**
+ * `taggables` — the tag catalogue, scoped to an owning model type.
+ *
+ * The two consumers disagree about ownership: the CMS module treats a row as a
+ * type-scoped tag with no single owner, while `orm/src/traits/taggable.ts`
+ * writes one row per owner and filters on `taggable_id`. Both are served by
+ * defaulting `taggable_id` to {@link UNSCOPED_OWNER_ID} — a CMS write lands on
+ * the sentinel, an ORM write carries the real owner, and the unique index is
+ * scoped by both so neither collides with the other.
+ */
+export declare function taggablesTableSql(sql: SqlHelpers): string;
+/**
+ * `categorizables` — the category catalogue, scoped to an owning model type.
+ * The owner link lives in the model-declared `categorizable_models` pivot,
+ * which `orm/src/traits/categorizable.ts` reads to resolve category ids.
+ */
+export declare function categorizablesTableSql(sql: SqlHelpers): string;
+/**
+ * `taggable_models` — links an owning record to a row in the tag catalogue.
+ *
+ * Guaranteed here because the trait needs it whenever a model sets
+ * `taggable: true`. It otherwise only exists when a model *separately*
+ * declares a matching `belongsToMany` pivot (as the framework's Post model
+ * does), which left `taggable: true` on its own pointing at a missing table.
+ */
+export declare function taggableModelsTableSql(sql: SqlHelpers): string;
+/**
+ * `categorizable_models` — the categorizable counterpart to
+ * {@link taggableModelsTableSql}. `orm/src/traits/categorizable.ts` reads this
+ * table directly to resolve the category ids an owner is filed under.
+ */
+export declare function categorizableModelsTableSql(sql: SqlHelpers): string;
+/**
+ * `<table>_likes` — the per-model table the `likeable` trait reads and writes.
+ *
+ * Unlike every other trait table this one has no fixed name: the trait derives
+ * it from the owning model (`posts` → `posts_likes`), or from
+ * `likeable: { table, foreignKey }`. Nothing created it on any driver, so
+ * `likeable: true` failed with "no such table" exactly the way the
+ * polymorphic traits did.
+ *
+ * `UNIQUE (foreignKey, user_id)` is the constraint `like()` already depends on:
+ * it catches the duplicate and returns the existing row instead of inserting
+ * twice.
+ */
+export declare function likesTableSql(sql: SqlHelpers, table: string, foreignKey: string): string;
+/**
+ * `commentable_upvotes` — upvotes on a polymorphic target. Columns match
+ * `CommentableUpvotesTable`.
+ */
+export declare function commentableUpvotesTableSql(sql: SqlHelpers): string;
+/**
+ * Secondary indexes for the trait tables.
+ *
+ * The unique indexes are the catalogue contract the CMS `findOrCreate` paths
+ * rely on: a tag/category name is unique *within* an owning model type, so
+ * 'posts' and 'products' can each have a "news" tag.
+ *
+ * Kept separate from the CREATE TABLE statements because not every dialect
+ * accepts `CREATE INDEX IF NOT EXISTS` — see
+ * `DialectCapabilities.supportsCreateIndexIfNotExists`. Where it isn't
+ * supported, {@link migrateTraitTables} drops the clause and tolerates the
+ * duplicate-index error on replay instead.
+ */
+export declare function traitTableIndexSql(): string[];
+/**
+ * The `<table>_likes` tables to create, one per model that sets `likeable`.
+ *
+ * Model discovery mirrors the reset paths (`dropSqliteTables`, …): userland
+ * models first, then the framework defaults. The orm helpers are imported
+ * lazily because this module is a leaf that the drivers barrel imports —
+ * pulling `@stacksjs/orm` in at the top level would re-enter that barrel and
+ * deadlock bun's module loader (see `drivers/helpers.ts`).
+ */
+export declare function likeableTargets(): Promise<Array<{ table: string, foreignKey: string }>>;
+/**
+ * Strip `IF NOT EXISTS` for dialects that reject it on `CREATE INDEX`, and let
+ * {@link isDuplicateIndexError} absorb the replay there instead.
+ */
+export declare function indexSqlForDialect(statement: string, dialect: string): string;
+/**
+ * Create the polymorphic trait tables. Idempotent (`IF NOT EXISTS`), so it's
+ * safe to run on every `buddy migrate`.
+ *
+ * Runs AFTER the model migrations for the same reason the notification and
+ * RBAC guarantees do: an app model that legitimately owns one of these table
+ * names must stay authoritative, and pre-creating the table would suppress
+ * its generated migration.
+ */
+export declare function migrateTraitTables(options?: { verbose?: boolean }): Promise<{ success: boolean, error?: string }>;
+/**
+ * The `taggable_id` / `categorizable_id` value that marks a catalogue row —
+ * a tag or category that belongs to an owning model *type* but to no
+ * individual record.
+ *
+ * A sentinel rather than NULL because the uniqueness rule has to hold on all
+ * three engines: SQLite and MySQL treat NULLs as distinct in a UNIQUE index
+ * (so two catalogue rows with the same slug would both be accepted), and
+ * `NULLS NOT DISTINCT` is Postgres 15+ only. A concrete value makes
+ * `UNIQUE (type, owner_id, slug)` mean the same thing everywhere.
+ */
+export declare const UNSCOPED_OWNER_ID: 0;
+declare type SqlHelpers = ReturnType<typeof sqlHelpers>;

package/dist/trait-tables.js

@@ -0,0 +1,206 @@
+import { log } from "@stacksjs/logging";
+import { env as envVars } from "@stacksjs/env";
+import { db } from "./utils";
+import { sqlHelpers } from "./sql-helpers";
+import { dialectCapabilities } from "./dialect";
+function getDbDriver() {
+  return process.env.DB_CONNECTION || envVars.DB_CONNECTION || "sqlite";
+}
+function createdAt(sql) {
+  return `created_at ${sql.datetime}`;
+}
+function updatedAt(sql) {
+  return `updated_at ${sql.nullableTimestamp}`;
+}
+export function traitTableNames() {
+  return [
+    "commentables",
+    "taggables",
+    "categorizables",
+    "commentable_upvotes",
+    "taggable_models",
+    "categorizable_models"
+  ];
+}
+export const UNSCOPED_OWNER_ID = 0;
+export function commentablesTableSql(sql) {
+  const { pkColumn, boolTrue } = sql;
+  return `CREATE TABLE IF NOT EXISTS commentables (
+    ${pkColumn},
+    title VARCHAR(255) NOT NULL,
+    body TEXT NOT NULL,
+    status VARCHAR(50) NOT NULL DEFAULT 'pending',
+    approved_at BIGINT,
+    rejected_at BIGINT,
+    commentables_id INTEGER NOT NULL,
+    commentables_type VARCHAR(255) NOT NULL,
+    user_id INTEGER,
+    is_active BOOLEAN NOT NULL DEFAULT ${boolTrue},
+    ${createdAt(sql)},
+    ${updatedAt(sql)}
+  )`;
+}
+export function taggablesTableSql(sql) {
+  const { pkColumn, boolTrue } = sql;
+  return `CREATE TABLE IF NOT EXISTS taggables (
+    ${pkColumn},
+    name VARCHAR(255) NOT NULL,
+    slug VARCHAR(255) NOT NULL,
+    description TEXT,
+    is_active BOOLEAN NOT NULL DEFAULT ${boolTrue},
+    taggable_id INTEGER NOT NULL DEFAULT ${UNSCOPED_OWNER_ID},
+    taggable_type VARCHAR(255) NOT NULL,
+    ${createdAt(sql)},
+    ${updatedAt(sql)}
+  )`;
+}
+export function categorizablesTableSql(sql) {
+  const { pkColumn, boolTrue } = sql;
+  return `CREATE TABLE IF NOT EXISTS categorizables (
+    ${pkColumn},
+    name VARCHAR(255) NOT NULL,
+    slug VARCHAR(255) NOT NULL,
+    description TEXT,
+    is_active BOOLEAN NOT NULL DEFAULT ${boolTrue},
+    categorizable_id INTEGER NOT NULL DEFAULT ${UNSCOPED_OWNER_ID},
+    categorizable_type VARCHAR(255) NOT NULL,
+    ${createdAt(sql)},
+    ${updatedAt(sql)}
+  )`;
+}
+export function taggableModelsTableSql(sql) {
+  const { pkColumn } = sql;
+  return `CREATE TABLE IF NOT EXISTS taggable_models (
+    ${pkColumn},
+    tag_id INTEGER NOT NULL,
+    taggable_id INTEGER NOT NULL,
+    taggable_type VARCHAR(255) NOT NULL,
+    ${createdAt(sql)},
+    ${updatedAt(sql)}
+  )`;
+}
+export function categorizableModelsTableSql(sql) {
+  const { pkColumn } = sql;
+  return `CREATE TABLE IF NOT EXISTS categorizable_models (
+    ${pkColumn},
+    category_id INTEGER NOT NULL,
+    categorizable_id INTEGER NOT NULL,
+    categorizable_type VARCHAR(255) NOT NULL,
+    ${createdAt(sql)},
+    ${updatedAt(sql)}
+  )`;
+}
+export function likesTableSql(sql, table, foreignKey) {
+  const { pkColumn } = sql;
+  return `CREATE TABLE IF NOT EXISTS ${table} (
+    ${pkColumn},
+    ${foreignKey} INTEGER NOT NULL,
+    user_id INTEGER NOT NULL,
+    ${createdAt(sql)},
+    ${updatedAt(sql)},
+    UNIQUE (${foreignKey}, user_id)
+  )`;
+}
+export function commentableUpvotesTableSql(sql) {
+  const { pkColumn } = sql;
+  return `CREATE TABLE IF NOT EXISTS commentable_upvotes (
+    ${pkColumn},
+    user_id INTEGER,
+    upvoteable_id INTEGER NOT NULL,
+    upvoteable_type VARCHAR(255) NOT NULL,
+    ${createdAt(sql)}
+  )`;
+}
+export function traitTableIndexSql() {
+  return [
+    "CREATE INDEX IF NOT EXISTS commentables_owner_index ON commentables (commentables_type, commentables_id)",
+    "CREATE INDEX IF NOT EXISTS commentables_status_index ON commentables (status)",
+    "CREATE UNIQUE INDEX IF NOT EXISTS taggables_owner_slug_unique ON taggables (taggable_type, taggable_id, slug)",
+    "CREATE UNIQUE INDEX IF NOT EXISTS categorizables_owner_slug_unique ON categorizables (categorizable_type, categorizable_id, slug)",
+    "CREATE INDEX IF NOT EXISTS commentable_upvotes_target_index ON commentable_upvotes (upvoteable_type, upvoteable_id)",
+    "CREATE UNIQUE INDEX IF NOT EXISTS commentable_upvotes_user_unique ON commentable_upvotes (upvoteable_type, upvoteable_id, user_id)",
+    "CREATE UNIQUE INDEX IF NOT EXISTS taggable_models_unique ON taggable_models (tag_id, taggable_id, taggable_type)",
+    "CREATE UNIQUE INDEX IF NOT EXISTS categorizable_models_unique ON categorizable_models (category_id, categorizable_id, categorizable_type)"
+  ];
+}
+export async function likeableTargets() {
+  const { path } = await import("@stacksjs/path"), { globSync } = await import("@stacksjs/storage"), { getTableName } = await import("@stacksjs/orm"), { getLikeableForeignKey, getUpvoteTableName } = await import("./drivers/helpers"), modelFiles = globSync([path.userModelsPath("*.ts"), path.storagePath("framework/defaults/app/Models/**/*.ts")], { absolute: !0 }), targets = new Map;
+  for (const modelFile of modelFiles) {
+    let model;
+    try {
+      model = (await import(modelFile)).default;
+    } catch {
+      continue;
+    }
+    if (!model?.traits?.likeable)
+      continue;
+    const tableName = await getTableName(model, modelFile);
+    if (!tableName)
+      continue;
+    const table = getUpvoteTableName(model, tableName);
+    if (!table || !/^[a-z_]\w*$/i.test(table))
+      continue;
+    const foreignKey = getLikeableForeignKey(model, tableName);
+    if (!/^[a-z_]\w*$/i.test(foreignKey))
+      continue;
+    targets.set(table, { table, foreignKey });
+  }
+  return [...targets.values()];
+}
+export function indexSqlForDialect(statement, dialect) {
+  if (dialectCapabilities(dialect).supportsCreateIndexIfNotExists)
+    return statement;
+  return statement.replace(/^(CREATE (?:UNIQUE )?INDEX) IF NOT EXISTS /i, "$1 ");
+}
+function isDuplicateIndexError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return /duplicate key name|already exists/i.test(message);
+}
+export async function migrateTraitTables(options = {}) {
+  const dbDriver = getDbDriver(), sql = sqlHelpers(dbDriver);
+  if (options.verbose)
+    log.info(`Creating polymorphic trait tables for ${dbDriver}...`);
+  try {
+    if (options.verbose)
+      log.info("Creating commentables table...");
+    await db.unsafe(commentablesTableSql(sql)).execute();
+    if (options.verbose)
+      log.info("Creating taggables table...");
+    await db.unsafe(taggablesTableSql(sql)).execute();
+    if (options.verbose)
+      log.info("Creating categorizables table...");
+    await db.unsafe(categorizablesTableSql(sql)).execute();
+    if (options.verbose)
+      log.info("Creating commentable_upvotes table...");
+    await db.unsafe(commentableUpvotesTableSql(sql)).execute();
+    if (options.verbose)
+      log.info("Creating taggable_models pivot...");
+    await db.unsafe(taggableModelsTableSql(sql)).execute();
+    if (options.verbose)
+      log.info("Creating categorizable_models pivot...");
+    await db.unsafe(categorizableModelsTableSql(sql)).execute();
+    try {
+      for (const { table, foreignKey } of await likeableTargets()) {
+        if (options.verbose)
+          log.info(`Creating ${table} table...`);
+        await db.unsafe(likesTableSql(sql, table, foreignKey)).execute();
+      }
+    } catch (error) {
+      log.debug(`[trait-tables] Skipped likeable tables: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    for (const statement of traitTableIndexSql())
+      try {
+        await db.unsafe(indexSqlForDialect(statement, dbDriver)).execute();
+      } catch (error) {
+        if (!isDuplicateIndexError(error))
+          throw error;
+      }
+    if (options.verbose)
+      log.success("Polymorphic trait tables created");
+    return { success: !0 };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    log.error(`Failed to create polymorphic trait tables: ${message}`);
+    return { success: !1, error: message };
+  }
+}

package/dist/utils.d.ts

@@ -4,8 +4,28 @@ export declare function acquireDbConfigLock(): Promise<() => void>;
 // Function to initialize the config when it's available
 export declare function initializeDbConfig(config: any): void;
 export declare function createDatabaseQueryHooks(dispatch: (event: DatabaseQueryLogEvent) => void | Promise<void>): QueryHooks;
+declare function ensureConfigLoaded(): Promise<void>;
 export declare function ensureDatabaseConfigLoaded(): Promise<void>;
 declare function getDb(): ReturnType<typeof createQueryBuilder>;
+/**
+ * The builder a read should use right now.
+ *
+ * Falls back to the primary whenever routing is not permitted — no
+ * replicas configured, auto-routing off, inside a transaction, or after a
+ * write in this async context. See `./replicas` for why each of those
+ * carve-outs exists.
+ */
+declare function getReadDb(): ReturnType<typeof createQueryBuilder>;
+/**
+ * Explicitly replica-routed handle: `db.read.selectFrom('users')`.
+ *
+ * Unlike automatic routing this ignores `reads.autoRoute` — asking for
+ * `db.read` IS the statement that this particular query tolerates a stale
+ * result. It still respects the transaction carve-out, because a read
+ * inside a transaction must see that transaction's own writes no matter
+ * how it was requested.
+ */
+declare function getExplicitReadDb(): ReturnType<typeof createQueryBuilder>;
 /**
  * Update bun-query-builder configuration
  */
@@ -33,11 +53,23 @@ export declare const RAW_QUERY_SOFT_DELETE_CONFIG: {
   column: 'deleted_at';
   defaultFilter: true
 };
+/** Statements that mutate, for the read-your-writes tracking in `./replicas`. */
+declare const WRITE_ENTRY_POINTS: Set<any>;
+/** Reads that are candidates for replica routing. */
+declare const READ_ENTRY_POINTS: Set<any>;
 /**
  * Lazy proxy for the query builder - connection is only made when first used.
  * This is the main entry point for database operations.
  */
 export declare const db: Proxy;
+/**
+ * Replica-routed handle exposed as `db.read`.
+ *
+ * A separate proxy rather than a method so the whole builder surface stays
+ * available behind it (`db.read.selectFrom(...).where(...)`) without
+ * re-declaring every chain entry point.
+ */
+export declare const readDb: Proxy;
 export declare interface DatabaseQueryLogEvent {
   query: {
     sql: string
@@ -159,6 +191,7 @@ declare interface Db extends Pick<Required<RawQueryBuilder>, GenericPassthroughK
   selectFromSub: (sub: any, alias: string) => FluentChain
   select: (table: TableName, ...columns: string[]) => FluentChain
   unsafe: (query: string, params?: any[]) => UnsafeReturn
+  read: Omit<Db, 'read'>
 }
 // The bun-query-builder types `unsafe()` as returning `Promise<any>`, but at
 // runtime it returns a Bun SQL Statement that has `.execute()`. This interface

package/dist/utils.js

@@ -1,7 +1,10 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createQueryBuilder, registerPersistentQueryHooks, setConfig } from "@stacksjs/query-builder";
+import { SQL } from "bun";
 import { env as envVars } from "@stacksjs/env";
 import { getConnectionDefaults } from "./defaults";
+import { isMysqlWire, toQueryBuilderDialect } from "./dialect";
+import { contextInTransaction, markContextWrote, resolveReplicaConnection, selectReplica, shouldRouteToReplica, withTransactionContext } from "./replicas";
 import { aggregateFunctions } from "./types";
 const sqliteDefaults = getConnectionDefaults("sqlite", envVars), mysqlDefaults = getConnectionDefaults("mysql", envVars), postgresDefaults = getConnectionDefaults("postgres", envVars);
 let appEnv = envVars.APP_ENV || "local", dbDriver = envVars.DB_CONNECTION || "sqlite", dbConfig = {
@@ -9,6 +12,7 @@ let appEnv = envVars.APP_ENV || "local", dbDriver = envVars.DB_CONNECTION || "sq
     sqlite: { database: sqliteDefaults.database, prefix: "" },
     mysql: { name: mysqlDefaults.database, host: mysqlDefaults.host, username: mysqlDefaults.username, password: mysqlDefaults.password, port: mysqlDefaults.port, prefix: "" },
     singlestore: { name: mysqlDefaults.database, host: mysqlDefaults.host, username: mysqlDefaults.username, password: mysqlDefaults.password, port: mysqlDefaults.port, prefix: "" },
+    vitess: { name: mysqlDefaults.database, host: mysqlDefaults.host, username: mysqlDefaults.username, password: mysqlDefaults.password, port: 15306, prefix: "" },
     postgres: { name: postgresDefaults.database, host: postgresDefaults.host, username: postgresDefaults.username, password: postgresDefaults.password, port: postgresDefaults.port, prefix: "" }
   }
 }, dbConfigLockTail = Promise.resolve();
@@ -29,6 +33,7 @@ export function initializeDbConfig(config) {
     dbConfig = config.database;
   updateQueryBuilderConfig();
   _dbInstance = null;
+  _replicaInstances = new Map;
 }
 function getEnv() {
   return appEnv;
@@ -40,16 +45,7 @@ function getDatabaseConfig() {
   return dbConfig;
 }
 function getDialect() {
-  const driver = getDriver();
-  if (driver === "sqlite")
-    return "sqlite";
-  if (driver === "mysql")
-    return "mysql";
-  if (driver === "singlestore")
-    return "singlestore";
-  if (driver === "postgres")
-    return "postgres";
-  return "sqlite";
+  return toQueryBuilderDialect(getDriver());
 }
 function getDbConfig() {
   const driver = getDriver(), database = getDatabaseConfig(), env = getEnv();
@@ -75,6 +71,14 @@ function getDbConfig() {
       password: database.connections?.singlestore?.password ?? "",
       port: database.connections?.singlestore?.port ?? 3306
     };
+  if (driver === "vitess")
+    return {
+      database: database.connections?.vitess?.name || "stacks",
+      host: database.connections?.vitess?.host ?? "127.0.0.1",
+      username: database.connections?.vitess?.username ?? "root",
+      password: database.connections?.vitess?.password ?? "",
+      port: database.connections?.vitess?.port ?? 15306
+    };
   if (driver === "postgres") {
     const dbName = database.connections?.postgres?.name ?? "stacks";
     return {
@@ -120,11 +124,40 @@ function forwardDatabaseQuery(event) {
   import("./query-logger").then(({ logQuery }) => logQuery(event)).catch(() => {});
 }
 registerPersistentQueryHooks(createDatabaseQueryHooks(forwardDatabaseQuery));
+function getPoolConfig() {
+  const driver = getDriver();
+  if (driver === "sqlite")
+    return;
+  return getDatabaseConfig().connections?.[driver]?.pool;
+}
+function getReplicas() {
+  const driver = getDriver();
+  if (driver === "sqlite")
+    return [];
+  return getDatabaseConfig().connections?.[driver]?.replicas ?? [];
+}
+function getReadPolicy() {
+  return getDatabaseConfig().reads ?? {};
+}
+function toBunPoolOptions(pool) {
+  if (!pool)
+    return {};
+  const options = {};
+  if (pool.max !== void 0)
+    options.max = pool.max;
+  if (pool.idleTimeoutMs !== void 0)
+    options.idleTimeout = Math.round(pool.idleTimeoutMs / 1000);
+  if (pool.acquireTimeoutMs !== void 0)
+    options.connectionTimeout = Math.round(pool.acquireTimeoutMs / 1000);
+  if (pool.maxLifetimeMs !== void 0)
+    options.maxLifetime = Math.round(pool.maxLifetimeMs / 1000);
+  return options;
+}
 function updateQueryBuilderConfig() {
-  const dialect = getDialect(), dbConfigForQb = getDbConfig();
+  const dialect = getDialect(), dbConfigForQb = getDbConfig(), pool = getPoolConfig();
   setConfig({
     dialect,
-    database: dbConfigForQb,
+    database: pool ? { ...dbConfigForQb, pool } : dbConfigForQb,
     verbose: getEnv() !== "production",
     snapshotDir: QB_SNAPSHOT_DIR,
     timestamps: {
@@ -172,21 +205,77 @@ function applySqliteTransactionSerialization(instance) {
   const original = instance.transaction.bind(instance);
   instance.transaction = (...args) => serializeSqliteTransaction(() => original(...args));
 }
+function applyTransactionRoutingContext(instance) {
+  const original = instance.transaction.bind(instance);
+  instance.transaction = (...args) => withTransactionContext(() => original(...args));
+}
 function getDb() {
   if (!_dbInstance) {
     updateQueryBuilderConfig();
     _dbInstance = createQueryBuilder();
     if (getDialect() === "sqlite")
       applySqliteTransactionSerialization(_dbInstance);
+    applyTransactionRoutingContext(_dbInstance);
   }
   return _dbInstance;
 }
+let _replicaInstances = new Map;
+function getReplicaDb(replica) {
+  const primary = getDbConfig(), resolved = resolveReplicaConnection(replica, primary), key = `${resolved.host}:${resolved.port ?? ""}`, cached = _replicaInstances.get(key);
+  if (cached)
+    return cached;
+  const scheme = isMysqlWire(getDriver()) ? "mysql" : "postgres", auth = resolved.username ? `${encodeURIComponent(resolved.username)}:${encodeURIComponent(resolved.password ?? "")}@` : "", url = `${scheme}://${auth}${resolved.host}:${resolved.port}/${resolved.database}`, sql = new SQL({ url, ...toBunPoolOptions(getPoolConfig()) }), instance = createQueryBuilder({ sql });
+  _replicaInstances.set(key, instance);
+  return instance;
+}
+function getReadDb() {
+  const replicas = getReplicas(), policy = getReadPolicy();
+  if (!shouldRouteToReplica({ policy, replicas }))
+    return getDb();
+  const replica = selectReplica(replicas, policy.strategy);
+  return replica ? getReplicaDb(replica) : getDb();
+}
+function getExplicitReadDb() {
+  const replicas = getReplicas();
+  if (!replicas.length || contextInTransaction())
+    return getDb();
+  const replica = selectReplica(replicas, getReadPolicy().strategy);
+  return replica ? getReplicaDb(replica) : getDb();
+}
+const WRITE_ENTRY_POINTS = new Set([
+  "insertInto",
+  "updateTable",
+  "deleteFrom",
+  "create",
+  "createMany",
+  "insertOrIgnore",
+  "insertGetId",
+  "updateOrInsert",
+  "upsert"
+]), READ_ENTRY_POINTS = new Set([
+  "selectFrom",
+  "selectFromSub",
+  "select"
+]);
 ensureConfigLoaded();
 export const db = new Proxy({}, {
   get(_target, prop) {
     if (prop === "fn")
       return aggregateFunctions;
-    const instance = getDb(), value = instance[prop];
+    if (prop === "read")
+      return readDb;
+    if (typeof prop === "string" && WRITE_ENTRY_POINTS.has(prop))
+      markContextWrote();
+    const instance = typeof prop === "string" && READ_ENTRY_POINTS.has(prop) ? getReadDb() : getDb(), value = instance[prop];
+    if (typeof value === "function")
+      return value.bind(instance);
+    return value;
+  }
+}), readDb = new Proxy({}, {
+  get(_target, prop) {
+    if (prop === "fn")
+      return aggregateFunctions;
+    const instance = getExplicitReadDb(), value = instance[prop];
     if (typeof value === "function")
       return value.bind(instance);
     return value;

package/dist/vschema.d.ts

@@ -0,0 +1,84 @@
+import type { VindexType } from '@stacksjs/types';
+/**
+ * Convert a model name to its conventional foreign key column.
+ *
+ * `User` -> `user_id`. Deliberately simple: it mirrors the convention the
+ * ORM's own relation resolution uses, and a model that diverges from it can
+ * state the column outright in `traits.sharding`.
+ */
+export declare function foreignKeyForModel(modelName: string): string;
+/**
+ * Decide how one model shards.
+ *
+ * Split out from `deriveVSchema` so the decision is testable on its own —
+ * it is the part with actual judgement in it, and the part a user will want
+ * to reason about when a query turns out to scatter.
+ */
+export declare function decideSharding(model: ShardableModel, tableByModel: Map<string, string>): ShardingDecision;
+/**
+ * Build a keyspace VSchema from model definitions.
+ *
+ * Returns the decisions alongside the document because the document alone
+ * does not explain itself: a user reviewing a generated VSchema needs to
+ * know which tables co-locate and which will scatter, and that is exactly
+ * what is lost once it is serialized to JSON.
+ */
+export declare function deriveVSchema(models: ShardableModel[]): VSchemaResult;
+/**
+ * Normalize a raw model definition into a `ShardableModel`.
+ *
+ * `belongsTo` accepts several shapes across the codebase (a bare string, an
+ * array of names, or an object keyed by model name), so this flattens them
+ * to the one form the derivation needs.
+ */
+export declare function toShardableModel(definition: any, table: string): ShardableModel;
+/**
+ * Human-readable summary of the sharding decisions.
+ *
+ * Printed by `buddy generate:vschema` because the whole point of deriving
+ * the topology is lost if the user cannot see and challenge it.
+ */
+export declare function formatShardingReport(decisions: ShardingDecision[]): string;
+/** The subset of a model definition this module needs. */
+export declare interface ShardableModel {
+  name: string
+  table: string
+  belongsTo: string[]
+  useUuid: boolean
+  sharding?: {
+    column?: string
+    vindex?: VindexType
+    unsharded?: boolean
+    sequence?: string
+  }
+}
+/** A `column_vindexes` entry in the emitted VSchema. */
+export declare interface ColumnVindex {
+  column: string
+  name: string
+}
+/** A table entry in the emitted VSchema. */
+export declare interface VSchemaTable {
+  column_vindexes?: ColumnVindex[]
+  auto_increment?: { column: string, sequence: string }
+  type?: 'reference'
+}
+/** A Vitess keyspace VSchema document. */
+export declare interface VSchema {
+  sharded: boolean
+  vindexes: Record<string, { type: string }>
+  tables: Record<string, VSchemaTable>
+}
+/** Why a table ended up sharded the way it did, for the CLI report. */
+export declare interface ShardingDecision {
+  table: string
+  column: string | null
+  vindex: VindexType | null
+  reason: 'explicit' | 'co-located with parent' | 'root entity' | 'reference table'
+  parent?: string
+  warning?: string
+}
+export declare interface VSchemaResult {
+  vschema: VSchema
+  decisions: ShardingDecision[]
+}