@simplysm/orm-common 14.0.4 → 14.0.6

package/README.md

@@ -1,135 +1,163 @@
 # @simplysm/orm-common
 
-Database-independent ORM providing schema builders, a type-safe query builder, an expression DSL, and multi-dialect support (MySQL, MSSQL, PostgreSQL).
+Platform-neutral ORM module for the Simplysm framework. Provides type-safe query building, schema definition, expression building, and DDL generation for MySQL, MSSQL, and PostgreSQL.
 
 ## Installation
 
 ```bash
 npm install @simplysm/orm-common
+# or
+pnpm add @simplysm/orm-common
 ```
 
-## API Reference
-
-| Category | Document | Key Exports |
-|---|---|---|
-| Core | [docs/core.md](docs/core.md) | `defineDbContext`, `createDbContext`, `DbContextDef`, `DbContextInstance`, `DbContextBase`, `DbContextStatus`, `DbContextConnectionMethods`, `DbContextDdlMethods`, `DbTransactionError`, `DbErrorCode` |
-| Queryable | [docs/queryable.md](docs/queryable.md) | `Queryable`, `QueryableRecord`, `QueryableWriteRecord`, `NullableQueryableRecord`, `getMatchedPrimaryKeys`, `Executable`, `executable`, `ParsedSearchQuery`, `parseSearchQuery` |
-| Expression | [docs/expression.md](docs/expression.md) | `expr`, `SwitchExprBuilder`, `ExprUnit`, `WhereExprUnit`, `ExprInput` |
-| Schema Builders | [docs/schema-builders.md](docs/schema-builders.md) | `Table`, `TableBuilder`, `View`, `ViewBuilder`, `Procedure`, `ProcedureBuilder`, `ColumnBuilder`, `createColumnFactory`, `IndexBuilder`, `createIndexFactory`, relation builders, type utilities |
-| Query Builder | [docs/query-builder.md](docs/query-builder.md) | `createQueryBuilder`, `QueryBuilderBase`, `ExprRendererBase`, `MysqlQueryBuilder`, `MssqlQueryBuilder`, `PostgresqlQueryBuilder` + renderers |
-| Types | [docs/types.md](docs/types.md) | `Dialect`, `IsolationLevel`, `DataRecord`, `DbContextExecutor`, `ResultMeta`, `Migration`, `QueryBuildResult`, `ColumnMeta`, `DataType`, column primitives, QueryDef types, Expr types, `parseQueryResult`, `_Migration` |
-
-## Quick Start
-
-### Define Schema
+## API Overview
+
+### Core
+
+| Export | Type | Description |
+|--------|------|-------------|
+| [`defineDbContext`](./docs/core.md#definedbcontext) | Function | Create a DbContext definition (blueprint) with tables, views, procedures, and migrations |
+| [`createDbContext`](./docs/core.md#createdbcontext) | Function | Create a DbContext instance from a definition and executor |
+| [`DbTransactionError`](./docs/core.md#dbtransactionerror) | Class | Standardized database transaction error with DBMS-independent error codes |
+| [`DbErrorCode`](./docs/core.md#dberrorcode) | Enum | Transaction error codes |
+| [`_Migration`](./docs/core.md#_migration) | Constant | System migration table definition (TableBuilder) |
+
+### Queryable / Executable
+
+| Export | Type | Description |
+|--------|------|-------------|
+| [`Queryable`](./docs/queryable.md#queryable) | Class | Fluent query builder for SELECT, INSERT, UPDATE, DELETE, UPSERT |
+| [`queryable`](./docs/queryable.md#queryable-factory) | Function | Factory to create Queryable accessors for tables/views |
+| [`Executable`](./docs/queryable.md#executable) | Class | Stored procedure execution wrapper |
+| [`executable`](./docs/queryable.md#executable-factory) | Function | Factory to create Executable accessors for procedures |
+| [`parseSearchQuery`](./docs/queryable.md#parsesearchquery) | Function | Parse search query string into SQL LIKE patterns |
+| [`ParsedSearchQuery`](./docs/queryable.md#parsedsearchquery) | Interface | Parsed search query result |
+| [`getMatchedPrimaryKeys`](./docs/queryable.md#getmatchedprimarykeys) | Function | Match FK columns with target table PK columns |
+| [`QueryableRecord`](./docs/queryable.md#queryablerecord) | Type | Maps DataRecord fields to ExprUnit proxies |
+| [`QueryableWriteRecord`](./docs/queryable.md#queryablewriterecord) | Type | Maps DataRecord fields to ExprInput for writes |
+| [`NullableQueryableRecord`](./docs/queryable.md#nullablequeryablerecord) | Type | QueryableRecord with nullable primitives (for LEFT JOIN) |
+| [`UnwrapQueryableRecord`](./docs/queryable.md#unwrapqueryablerecord) | Type | Reverse-map QueryableRecord to DataRecord |
+| [`PathProxy`](./docs/queryable.md#pathproxy) | Type | Type-safe path proxy for `include()` |
+
+### Expression Builder
+
+| Export | Type | Description |
+|--------|------|-------------|
+| [`expr`](./docs/expression.md#expr-object) | Object | Dialect-independent SQL expression builder (100+ methods) |
+| [`ExprUnit`](./docs/expression.md#exprunit) | Class | Type-safe expression wrapper |
+| [`WhereExprUnit`](./docs/expression.md#whereexprunit) | Class | WHERE clause expression wrapper |
+| [`ExprInput`](./docs/expression.md#exprinput) | Type | Union of ExprUnit or literal values |
+| [`SwitchExprBuilder`](./docs/expression.md#switchexprbuilder) | Interface | CASE WHEN builder (fluent API) |
+
+### Schema Builders
+
+| Export | Type | Description |
+|--------|------|-------------|
+| [`Table`](./docs/schema-builders.md#table-function) | Function | Create a TableBuilder |
+| [`TableBuilder`](./docs/schema-builders.md#tablebuilder) | Class | Fluent API for table definitions |
+| [`View`](./docs/schema-builders.md#view-function) | Function | Create a ViewBuilder |
+| [`ViewBuilder`](./docs/schema-builders.md#viewbuilder) | Class | Fluent API for view definitions |
+| [`Procedure`](./docs/schema-builders.md#procedure-function) | Function | Create a ProcedureBuilder |
+| [`ProcedureBuilder`](./docs/schema-builders.md#procedurebuilder) | Class | Fluent API for stored procedure definitions |
+| [`ColumnBuilder`](./docs/schema-builders.md#columnbuilder) | Class | Column definition builder |
+| [`createColumnFactory`](./docs/schema-builders.md#createcolumnfactory) | Function | Column type factory |
+| [`IndexBuilder`](./docs/schema-builders.md#indexbuilder) | Class | Index definition builder |
+| [`createIndexFactory`](./docs/schema-builders.md#createindexfactory) | Function | Index factory |
+| [`ForeignKeyBuilder`](./docs/schema-builders.md#foreignkeybuilder) | Class | FK relation builder (N:1) |
+| [`ForeignKeyTargetBuilder`](./docs/schema-builders.md#foreignkeytargetbuilder) | Class | FK reverse-reference builder (1:N/1:1) |
+| [`RelationKeyBuilder`](./docs/schema-builders.md#relationkeybuilder) | Class | Logical relation builder (no DB FK) |
+| [`RelationKeyTargetBuilder`](./docs/schema-builders.md#relationkeytargetbuilder) | Class | Logical reverse-reference builder |
+| [`createRelationFactory`](./docs/schema-builders.md#createrelationfactory) | Function | Relation factory |
+
+### Query Builder & Result Parsing
+
+| Export | Type | Description |
+|--------|------|-------------|
+| [`createQueryBuilder`](./docs/query-builder.md#createquerybuilder) | Function | Create a dialect-specific QueryBuilder |
+| [`QueryBuilderBase`](./docs/query-builder.md#querybuilderbase) | Abstract Class | Base for QueryDef to SQL rendering |
+| [`MysqlQueryBuilder`](./docs/query-builder.md#dialect-specific-query-builders) | Class | MySQL query builder |
+| [`MssqlQueryBuilder`](./docs/query-builder.md#dialect-specific-query-builders) | Class | MSSQL query builder |
+| [`PostgresqlQueryBuilder`](./docs/query-builder.md#dialect-specific-query-builders) | Class | PostgreSQL query builder |
+| [`ExprRendererBase`](./docs/query-builder.md#exprrendererbase) | Abstract Class | Base for Expr to SQL rendering |
+| [`MysqlExprRenderer`](./docs/query-builder.md#dialect-specific-expression-renderers) | Class | MySQL expression renderer |
+| [`MssqlExprRenderer`](./docs/query-builder.md#dialect-specific-expression-renderers) | Class | MSSQL expression renderer |
+| [`PostgresqlExprRenderer`](./docs/query-builder.md#dialect-specific-expression-renderers) | Class | PostgreSQL expression renderer |
+| [`parseQueryResult`](./docs/query-builder.md#parsequeryresult) | Function | Parse raw DB results into typed objects |
+
+### Types
+
+See [Types documentation](./docs/types.md) for all type exports including:
+- Database: `Dialect`, `dialects`, `IsolationLevel`, `DataRecord`, `DbContextExecutor`, `ResultMeta`, `Migration`, `QueryBuildResult`
+- DbContext: `DbContextDef`, `DbContextBase`, `DbContextStatus`, `DbContextInstance`, `DbContextConnectionMethods`, `DbContextDdlMethods`
+- Column: `DataType`, `ColumnPrimitive`, `ColumnPrimitiveStr`, `ColumnPrimitiveMap`, `ColumnMeta`, `dataTypeStrToColumnPrimitiveStr`, `inferColumnPrimitiveStr`, `InferColumnPrimitiveFromDataType`
+- Column Builder: `ColumnBuilderRecord`, `InferColumns`, `InferColumnExprs`, `InferInsertColumns`, `InferUpdateColumns`, `RequiredInsertKeys`, `OptionalInsertKeys`, `DataToColumnBuilderRecord`
+- Relation: `RelationBuilderRecord`, `InferDeepRelations`, `ExtractRelationTarget`, `ExtractRelationTargetResult`
+- Expression: `Expr` (50+ variants), `WhereExpr`, `DateUnit`, `WinFn`, `WinSpec`, all `Expr*` interfaces
+- QueryDef: `QueryDef` (30+ variants), `QueryDefObjectName`, `DDL_TYPES`, `DdlType`, all `*QueryDef` interfaces
+
+## Usage Examples
+
+### Define Schema and DbContext
 
 ```typescript
-import { Table, defineDbContext, expr } from "@simplysm/orm-common";
+import { Table, defineDbContext, createDbContext, expr } from "@simplysm/orm-common";
 
-// Define tables
 const User = Table("User")
   .database("mydb")
   .columns((c) => ({
     id: c.bigint().autoIncrement(),
     name: c.varchar(100),
     email: c.varchar(200).nullable(),
-    status: c.varchar(20).default("active"),
-    createdAt: c.datetime(),
-  }))
-  .primaryKey("id")
-  .indexes((i) => [i.index("email").unique()]);
-
-const Post = Table("Post")
-  .database("mydb")
-  .columns((c) => ({
-    id: c.bigint().autoIncrement(),
-    authorId: c.bigint(),
-    title: c.varchar(200),
-    content: c.text(),
+    companyId: c.bigint(),
   }))
   .primaryKey("id")
+  .indexes((i) => [i.index("email").unique()])
   .relations((r) => ({
-    author: r.foreignKey(["authorId"], () => User),
+    company: r.foreignKey(["companyId"], () => Company),
+    posts: r.foreignKeyTarget(() => Post, "author"),
   }));
 
-// Define DbContext
-const MyDb = defineDbContext({
-  tables: { user: User, post: Post },
-  migrations: [
-    {
-      name: "20260105_001_init",
-      up: async (db) => {
-        await db.createTable(User);
-        await db.createTable(Post);
-      },
-    },
-  ],
-});
+const MyDb = defineDbContext({ tables: { user: User, post: Post, company: Company } });
+const db = createDbContext(MyDb, executor, { database: "mydb" });
 ```
 
 ### Query Data
 
 ```typescript
-// Assume db is a DbContextInstance created via createDbContext()
-
-// SELECT with WHERE
-const activeUsers = await db.user()
-  .where((u) => [expr.eq(u.status, "active")])
-  .orderBy((u) => u.name)
-  .execute();
-
-// JOIN
-const postsWithAuthor = await db.post()
-  .include((p) => p.author)
-  .execute();
-
-// Aggregate
-const userPostCount = await db.user()
-  .select((u) => ({
-    name: u.name,
-    postCount: expr.count(),
-  }))
-  .joinSingle("latestPost", (qr, u) =>
-    qr.from(Post).where((p) => [expr.eq(p.authorId, u.id)])
-  )
-  .groupBy((u) => [u.name])
-  .execute();
-
-// INSERT
-await db.user().insert([
-  { name: "Gildong Hong", email: "hong@test.com", createdAt: DateTime.now() },
-]);
-
-// UPDATE
-await db.user()
-  .where((u) => [expr.eq(u.id, 1)])
-  .update(() => ({
-    name: expr.val("string", "New Name"),
-  }));
+await db.connect(async () => {
+  const users = await db.user()
+    .where((u) => [expr.eq(u.status, "active")])
+    .orderBy((u) => u.name)
+    .execute();
 
-// DELETE
-await db.user()
-  .where((u) => [expr.eq(u.status, "deleted")])
-  .delete();
-```
+  const posts = await db.post().include((p) => p.author).execute();
 
-### Search
+  await db.user().insert([{ name: "New User", companyId: 1 }]);
 
-```typescript
-// Text search with operators
-const results = await db.user()
-  .search((u) => [u.name, u.email], "+admin -deleted")
-  .execute();
+  await db.user()
+    .where((u) => [expr.eq(u.id, 1)])
+    .update(() => ({ name: expr.val("string", "Updated") }));
+});
 ```
 
-### Recursive CTE
+### Expression Builder
 
 ```typescript
-const hierarchy = await db.employee()
-  .where((e) => [expr.null(e.managerId)])
-  .recursive((cte) =>
-    cte.from(Employee)
-      .where((e) => [expr.eq(e.managerId, e.self[0].id)])
-  )
-  .execute();
+// Window functions
+db.order().select((o) => ({
+  ...o,
+  rowNum: expr.rowNumber({ partitionBy: [o.userId], orderBy: [[o.createdAt, "DESC"]] }),
+}));
+
+// CASE WHEN
+db.user().select((u) => ({
+  grade: expr.switch<string>()
+    .case(expr.gte(u.score, 90), "A")
+    .default("C"),
+}));
+
+// Raw SQL
+db.user().select((u) => ({
+  data: expr.raw("string")`JSON_EXTRACT(${u.metadata}, '$.email')`,
+}));
 ```

package/docs/core.md

@@ -4,32 +4,32 @@ DbContext definition, creation, and lifecycle management.
 
 ## defineDbContext
 
-Factory function that creates a `DbContextDef` blueprint from tables, views, procedures, and migrations. Automatically adds a `_migration` system table.
-
 ```typescript
-function defineDbContext<TTables, TViews, TProcedures>(config: {
+function defineDbContext<
+  TTables extends Record<string, TableBuilder<any, any>> = {},
+  TViews extends Record<string, ViewBuilder<any, any, any>> = {},
+  TProcedures extends Record<string, ProcedureBuilder<any, any>> = {},
+>(config: {
   tables?: TTables;
   views?: TViews;
   procedures?: TProcedures;
   migrations?: Migration[];
-}): DbContextDef<TTables & { _migration: typeof _Migration }, TViews, TProcedures>;
+}): DbContextDef<TTables & { _migration: typeof _Migration }, TViews, TProcedures>
 ```
 
-**Parameters:**
+Creates a DbContext definition (blueprint) containing schema metadata. Automatically adds the `_migration` system table. The definition itself has no runtime state.
 
 | Parameter | Type | Description |
-|---|---|---|
+|-----------|------|-------------|
 | `config.tables` | `Record<string, TableBuilder>` | Table definitions |
 | `config.views` | `Record<string, ViewBuilder>` | View definitions |
 | `config.procedures` | `Record<string, ProcedureBuilder>` | Procedure definitions |
 | `config.migrations` | `Migration[]` | Migration definitions |
 
-**Example:**
-
 ```typescript
 const MyDb = defineDbContext({
   tables: { user: User, post: Post },
-  views: { userSummary: UserSummary },
+  views: { activeUsers: ActiveUsersView },
   procedures: { getUserById: GetUserById },
   migrations: [
     { name: "20260101_001_init", up: async (db) => { await db.createTable(User); } },
@@ -39,161 +39,97 @@ const MyDb = defineDbContext({
 
 ## createDbContext
 
-Factory that creates a complete `DbContextInstance` from a `DbContextDef` and a `DbContextExecutor`. The returned instance includes queryable accessors for all tables/views, executable accessors for procedures, connection/transaction management, and DDL methods.
-
 ```typescript
 function createDbContext<TDef extends DbContextDef<any, any, any>>(
   def: TDef,
   executor: DbContextExecutor,
   opt: { database: string; schema?: string },
-): DbContextInstance<TDef>;
+): DbContextInstance<TDef>
 ```
 
-**Parameters:**
+Creates a full DbContext instance from a definition and executor. The returned object provides:
+
+- **Queryable accessors** for each table/view (e.g., `db.user()` returns a `Queryable`)
+- **Executable accessors** for each procedure (e.g., `db.getUserById()` returns an `Executable`)
+- **Connection management**: `connect()`, `connectWithoutTransaction()`, `transaction()`
+- **DDL methods**: `createTable()`, `dropTable()`, `addColumn()`, etc. (see `DbContextDdlMethods`)
+- **DDL QueryDef generators**: `getCreateTableQueryDef()`, etc.
+- **Initialize**: `initialize()` runs migrations
 
 | Parameter | Type | Description |
-|---|---|---|
-| `def` | `DbContextDef` | Definition created by `defineDbContext()` |
-| `executor` | `DbContextExecutor` | Query executor (e.g., `NodeDbContextExecutor`) |
+|-----------|------|-------------|
+| `def` | `DbContextDef` | Definition from `defineDbContext()` |
+| `executor` | `DbContextExecutor` | Query execution engine (e.g., `NodeDbContextExecutor`) |
 | `opt.database` | `string` | Database name |
-| `opt.schema` | `string` | Schema name (MSSQL: dbo, PostgreSQL: public) |
+| `opt.schema` | `string?` | Schema name (MSSQL: dbo, PostgreSQL: public) |
 
-**Example:**
+### Connection Methods
 
-```typescript
-const db = createDbContext(MyDb, executor, { database: "mydb" });
-
-await db.connect(async () => {
-  const users = await db.user().execute();
-});
-```
-
-## DbContextDef
-
-Blueprint interface created by `defineDbContext()`. Contains only schema metadata, no runtime state.
-
-```typescript
-interface DbContextDef<TTables, TViews, TProcedures> {
-  readonly meta: {
-    readonly tables: TTables;
-    readonly views: TViews;
-    readonly procedures: TProcedures;
-    readonly migrations: Migration[];
-  };
-}
-```
-
-## DbContextInstance
-
-Full DbContext instance type returned by `createDbContext()`. Extends `DbContextBase` with queryable accessors, DDL methods, and connection management.
-
-```typescript
-type DbContextInstance<TDef> = DbContextBase
-  & DbContextConnectionMethods
-  & DbContextDdlMethods
-  & { [K in keyof TDef["meta"]["tables"]]: () => Queryable<...> }
-  & { [K in keyof TDef["meta"]["views"]]: () => Queryable<...> }
-  & { [K in keyof TDef["meta"]["procedures"]]: () => Executable<...> }
-  & {
-    _migration: () => Queryable<{ code: string }, any>;
-    initialize(options?: { dbs?: string[]; force?: boolean }): Promise<void>;
-  };
-```
-
-## DbContextBase
-
-Core interface used internally by Queryable, Executable, and ViewBuilder.
-
-```typescript
-interface DbContextBase {
-  status: DbContextStatus;
-  readonly database: string | undefined;
-  readonly schema: string | undefined;
-  getNextAlias(): string;
-  resetAliasCounter(): void;
-  executeDefs<T = DataRecord>(defs: QueryDef[], resultMetas?: (ResultMeta | undefined)[]): Promise<T[][]>;
-  getQueryDefObjectName(tableOrView: TableBuilder | ViewBuilder): QueryDefObjectName;
-  switchFk(table: QueryDefObjectName, enabled: boolean): Promise<void>;
-}
-```
-
-## DbContextStatus
-
-```typescript
-type DbContextStatus = "ready" | "connect" | "transact";
-```
-
-| Value | Description |
-|---|---|
-| `"ready"` | Not connected |
-| `"connect"` | Connected, no active transaction |
-| `"transact"` | Inside a transaction |
-
-## DbContextConnectionMethods
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `connect` | `<R>(fn: () => Promise<R>, isolationLevel?: IsolationLevel) => Promise<R>` | Connect, begin transaction, execute callback, commit (auto-rollback on error) |
+| `connectWithoutTransaction` | `<R>(fn: () => Promise<R>) => Promise<R>` | Connect without transaction, execute callback, close |
+| `transaction` | `<R>(fn: () => Promise<R>, isolationLevel?: IsolationLevel) => Promise<R>` | Begin transaction within existing connection (for use inside `connectWithoutTransaction`) |
+
+### DDL Execution Methods
+
+| Method | Signature |
+|--------|-----------|
+| `createTable` | `(table: TableBuilder) => Promise<void>` |
+| `dropTable` | `(table: QueryDefObjectName) => Promise<void>` |
+| `renameTable` | `(table: QueryDefObjectName, newName: string) => Promise<void>` |
+| `createView` | `(view: ViewBuilder) => Promise<void>` |
+| `dropView` | `(view: QueryDefObjectName) => Promise<void>` |
+| `createProc` | `(procedure: ProcedureBuilder) => Promise<void>` |
+| `dropProc` | `(procedure: QueryDefObjectName) => Promise<void>` |
+| `addColumn` | `(table: QueryDefObjectName, columnName: string, column: ColumnBuilder) => Promise<void>` |
+| `dropColumn` | `(table: QueryDefObjectName, column: string) => Promise<void>` |
+| `modifyColumn` | `(table: QueryDefObjectName, columnName: string, column: ColumnBuilder) => Promise<void>` |
+| `renameColumn` | `(table: QueryDefObjectName, column: string, newName: string) => Promise<void>` |
+| `addPrimaryKey` | `(table: QueryDefObjectName, columns: string[]) => Promise<void>` |
+| `dropPrimaryKey` | `(table: QueryDefObjectName) => Promise<void>` |
+| `addForeignKey` | `(table: QueryDefObjectName, relationName: string, relationDef: ForeignKeyBuilder) => Promise<void>` |
+| `addIndex` | `(table: QueryDefObjectName, indexBuilder: IndexBuilder) => Promise<void>` |
+| `dropForeignKey` | `(table: QueryDefObjectName, relationName: string) => Promise<void>` |
+| `dropIndex` | `(table: QueryDefObjectName, columns: string[]) => Promise<void>` |
+| `clearSchema` | `(params: { database: string; schema?: string }) => Promise<void>` |
+| `schemaExists` | `(database: string, schema?: string) => Promise<boolean>` |
+| `truncate` | `(table: QueryDefObjectName) => Promise<void>` |
+| `switchFk` | `(table: QueryDefObjectName, enabled: boolean) => Promise<void>` |
+
+### DDL QueryDef Generators
+
+Each DDL method has a corresponding `get*QueryDef` method that returns a `QueryDef` without executing it. For example: `getCreateTableQueryDef(table)`, `getDropTableQueryDef(table)`, etc.
+
+### Initialize
 
 ```typescript
-interface DbContextConnectionMethods {
-  connect<TResult>(fn: () => Promise<TResult>, isolationLevel?: IsolationLevel): Promise<TResult>;
-  connectWithoutTransaction<TResult>(callback: () => Promise<TResult>): Promise<TResult>;
-  transaction<TResult>(fn: () => Promise<TResult>, isolationLevel?: IsolationLevel): Promise<TResult>;
-}
+async initialize(options?: { dbs?: string[]; force?: boolean }): Promise<void>
 ```
 
-| Method | Description |
-|---|---|
-| `connect(fn, isolationLevel?)` | Connect, begin transaction, execute `fn`, commit. Auto-rollback on error. |
-| `connectWithoutTransaction(fn)` | Connect and execute `fn` without a transaction. For DDL or read-only operations. |
-| `transaction(fn, isolationLevel?)` | Begin a nested transaction within an existing connection. Use inside `connectWithoutTransaction`. |
-
-## DbContextDdlMethods
-
-DDL execution methods and QueryDef generators on `DbContextInstance`.
-
-### Execution Methods
-
-| Method | Signature | Description |
-|---|---|---|
-| `createTable` | `(table: TableBuilder) => Promise<void>` | Create a table |
-| `dropTable` | `(table: QueryDefObjectName) => Promise<void>` | Drop a table |
-| `renameTable` | `(table: QueryDefObjectName, newName: string) => Promise<void>` | Rename a table |
-| `createView` | `(view: ViewBuilder) => Promise<void>` | Create a view |
-| `dropView` | `(view: QueryDefObjectName) => Promise<void>` | Drop a view |
-| `createProc` | `(procedure: ProcedureBuilder) => Promise<void>` | Create a stored procedure |
-| `dropProc` | `(procedure: QueryDefObjectName) => Promise<void>` | Drop a stored procedure |
-| `addColumn` | `(table, columnName, column: ColumnBuilder) => Promise<void>` | Add a column |
-| `dropColumn` | `(table, column: string) => Promise<void>` | Drop a column |
-| `modifyColumn` | `(table, columnName, column: ColumnBuilder) => Promise<void>` | Modify a column |
-| `renameColumn` | `(table, column, newName) => Promise<void>` | Rename a column |
-| `addPrimaryKey` | `(table, columns: string[]) => Promise<void>` | Add primary key |
-| `dropPrimaryKey` | `(table) => Promise<void>` | Drop primary key |
-| `addForeignKey` | `(table, relationName, relationDef: ForeignKeyBuilder) => Promise<void>` | Add foreign key |
-| `addIndex` | `(table, indexBuilder: IndexBuilder) => Promise<void>` | Add index |
-| `dropForeignKey` | `(table, relationName) => Promise<void>` | Drop foreign key |
-| `dropIndex` | `(table, columns: string[]) => Promise<void>` | Drop index |
-| `clearSchema` | `(params: { database; schema? }) => Promise<void>` | Clear all objects in schema |
-| `schemaExists` | `(database, schema?) => Promise<boolean>` | Check if schema exists |
-| `truncate` | `(table) => Promise<void>` | Truncate table |
-| `switchFk` | `(table, enabled: boolean) => Promise<void>` | Enable/disable FK constraints |
-
-### QueryDef Generator Methods
-
-Each DDL execution method has a corresponding `get*QueryDef` method (e.g., `getCreateTableQueryDef`, `getDropTableQueryDef`) that returns a `QueryDef` without executing it. These are useful for building migration scripts or batching DDL operations.
+Runs pending migrations. If `force` is true, drops and recreates the schema.
 
 ## DbTransactionError
 
-Standardized transaction error that wraps DBMS-native errors with a `DbErrorCode`.
-
 ```typescript
 class DbTransactionError extends Error {
   readonly name = "DbTransactionError";
   constructor(
-    readonly code: DbErrorCode,
+    public readonly code: DbErrorCode,
     message: string,
-    readonly originalError?: unknown,
-  );
+    public readonly originalError?: unknown,
+  )
 }
 ```
 
+Wraps DBMS-native transaction errors into standardized error codes.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `code` | `DbErrorCode` | Standardized error code |
+| `message` | `string` | Error message |
+| `originalError` | `unknown?` | Original DBMS error (for debugging) |
+
 ## DbErrorCode
 
 ```typescript
@@ -204,3 +140,18 @@ enum DbErrorCode {
   LOCK_TIMEOUT = "LOCK_TIMEOUT",
 }
 ```
+
+| Value | Description |
+|-------|-------------|
+| `NO_ACTIVE_TRANSACTION` | No active transaction (e.g., rollback when no transaction) |
+| `TRANSACTION_ALREADY_STARTED` | Transaction already started |
+| `DEADLOCK` | Deadlock detected |
+| `LOCK_TIMEOUT` | Lock timeout exceeded |
+
+## _Migration
+
+```typescript
+const _Migration: TableBuilder<{ code: ColumnBuilder<string, ...> }, {}>
+```
+
+System migration tracking table. Automatically added to every DbContext via `defineDbContext()`. Has a single `code` column (VARCHAR(255)) as primary key, storing executed migration names.