sqlstack 3.4.0 → 3.6.0-dev.0

package/readme.md

@@ -16,6 +16,7 @@ Write real SQL next to your code, and use small, composable decorators to bind,
 - [Error Handling](#error-handling)
 - [Transactions](#transactions)
 - [Inline SQL](#inline-sql)
+- [Choosing the Database at Call Time](#choosing-the-database-at-call-time)
 - [Advanced: Direct Database Access](#advanced-direct-database-access)
 - [Database Support](#database-support)
 - [Philosophy](#philosophy)
@@ -78,15 +79,16 @@ Load this file once during app startup.
 
 ```ts
 // src/users/index.ts
-import { QueryBinder, Query, SqlStackError } from "sqlstack";
+import { QueryBinder, Query, run } from "sqlstack";
 
 @QueryBinder() // looks for .sql files in the same folder by default
 export class UsersRepository {
   @Query()
   async findByEmail(params: { email: string }): Promise<User[]> {
-    // Implementation bodies are never called; this method exists
-    // only to define the TypeScript signature for @Query.
-    throw new SqlStackError("replaced by @Query");
+    // run() executes this method's SQL (findByEmail.sql) with the method's
+    // arguments; the result type is inferred from the declared return type.
+    // Code before/after `await run()` runs normally (logging, try/catch, ...).
+    return run();
   }
 }
 ```
@@ -116,7 +118,7 @@ const users = await repo.findByEmail({ email: "alice@example.com" });
 console.log(users); // User[]
 ```
 
-That's it! The `@Query` decorator intercepts the method, loads and executes the SQL, and returns results.
+That's it! The `@Query` decorator wraps the method; the body's `return run()` loads and executes the SQL and returns the shaped results. (Older code whose body is a placeholder `throw` still works — the wrapper falls back to running the SQL — but `return run()` is the supported form.)
 
 You can then add more methods on the same repository that use sqlstack’s SQL helpers:
 
@@ -125,22 +127,22 @@ You can then add more methods on the same repository that use sqlstack’s SQL h
 export class UsersRepository {
   @Query()
   async findByEmail(params: { email: string }): Promise<User[]> {
-    throw new SqlStackError("replaced by @Query");
+    return run();
   }
 
   @Query()
   async updateProfile(params: { id: string; name?: string; status?: string }): Promise<WriteResult> {
-    throw new SqlStackError("replaced by @Query");
+    return run();
   }
 
   @Query()
   async createUser(params: { id: string; email: string; name?: string }): Promise<WriteResult> {
-    throw new SqlStackError("replaced by @Query");
+    return run();
   }
 
   @Query()
   async search(filters: { name?: string; status?: string }): Promise<User[]> {
-    throw new SqlStackError("replaced by @Query");
+    return run();
   }
 }
 ```
@@ -407,13 +409,13 @@ SqlStackDB.register('sqlite-existing', createSqliteDb(sqlite));
 Use `@QueryBinder({ db: "name" })` to set a default database for all methods in a class:
 
 ```ts
-import { QueryBinder, Query, SqlStackError } from "sqlstack";
+import { QueryBinder, Query, run } from "sqlstack";
 
 @QueryBinder({ db: "analytics" }) // all methods use "analytics"
 export class ReportsRepo {
   @Query()
   async topPages(_a: { since: string }): Promise<Row[]> {
-    throw new SqlStackError("replaced");
+    return run();
   }
 }
 ```
@@ -427,12 +429,12 @@ Use `@Query({ db: "name" })` to override the class default for a specific method
 export class MixedRepo {
   @Query() // uses "primary"
   async dailySummary(_a: { date: string }): Promise<Row[]> {
-    throw new SqlStackError("replaced");
+    return run();
   }
 
   @Query({ db: "analytics" }) // override to use "analytics"
   async topPages(_a: { since: string }): Promise<Row[]> {
-    throw new SqlStackError("replaced");
+    return run();
   }
 }
 ```
@@ -514,7 +516,7 @@ No argument to `@Query()` → looks in the same folder as the class file:
 class UsersRepo {
   @Query()
   async findByEmail(_a: { email: string }): Promise<User[]> {
-    throw new Error();
+    return run();
   }
 }
 ```
@@ -560,14 +562,14 @@ Use decorators to add behavior to your methods. They compose freely and always e
 Provide default parameter values:
 
 ```ts
-import { QueryBinder, Defaults, Query, SqlStackError } from "sqlstack";
+import { QueryBinder, Defaults, Query, run } from "sqlstack";
 
 @QueryBinder()
 class UsersRepo {
   @Defaults({ status: "active", limit: 10 })
   @Query()
   async listUsers(_a: { status?: string; limit?: number }): Promise<User[]> {
-    throw new SqlStackError();
+    return run();
   }
 }
 ```
@@ -583,14 +585,14 @@ await repo.listUsers({ status: "inactive" }); // { status: "inactive", limit: 10
 Add pagination with `:offset` and `:limit` parameters. Pages are 1-based by default:
 
 ```ts
-import { QueryBinder, Page, Query, SqlStackError } from "sqlstack";
+import { QueryBinder, Page, Query, run } from "sqlstack";
 
 @QueryBinder()
 class UsersRepo {
   @Page(10) // limit = 10, pages 1-based
   @Query()
   async listUsers(params: { status?: string; page?: number }): Promise<User[]> {
-    throw new SqlStackError();
+    return run();
   }
 }
 ```
@@ -623,7 +625,7 @@ await repo.list(userId, { page: 2 });         // positional id + trailing option
 Shape single-query results without parameters:
 
 ```ts
-import { QueryBinder, Single, Only, Exist, None, Query, SqlStackError } from "sqlstack";
+import { QueryBinder, Single, Only, Exist, None, Query, run } from "sqlstack";
 
 @QueryBinder()
 class UsersRepo {
@@ -631,28 +633,28 @@ class UsersRepo {
   @Single
   @Query()
   async firstOrNull(_a: { email: string }): Promise<User | null> {
-    throw new SqlStackError();
+    return run();
   }
 
   // @Only → require exactly one row; throw if 0 or >1
   @Only
   @Query()
   async exactlyOne(_a: { id: string }): Promise<User> {
-    throw new SqlStackError();
+    return run();
   }
 
   // @Exist → require at least one row; return first row; throw if none
   @Exist
   @Query()
   async requireOne(_a: { email: string }): Promise<User> {
-    throw new SqlStackError();
+    return run();
   }
 
   // @None → require zero rows; return null; throw if any rows
   @None
   @Query()
   async ensureNone(_a: { status: string }): Promise<null> {
-    throw new SqlStackError();
+    return run();
   }
 }
 ```
@@ -670,7 +672,7 @@ Validate query results against a JSON Schema:
 
 ```ts
 import schema from "./user.row.schema.json" assert { type: "json" };
-import { QueryBinder, ValidateResult, Single, Query, SqlStackError } from "sqlstack";
+import { QueryBinder, ValidateResult, Single, Query, run } from "sqlstack";
 
 @QueryBinder()
 class UsersRepo {
@@ -678,7 +680,7 @@ class UsersRepo {
   @Single
   @Query()
   async findByEmail(_a: { email: string }): Promise<User | null> {
-    throw new SqlStackError();
+    return run();
   }
 }
 ```
@@ -735,7 +737,7 @@ class Repo {
     WHERE g.id = :id
     ORDER BY m.name, e.name
   ` })
-  async getGroup(_a: { id: string }): Promise<any | null> { throw new Error('replaced'); }
+  async getGroup(_a: { id: string }): Promise<any | null> { return run(); }
 }
 ```
 
@@ -806,13 +808,13 @@ Returns an array of rows, which can be shaped via decorators:
 class Repo {
   @Query()
   async allUsers(): Promise<User[]> {
-    throw new Error();
+    return run();
   }
 
   @Single
   @Query()
   async firstUser(): Promise<User | null> {
-    throw new Error();
+    return run();
   }
 }
 ```
@@ -867,16 +869,18 @@ This lets you start with very simple queries and incrementally adopt more comple
 
 ## Error Handling
 
-sqlstack provides a base error class and specific error types. Import and catch as needed:
+sqlstack throws; it does not return result objects. Its errors extend `SqlStackError` (with one historical exception, noted below). Import and catch as needed:
 
 ```ts
-import { SqlStackError } from "sqlstack";
+import { SqlStackError, DatabaseError } from "sqlstack";
 import { ExactlyOneRowError, NoRowsError, ValidationError } from "sqlstack/errors";
 
 try {
   const user = await repo.findByEmail({ email: "alice@example.com" });
 } catch (err) {
-  if (err instanceof ExactlyOneRowError) {
+  if (err instanceof DatabaseError) {
+    console.log("statement failed:", err.sql, err.code, err.cause);
+  } else if (err instanceof ExactlyOneRowError) {
     console.log("@Only: expected exactly one row, got a different number");
   } else if (err instanceof NoRowsError) {
     console.log("@Exist: expected at least one row, got none");
@@ -891,220 +895,165 @@ try {
 ```
 
 Available error classes:
-- `SqlStackError` — base class for all sqlstack errors
+- `SqlStackError` — base class for all sqlstack errors (also used for usage errors such as calling `run()` outside a `@Query` method)
+- `DatabaseError` — a statement failed. `.sql` holds the statement (with placeholders), `.cause` holds the original error (the driver's error, or the macro/binding/name-resolution error), and `.code` copies the cause's string driver code (`SQLITE_CONSTRAINT_UNIQUE`, `23505`, `ER_DUP_ENTRY`, ...) when present
 - `ExactlyOneRowError` — thrown by `@Only` when row count ≠ 1
 - `NoRowsError` — thrown by `@Exist` when no rows found
+- `RowsExistError` — thrown by `@None` when rows exist
+- `ExpectedRowsError` — a shape decorator was applied to a statement that produced no result set
 - `ValidationError` — thrown by `@ValidateResult` on schema mismatch
-- Database driver errors — pass through unchanged
+
+**The error contract.** Driver errors never pass through raw: they are always wrapped in `DatabaseError` with the original in `.cause`. Parameter-binding errors such as `Missing named parameter :email` are a `DatabaseError` with the original in `.cause` in every `run(...)` form, including the zero-argument `run()`. For the `run(...)` forms that take arguments (`run(query)`, `run(db, query)`, `run(db, params)`), *every* failure before result shaping — macro errors from an `` sql`...` `` fragment, parameter-binding errors, an unknown database name — is a `DatabaseError` with the original in `.cause`; invalid arguments are `SqlStackError`. Errors thrown by your own code — the method body or a `@Transform` function — propagate unchanged.
 
 ---
 
 ## Transactions
 
-Run multiple queries as a single atomic unit. If any query fails, all changes are rolled back automatically.
-
-### Basic Usage with `@transaction` Decorator
-
-Mark a method with `@transaction` to wrap it in a transaction:
+`@transaction` on a method means *everything this method touches is transactional*. You don't name a database: each repository already knows its own (`@QueryBinder({ db })`, the stack default, or the active family binding).
 
 ```ts
-import { transaction, currentTransaction } from "sqlstack";
+import { transaction } from "sqlstack";
 
-class UserService {
+class SpawnService {
   @transaction
-  async createUserWithProfile(data: { email: string; name: string }) {
-    await this.usersRepo.insert(data);
-    await this.profilesRepo.insert({ userId: data.id, bio: "" });
+  async commitSpawnIdentity(input: Input): Promise<Spawned | SpawnRejected> {
+    const root = await this.agents.ensureRoot({ conversationId: input.rootConversationId });
+    await this.agents.insertRunning({ agentId: input.agentId, parentId: root.id });
+
+    if (input.group && !(await this.groups.canJoin(input.group.id))) {
+      transaction.rollback();                                     // mark; nothing is sent yet
+      await this.agents.recordRejection({ agentId: input.agentId }); // still runs, still visible here
+      return { rejected: true };                                  // returns normally; everything rolls back
+    }
+
+    transaction.afterCommit(() => this.publishSpawned(input));    // runs only if the commit lands
+    return { agentId: input.agentId, rootId: root.id };           // return → commit
   }
 }
-
-// If either insert fails, both are rolled back
-await new UserService().createUserWithProfile({ email: "alice@example.com", name: "Alice" });
 ```
 
-Queries in `@Query` decorated methods automatically participate in the active transaction:
+Queries from `@Query` methods take part automatically. So do `run(sql...)` and `run("name", ...)`:
 
 ```ts
 @QueryBinder()
 class UsersRepo {
   @Query({ sql: 'INSERT INTO users (email, name) VALUES (:email, :name)' })
   async insert(data: { email: string; name: string }): Promise<WriteResult> {
-    throw new Error("replaced by @Query");
-  }
-}
-
-@QueryBinder()
-class ProfilesRepo {
-  @Query({ sql: 'INSERT INTO profiles (user_id, bio) VALUES (:userId, :bio)' })
-  async insert(data: { userId: string; bio: string }): Promise<WriteResult> {
-    throw new Error("replaced by @Query");
+    return run();
   }
 }
 ```
 
-### Commit and Rollback
+### Rules
+
+1. **Opened on first touch.** Nothing is opened when the method starts. The first query that resolves to a database with no open transaction in this flow opens one on that database: `BEGIN IMMEDIATE` on SQLite, `BEGIN` on a pooled Postgres client, `START TRANSACTION` on a pooled MySQL connection. A `@transaction` method that issues no SQL opens nothing.
+2. **Return commits, throw rolls back.** If the method returns normally, every transaction the scope opened is committed, in the order they were opened. If it throws, they are all rolled back and the error is rethrown.
+3. **`transaction.rollback()` is a mark, not a throw.** The call is synchronous and marks the innermost scope. SQL after it still runs inside the open transaction and is visible to the method. When the method returns, the scope rolls back instead of committing, and the return value still reaches the caller. Pass a database name or a `Database` handle (`transaction.rollback("analytics")`, `transaction.rollback(analyticsDb)`) to mark only that database. The target must have a transaction open in the current flow; otherwise `SqlStackError` is thrown.
+4. **`await transaction.restart()`.** This rolls back everything the scope has done so far, right away, and fresh transactions open on the next touch. Use it when the work after a failure must persist, such as writing a rejection record after a failed statement. It is the only portable form after a *failed statement* on Postgres, where the whole transaction is aborted until `ROLLBACK`. `afterCommit` hooks registered before the restart are dropped; `afterSettled` hooks stay.
+5. **Nesting uses savepoints.** A `@transaction` method called from inside another one is a piece of the outer one. On entry it issues `SAVEPOINT` on every transaction already open, and a transaction first opened inside it gets its savepoint right after `BEGIN`. An inner `rollback()`, or an inner throw, becomes `ROLLBACK TO SAVEPOINT` and the outer scope continues. Inner success becomes `RELEASE SAVEPOINT`, and the inner `afterCommit` hooks move up to the outermost scope. The savepoint statements are the same on SQLite, Postgres and MySQL.
+6. **Hooks.** `transaction.afterCommit(fn)` runs `fn` after the outermost scope commits, in registration order; it is dropped on rollback or on any mark. `transaction.afterSettled(fn)` runs after the outermost scope finishes either way, which makes it the place for cleanup. Hooks run *outside* the scope, so a hook that is itself `@transaction` opens a fresh, independent scope. A hook that throws makes the method's promise reject after all hooks have run; the commit has already happened by then.
+7. **Two databases are coordinated, not atomic.** Both commit at return and both roll back on a mark. A failure between the two commits, however, leaves them inconsistent. When a scope opens its second database it emits one `sqlstack.transaction.multi_database` event with the database names, so these cases are visible. Cross-database side effects that must not be half-applied belong in `afterCommit`.
+8. **SQLite queues.** Independent async flows that open a transaction on the same SQLite connection wait their turn instead of failing with "cannot start a transaction within a transaction". Postgres and MySQL get isolation from the pool and need no queue.
 
-**Commit on success:** If the transaction method returns normally, all queries are committed.
+`transaction.rollback`, `transaction.restart`, `transaction.afterCommit` and `transaction.afterSettled` throw `SqlStackError` when called outside a `@transaction` method.
 
-**Rollback on error:** If the method throws, all queries are rolled back and the error is rethrown:
+### Nested Scopes
 
 ```ts
 class UserService {
   @transaction
-  async createUser() {
-    await this.usersRepo.insert({ email: "bob@example.com" });
-    throw new Error("something went wrong");
-    // Rollback happens here; insert is undone
+  async createUser(email: string) {
+    await this.usersRepo.insert({ email });
+    await this.createDefaultProfile();          // SAVEPOINT … RELEASE SAVEPOINT
+    await this.usersRepo.markReady({ email });
   }
-}
-
-await new UserService().createUser(); // throws "something went wrong"
-```
-
-### Lazy Transactions
-
-By default, transactions use **lazy mode**: they don't start (no `BEGIN`) until the first query runs. This avoids overhead if the method never queries:
-
-```ts
-@transaction({ lazy: true })  // default behavior
-async readOnlyOperation() {
-  // No database transaction started yet
-  const data = await this.repo.fetch();
-
-  // Process data without holding a transaction
-  return processData(data);
-}
-```
-
-Disable lazy mode with `lazy: false` to start the transaction immediately:
-
-```ts
-@transaction({ lazy: false })
-async mustStartTransaction() {
-  // BEGIN is executed immediately, even before first query
-}
-```
 
-### Accessing the Current Transaction
-
-Use `currentTransaction()` to access the active transaction context within a method:
-
-```ts
-class UserService {
   @transaction
-  async createUserWithValidation(data: { email: string }) {
-    const user = await this.usersRepo.insert(data);
-
-    // Validate user was inserted
-    const check = await this.usersRepo.findById(user.id);
-    if (!check) {
-      // Mark transaction for rollback and throw a custom error
-      currentTransaction()?.rollbackOnly(new Error("User not found after insert"));
-      return; // exit gracefully
-    }
-
-    return user;
+  async createDefaultProfile() {
+    await this.profilesRepo.insert({ name: "Default Profile" });
+    if (await this.profilesRepo.isDuplicate()) transaction.rollback(); // undoes only this piece
   }
 }
 ```
 
-### Rollback with Custom Error
-
-Use `rollbackOnly(error)` to mark a transaction for rollback while specifying which error should be thrown:
+### Restart After a Failed Statement
 
 ```ts
-class UserService {
+class JoinService {
   @transaction
-  async createUser(email: string) {
+  async join(input: JoinInput) {
     try {
-      await this.usersRepo.insert({ email });
-    } catch (dbError) {
-      // Roll back and throw a sanitized error
-      currentTransaction()?.rollbackOnly(new Error("Failed to create user"));
-      return; // rethrow happens automatically
+      await this.members.insert(input);
+    } catch (err) {
+      await transaction.restart();                     // the failed work is gone
+      await this.rejections.insert({ id: input.id });  // this persists
+      return { joined: false };
     }
+    return { joined: true };
   }
 }
 ```
 
-You can also throw `RollbackTransactionError` to explicitly signal rollback while optionally wrapping another error:
+### Observing Multi-Database Scopes
 
 ```ts
-import { RollbackTransactionError } from "sqlstack";
-
-class UserService {
-  @transaction
-  async createUser(email: string) {
-    await this.usersRepo.insert({ email });
+import { onTransactionEvent } from "sqlstack";
 
-    // Roll back and throw the wrapped error
-    throw new RollbackTransactionError("Transaction cancelled", new Error("User rejected"));
-    // Caller sees: Error("User rejected")
-  }
-}
+const unsubscribe = onTransactionEvent((event) => {
+  // { type: "sqlstack.transaction.multi_database", databases: ["primary", "analytics"] }
+  logger.warn(event.type, { databases: event.databases });
+});
 ```
 
-### Using `withTransaction()` Function
+### Name-Based Transactions (`@transaction({ db })`, `withTransaction`)
 
-For programmatic control, use the `withTransaction()` function:
+The name-based form from earlier versions still works as it always has. It opens a transaction on one named database only, and queries on other databases run outside it:
 
 ```ts
-import { withTransaction } from "sqlstack";
+import { transaction, withTransaction, currentTransaction, RollbackTransactionError } from "sqlstack";
 
-const result = await withTransaction(async () => {
-  const user = await this.usersRepo.insert({ email: "charlie@example.com" });
-  await this.profilesRepo.insert({ userId: user.id });
-  return user;
-}, { db: "primary" });
-```
-
-### Multiple Databases
-
-Transactions are per-database. Run transactions on different databases simultaneously:
-
-```ts
 class MultiDbService {
-  @transaction({ db: "primary" })
+  @transaction({ db: "primary" })                 // lazy: BEGIN on the first query to "primary"
   async insertUser() {
     await this.usersRepo.insert({ email: "dave@example.com" });
   }
 
-  @transaction({ db: "analytics" })
-  async logAnalytics() {
-    await this.analyticsRepo.insert({ event: "user_created" });
-  }
+  @transaction({ db: "primary", lazy: false })    // BEGIN immediately
+  async mustStart() {}
 }
 
-// Both transactions run independently
-await Promise.all([
-  new MultiDbService().insertUser(),
-  new MultiDbService().logAnalytics(),
-]);
+const result = await withTransaction(async () => {
+  const user = await this.usersRepo.insert({ email: "charlie@example.com" });
+  await this.profilesRepo.insert({ userId: user.id });
+  return user;
+}, { db: "primary" });
 ```
 
-### Nested Transactions (Savepoints)
+On SQLite this form issues a plain `BEGIN` and doesn't queue. `@transaction({ lazy: false })` with no `db` opens eagerly on the default database.
 
-Multiple `@transaction` decorators stack safely. Only the outermost transaction commits/rolls back:
+`currentTransaction()?.rollbackOnly(error?)` marks the active transaction for rollback *and throws* at exit: it throws `error` if one was given, otherwise `RollbackTransactionError`. Throwing `new RollbackTransactionError(message, cause)` rolls back and rethrows `cause`. Both work inside a scope-based `@transaction` too:
 
 ```ts
 class UserService {
   @transaction
   async createUser(email: string) {
-    await this.usersRepo.insert({ email });
-    await this.createDefaultProfile();
+    try {
+      await this.usersRepo.insert({ email });
+    } catch {
+      currentTransaction()?.rollbackOnly(new Error("Failed to create user")); // caller sees this error
+      return;
+    }
   }
 
-  @transaction  // nested decorator
-  async createDefaultProfile() {
-    await this.profilesRepo.insert({ name: "Default Profile" });
+  @transaction
+  async cancel(email: string) {
+    await this.usersRepo.insert({ email });
+    throw new RollbackTransactionError("Transaction cancelled", new Error("User rejected")); // caller sees "User rejected"
   }
 }
-
-// Outer transaction commits both inserts
-await new UserService().createUser("eve@example.com");
 ```
 
-All queries use the same transaction context. If the inner method throws, the outer transaction rolls back everything.
+When code is mixed, a name-based transaction that is open in the flow is joined by queries on that database. The name-based transaction keeps its own commit and rollback rules: a scope's `rollback()` mark or `restart()` doesn't apply to it.
 
 ### Connection Pooling and Resource Cleanup
 
@@ -1184,7 +1133,7 @@ async createUser() {
 
 ## Inline SQL
 
-For simple or dynamic queries, use `@Query({ sql: "..." })` with inline SQL:
+For simple queries, use `@Query({ sql: "..." })` with inline SQL:
 
 ```ts
 @QueryBinder()
@@ -1195,18 +1144,99 @@ class Repo {
     WHERE email = :email
   ` })
   async findByEmail(_a: { email: string }): Promise<User[]> {
-    throw new Error("replaced");
+    return run();
   }
 }
 ```
 
 sqlstack applies the same parameter binding and result shaping as file-based SQL.
 
+For SQL built in code, pass an `` sql`...` `` fragment to `run`. The fragment replaces the method's SQL file; its `${}` values are the bound parameters (the method's own arguments are not auto-bound). The database still comes from `@Query({ db })` / `@QueryBinder({ db })` / the default, the active transaction is joined, and the shape/transform/validation decorators still apply:
+
+```ts
+import { QueryBinder, Query, Single, run, sql } from "sqlstack";
+
+@QueryBinder()
+class Repo {
+  @Single
+  @Query()
+  async findByEmail(email: string): Promise<User | null> {
+    return run(sql`SELECT id, email, name FROM users WHERE email = ${email}`);
+  }
+}
+```
+
+SQL is never accepted as a plain string — always build it with the `sql` tag, and pass the fragment itself (not its `.toSQL()` output) so `run` can bind it for the target dialect.
+
+> **Deprecated:** a `@Query` body that *returns* an `` sql`...` `` fragment (instead of `` return run(sql`...`) ``) still executes, but only type-checks with an `as any`-style cast. It emits a one-time `DeprecationWarning` (`SQLSTACK_FRAGMENT_BODY`) per method and will be removed in the next major version.
+
+---
+
+## Choosing the Database at Call Time
+
+When the database handle is only known at runtime (per-tenant or per-thread databases, a handle passed into a repository method), pass it to `run` as the first argument. The handle is anything with `query(sql, params)` — a sqlstack `Database` from `createPgDb` / `createMysqlDb` / `createSqliteDb`, or your application's own wrapper — or the name of a registered database. sqlstack never opens databases by path.
+
+### `run(db, query)` — anywhere
+
+```ts
+import { run, sql } from "sqlstack";
+
+const rows = await run<ImportRow[]>(accountsDb, sql`
+  SELECT 1 AS present FROM data_root_imports
+  WHERE data_root = ${dataRoot} AND kind = ${kind}
+  LIMIT 1
+`);
+
+await run(accountsDb, sql`INSERT INTO data_root_imports :insert(${{ data_root: dataRoot, kind }})`);
+```
+
+Outside a `@Query` method this returns the raw result: a rows array for statements that produce a result set, `{ rowsAffected, lastInsertId? }` otherwise. Without an explicit type argument the result is `unknown`, never `any`. Inside a `@Query` method, `` return run(db, sql`...`) `` runs the fragment on `db` and applies the method's shape/transform/validation decorators; the result type is inferred from the method's declared return type.
+
+### `run(db, params)` — inside a `@Query` method
+
+Runs the method's own SQL (its `.sql` file or inline `@Query({ sql })`) against `db`, binding `params` — an object for `:named` placeholders, an array for `:arg1, :arg2, ...`. In this form the method's raw arguments are **not** auto-bound; `params` is the whole binding input. `@Defaults`, `@Page`, shaping, transform, and validation still apply.
+
+```ts
+@QueryBinder()
+class AccountsRepo {
+  @Single
+  @Query() // AccountsRepo/findByEmail.sql: SELECT * FROM accounts WHERE email = :email
+  async findByEmail(db: Database, params: { email: string }): Promise<Account | null> {
+    return run(db, params);
+  }
+}
+```
+
+The SQL file is located through the same resolver as `run()` (under an active IoC environment that means the root's registered `SqlStack`). Calling `run(db, params)` outside a `@Query` method throws `SqlStackError` — there is no SQL to run.
+
+### The forms at a glance
+
+| Call | Where | SQL | Database | Binding |
+|---|---|---|---|---|
+| `run()` | `@Query` body | method's file / inline SQL | decorator context | method arguments |
+| `run(query)` | `@Query` body | the fragment | decorator context | fragment values |
+| `run(db, query)` | anywhere | the fragment | `db` | fragment values |
+| `run(db, params)` | `@Query` body | method's file / inline SQL | `db` | `params` only |
+
+Type rules (enforced by the overloads, and mirrored at runtime for untyped callers): SQL strings are rejected, `.toSQL()` output (`{ sql, params }`) is rejected, the first argument must be a handle or a name, and params must be an object or array. All forms follow the [error contract](#error-handling): failures surface as `DatabaseError` with the original error in `.cause`.
+
+### Dialects
+
+`run` binds fragments for the target database: `$1, $2, ...` for Postgres, `?` for MySQL and SQLite (including inside `:insert`, `:update`, `:filter`, and `:batch_insert`). The dialect comes from the handle's `dialect` property and defaults to `sqlite` when the handle has none. `fragment.toSQL()` itself is unchanged and always emits `?`.
+
+### Transactions
+
+A database passed to `run` joins an active transaction (from `@transaction` / `withTransaction`) that was opened **on that same database**: by name, or — for a handle — when it is the very `Database` object registered under the transaction's name. A handle that is not registered with sqlstack (for example an application-owned SQLite connection) never joins a sqlstack transaction; manage its transactions with your driver.
+
+### Inside `@Query`, all `run` calls belong to the method
+
+`run` finds the enclosing `@Query` invocation through async context. Any `run(...)` executed while a `@Query` method body is running — including inside helper functions the body awaits — is treated as that method's query and gets its shape/transform/validation decorators. Keep `run(db, query)` calls meant to return raw results out of `@Query` bodies.
+
 ---
 
 ## Advanced: Direct Database Access
 
-Every `Database` instance exposes the underlying driver via `.conn`, so you can drop down to raw queries when needed:
+For SQL that should stay typed and dialect-safe, prefer `` run(db, sql`...`) `` (see [Choosing the Database at Call Time](#choosing-the-database-at-call-time)). Every `Database` instance also exposes the underlying driver via `.conn`, so you can drop down to raw driver calls when needed:
 
 ```ts
 import { SqlStackDB } from 'sqlstack/registry';
@@ -1238,7 +1268,7 @@ More adapters are planned.
 
 ### Dialect Inference
 
-The placeholder style is inferred from the selected database. Override per-method with `@Query({ dialect: "pg" })` if needed.
+The placeholder style is inferred from the selected database. Override per-method with `@Query({ dialect: "postgres" })` if needed.
 
 ---