@sigitex/outlaw 1.0.0 → 1.2.0

package/README.md

@@ -1,9 +1,360 @@
 # Outlaw
 
-It's sqlite.
+A trigger-happy SQLite framework. Type-safe, schema-first, with automatic migrations.
 
-`bun add @sigitex/outlaw`
+```
+bun add @sigitex/outlaw
+```
 
-> **Note:** This package currently exports TypeScript sources directly. A TypeScript-compatible runtime or bundler (Bun, etc.) is required.
+Attempts to mirror Sqlite syntax *very* closely. Currently works with Bun and Cloudflare Functions.
 
-- TODO: conform to "adapts-to" stuff
+Define your schema in code, and Outlaw's [cowboy migrations](#cowboy-migrations) automatically diff and converge your database on startup.
+
+> **Note:** This package exports TypeScript sources directly. A TypeScript-compatible runtime or bundler (Bun, etc.) is required.
+
+## Quick Start
+
+```ts
+// 1. Define your schema
+const users = createTable("users", {
+  id: integer.primaryKey.autoincrement,
+  name: text.notNull,
+  email: text.notNull.unique,
+})
+
+const schema = createSchema({ users })
+
+// 2. Create a connection with auto-migration
+const bun = new BunConnection(new Database("app.db"))
+const connection = new CowboyConnection(bun, schema)
+
+// 3. Use the typed database API
+const db = createDatabase(connection, schema)
+
+await db.users.insert({ name: "Wyatt", email: "wyatt@earp.com" }).execute()
+
+const allUsers = await db.users.select("*").fetch()
+const user = await db.users.select("*").where("id", 1).first()
+```
+
+## Schema Definition
+
+### Tables
+
+Define tables with `createTable`. Each column uses a builder chain starting from a base type.
+
+```ts
+import { createTable, text, integer, real, blob } from "@sigitex/outlaw"
+
+const products = createTable("products", {
+  id: integer.primaryKey.autoincrement,
+  name: text.notNull,
+  description: text,               // nullable by default
+  price: real.notNull,
+  image: blob,
+  sku: text.notNull.unique,
+})
+```
+
+#### Column Types
+
+| Builder   | SQLite Type | TypeScript Type |
+|-----------|-------------|-----------------|
+| `text`    | TEXT        | `string`        |
+| `integer` | INTEGER     | `number`        |
+| `real`    | REAL        | `number`        |
+| `blob`    | BLOB        | `ArrayBuffer`   |
+
+#### Column Modifiers
+
+Modifiers are chained as properties or method calls:
+
+```ts
+text.notNull                          // NOT NULL
+integer.primaryKey                    // PRIMARY KEY
+integer.primaryKey.autoincrement      // PRIMARY KEY AUTOINCREMENT
+text.unique                           // UNIQUE
+text.default("'unknown'")             // DEFAULT 'unknown'
+text.check("length(name) > 0")       // CHECK constraint
+integer.foreignKey.references(other.id) // FOREIGN KEY
+```
+
+Each modifier can only be used once per column -- the type system removes it after use.
+
+#### Type Mappings
+
+Map SQLite storage types to richer TypeScript types:
+
+```ts
+const events = createTable("events", {
+  id: integer.primaryKey.autoincrement,
+  active: integer.notNull.map.boolean,     // stored as 0/1, typed as boolean
+  createdAt: integer.notNull.map.timestamp, // stored as epoch ms, typed as Date
+  scheduledFor: text.map.date,              // stored as ISO string, typed as Date
+  metadata: text.map.json<{ tags: string[] }>(), // stored as JSON string, typed as object
+})
+```
+
+#### Table Constraints
+
+Add composite constraints after column definitions:
+
+```ts
+const memberships = createTable("memberships", {
+  userId: integer.notNull.foreignKey.references(users.id),
+  groupId: integer.notNull.foreignKey.references(groups.id),
+})
+  .primaryKey("userId", "groupId")
+  .unique("userId", "groupId")
+  .check("userId != groupId")
+```
+
+### Views
+
+Define views from query builders on existing tables:
+
+```ts
+import { createView } from "@sigitex/outlaw"
+
+const activeUsers = createView("active_users",
+  users.select("id", "name").where("active", 1)
+)
+```
+
+### Indexes
+
+```ts
+import { createIndex, createUniqueIndex } from "@sigitex/outlaw"
+
+const emailIndex = createUniqueIndex("idx_users_email").on(users.email)
+const nameIndex = createIndex("idx_users_name").on(users.name)
+```
+
+### Schema
+
+Group tables, views, and indexes into a schema:
+
+```ts
+import { createSchema } from "@sigitex/outlaw"
+
+const schema = createSchema({
+  users,
+  products,
+  memberships,
+  activeUsers,
+  emailIndex,
+  nameIndex,
+})
+```
+
+## Connections
+
+Outlaw abstracts over any SQLite connection via the `Connection` interface:
+
+```ts
+type Connection = {
+  query<Row>(sql: string): Promise<Row[]>
+  script(statements: string[]): Promise<void>
+  transaction?<Result>(
+    work: (connection: TransactionalConnection) => Promise<Result>,
+  ): Promise<Result>
+}
+```
+
+Two built-in adapters are provided:
+
+### Bun
+
+```ts
+import { BunConnection } from "@sigitex/outlaw/bun"
+import { Database } from "bun:sqlite"
+
+const connection = new BunConnection(new Database("app.db"))
+```
+
+### Cloudflare D1
+
+```ts
+import { CloudflareConnection } from "@sigitex/outlaw/cloudflare"
+
+// Inside a Cloudflare Worker
+const connection = new CloudflareConnection(env.DB)
+```
+
+## Database API
+
+`createDatabase` returns a typed object with an accessor for each table and view in the schema.
+
+```ts
+import { createDatabase } from "@sigitex/outlaw"
+
+const db = createDatabase(connection, schema)
+```
+
+Every database API exposes `transaction`. Supported connections provide a fresh
+database API bound to the transaction-scoped connection:
+
+```ts
+await db.transaction(async (tx) => {
+  await tx.users.insert({ name: "Wyatt" }).execute()
+
+  await tx.transaction(async (nested) => {
+    await nested.products.insert({ name: "Hat" }).execute()
+  })
+})
+```
+
+Use only the callback's scoped database API until that callback ends. Bun
+serializes root operations, uses `BEGIN IMMEDIATE`, and implements nested
+callbacks with savepoints. Cloudflare D1 does not support interactive callback
+transactions; `transaction` throws `UnsupportedTransactionError` before the
+callback runs, while `script()` remains available through D1 batch.
+
+### Select
+
+```ts
+// Select all columns
+const rows = await db.users.select("*").fetch()
+
+// Select specific columns
+const names = await db.users.select("name", "email").fetch()
+
+// Single result (throws if no match)
+const user = await db.users.select("*").where("id", 1).first()
+
+// Filtering
+db.users.select("*")
+  .where("name", "Wyatt")             // equality
+  .where("age", ">=", 21)             // comparison operators
+  .where("deletedAt", "is null")       // unary operators
+
+// Sorting, pagination
+db.users.select("*")
+  .orderBy([["name", "asc"], ["id", "desc"]])
+  .limit(10)
+  .offset(20)
+  .fetch()
+```
+
+### Joins
+
+```ts
+db.users.select("*")
+  .join(posts).on(users.id, "=", posts.userId)
+  .fetch()
+
+db.users.select("*")
+  .leftJoin(posts).on(users.id, "=", posts.userId)
+  .fetch()
+```
+
+Join types: `join`, `leftJoin`, `rightJoin`, `crossJoin`. Each accepts a table or a subquery.
+
+### Insert
+
+```ts
+// Single row
+await db.users.insert({ name: "Doc", email: "doc@ok.com" }).execute()
+
+// With returning
+const [inserted] = await db.users
+  .insert({ name: "Doc", email: "doc@ok.com" })
+  .returning("*")
+  .execute()
+```
+
+### Update
+
+```ts
+await db.users
+  .update({ name: "Morgan" })
+  .where("id", 3)
+  .execute()
+
+// With returning
+const updated = await db.users
+  .update({ name: "Morgan" })
+  .where("id", 3)
+  .returning("*")
+  .execute()
+```
+
+### Delete
+
+```ts
+await db.users
+  .delete()
+  .where("id", 3)
+  .execute()
+
+// With returning
+const deleted = await db.users
+  .delete()
+  .where("id", 3)
+  .returning("*")
+  .execute()
+```
+
+## Cowboy Migrations
+
+Wrap any connection with `CowboyConnection` to enable automatic schema migration. On the first query, Outlaw diffs the database against your schema and applies changes -- creating missing tables, rebuilding tables whose columns have changed, and managing views and indexes.
+
+```ts
+import { CowboyConnection } from "@sigitex/outlaw"
+
+const connection = new CowboyConnection(rawConnection, schema)
+```
+
+Schema metadata is stored in a `cowboy_migration` table. When columns change, Outlaw uses an interim table pattern: create the new table, copy data, drop the old one, rename.
+
+### Schema Hacks
+
+Destructive changes (renaming or dropping tables/columns) require explicit hints via `createSchemaHacker`, so data isn't silently lost:
+
+```ts
+import { createSchemaHacker } from "@sigitex/outlaw"
+
+const hack = createSchemaHacker()
+
+hack.renamed.table("old_users", "users")
+hack.renamed.column("users", "firstName", "name")
+hack.dropped.table("legacy_data")
+hack.dropped.column("users", "deprecated_field")
+
+const connection = new CowboyConnection(rawConnection, schema, {
+  hacks: hack.hacks,
+})
+```
+
+## Fixtures and Seeds
+
+Pre-populate tables with `createFixture` (or its alias `createSeed`). Fixtures can use templates to provide default values and `RefBy` to reference rows in other tables.
+
+```ts
+import { createFixture } from "@sigitex/outlaw"
+
+// Simple fixture
+const userFixture = createFixture(users, [
+  { name: "Wyatt", email: "wyatt@earp.com" },
+  { name: "Doc", email: "doc@ok.com" },
+])
+
+// Fixture with a template for default values
+const postFixture = createFixture(posts,
+  { createdAt: () => Date.now() },   // template: default for createdAt
+  [
+    { title: "First Post", userId: users.by.id(1) },  // RefBy
+    { title: "Second Post", userId: users.by.id(1) },
+  ],
+)
+
+// Pass to CowboyConnection
+const connection = new CowboyConnection(rawConnection, schema, {
+  fixtures: { userFixture, postFixture },
+  runFixtures: true,
+})
+```
+
+## License
+
+MIT

package/package.json

@@ -2,13 +2,14 @@
   "name": "@sigitex/outlaw",
   "type": "module",
   "license": "MIT",
+  "description": "A trigger-happy sqlite framework.",
   "author": {
     "name": "Sigitex",
-    "url": "http://github.com/sigitex"
+    "url": "https://sigitex.com"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/sigitex/outlaw.git"
+    "url": "git+https://github.com/sigitex/outlaw.git"
   },
   "exports": {
     ".": {
@@ -27,12 +28,12 @@
     "@semantic-release/exec": "^7.0.3",
     "@types/bun": "^1.3.13",
     "@types/fast-json-stable-stringify": "^2.1.2",
-    "@typescript/native-preview": "beta",
     "husky": "^9.1.7",
     "multi-semantic-release": "^3.1.0",
     "oxfmt": "^0.47.0",
     "oxlint": "^1.62.0",
-    "semantic-release": "^25.0.3"
+    "semantic-release": "^25.0.3",
+    "typescript": "^7.0.2"
   },
   "dependencies": {
     "@sigitex/print": "*",
@@ -42,11 +43,11 @@
   "scripts": {
     "prepare": "husky",
     "lint": "oxlint",
-    "check": "tsgo --build",
+    "check": "tsc --build",
     "test": "bun test --pass-with-no-tests --tsconfig-override tsconfig.test.json"
   },
   "files": [
     "src"
   ],
-  "version": "1.0.0"
+  "version": "1.2.0"
 }

package/src/api/DatabaseTable.ts

@@ -1,5 +1,12 @@
 // oxlint-disable typescript/no-explicit-any
-import type { Delete, Connection, Insert, Select, TableApi, Update } from "./api.types"
+import type {
+  Delete,
+  Connection,
+  Insert,
+  Select,
+  TableApi,
+  Update,
+} from "./api.types"
 import type { TableData } from "../schemaBuilder"
 import {
   DeleteBuilder,
@@ -18,27 +25,32 @@ export class DatabaseTable implements TableApi<any> {
   }
 
   select(all: "*"): Select<any, any>
-  select<Column extends string>(columns: Column[]): Select<Pick<any, any>, any>
-  select(
-    columns: "*" | string[],
-  ): Select<any, any> | Select<Pick<any, any>, any> {
-    return new SelectBuilder(this.connection, this.table, columns)
+  select<Column extends string>(
+    ...columns: Column[]
+  ): Select<Pick<any, any>, any>
+  select(...columns: ("*" | string)[]): Select<any, any> {
+    const selected = columns[0] === "*" || columns.length === 0 ? "*" : columns
+    return new SelectBuilder(this.connection, this.table, selected)
   }
 
-  insert(row: Partial<any>): Insert<any, any, number>
-  insert<Column extends string | number | symbol>(
-    columns: Column[],
-    rows: Pick<any, Column>[],
-  ): Insert<Column, any, number>
-  insert(
-    columnsOrRow: any,
-    rows?: any,
-  ): Insert<any, any, number> | Insert<any, any, number> {
-    if (rows) {
-      return new InsertBuilder(this.connection, this.table, columnsOrRow, rows)
+  insert(...rows: [Partial<any>, ...Partial<any>[]]): Insert<any, any, number>
+  insert(...rows: Record<string, unknown>[]): Insert<any, any, number> {
+    const first = rows[0]
+    if (!first) {
+      throw new Error("insert() requires at least one row")
     }
-    const row = columnsOrRow as Record<string, unknown>
-    return new InsertBuilder(this.connection, this.table, Object.keys(row), [row])
+    const columns = Object.keys(first)
+    const expected = new Set(columns)
+    for (const row of rows.slice(1)) {
+      const rowColumns = Object.keys(row)
+      if (
+        rowColumns.length !== columns.length ||
+        rowColumns.some((column) => !expected.has(column))
+      ) {
+        throw new Error("insert() rows must use the same columns")
+      }
+    }
+    return new InsertBuilder(this.connection, this.table, columns, rows)
   }
 
   update(row: Partial<any>): Update<any, number> {

package/src/api/DatabaseView.ts

@@ -13,10 +13,11 @@ export class DatabaseView implements ViewApi<any> {
   }
 
   select(all: "*"): Select<any, any>
-  select<Column extends string>(columns: Column[]): Select<Pick<any, any>, any>
-  select(
-    columns: "*" | string[],
-  ): Select<any, any> | Select<Pick<any, any>, any> {
-    return new SelectBuilder(this.connection, this.tableData, columns)
+  select<Column extends string>(
+    ...columns: Column[]
+  ): Select<Pick<any, any>, any>
+  select(...columns: ("*" | string)[]): Select<any, any> {
+    const selected = columns[0] === "*" || columns.length === 0 ? "*" : columns
+    return new SelectBuilder(this.connection, this.tableData, selected)
   }
 }

package/src/api/UnsupportedTransactionError.ts

@@ -0,0 +1,7 @@
+export class UnsupportedTransactionError extends Error {
+  override readonly name = "UnsupportedTransactionError"
+
+  constructor() {
+    super("This connection does not support transactions.")
+  }
+}

package/src/api/api.types.ts

@@ -1,11 +1,12 @@
-// oxlint-disable typescript/consistent-type-definitions
 // oxlint-disable typescript/no-explicit-any
+// oxlint-disable typescript/method-signature-style
+// oxlint-disable typescript/consistent-type-definitions
 import type { BINARY_OPERATORS, UNARY_OPERATORS } from "../queryBuilder"
 import type {
-  BuildColumn,
   BuildTable,
   BuildView,
   ColumnRef,
+  InferColumn,
   SchemaMembers,
   TablesOf,
   ViewsOf,
@@ -29,36 +30,54 @@ export type InsertRecord<R> = Partial<R> &
 export type ColumnsOf<BT> =
   BT extends BuildTable<infer Columns> ? Columns : never
 
-export type ColumnTypeOf<BC> =
-  BC extends BuildColumn<infer Type, infer Constraints>
-    ? Constraints extends "notNull" | "primaryKey"
-      ? Type
-      : Type | null
-    : never
-
 export type ColumnTypesOf<BCS> = {
-  readonly [BCK in keyof BCS]: ColumnTypeOf<BCS[BCK]>
+  readonly [BCK in keyof BCS]: InferColumn<BCS[BCK]>
 }
 
 // API
 
 export type DefaultRow = Record<string, unknown>
 
-export type Connection = {
+export type ConnectionOperations = {
   readonly query: <Row = DefaultRow>(sql: string) => Promise<Row[]>
   readonly script: (statements: string[]) => Promise<void>
+}
+
+export type TransactionWork<Result> = (
+  connection: TransactionalConnection,
+) => Promise<Result>
+
+export type Transaction = <Result>(
+  work: TransactionWork<Result>,
+) => Promise<Result>
+
+export type TransactionalConnection = ConnectionOperations & {
+  readonly transaction: Transaction
+}
+
+export type Connection = ConnectionOperations & {
   readonly reset?: () => Promise<void>
+  readonly transaction?: Transaction
 }
 
-export type DatabaseApi<M extends SchemaMembers> = {
+export type DatabaseApi<
+  M extends SchemaMembers,
+  C extends Connection = Connection,
+> = {
   readonly [K in keyof TablesOf<M>]: TableApi<ColumnsOf<TablesOf<M>[K]>>
 } & {
   readonly [K in keyof ViewsOf<M>]: ViewApi<ColumnsOfView<ViewsOf<M>[K]>>
 } & {
-  readonly connection: Connection
+  readonly connection: C
+  readonly transaction: <Result>(
+    work: (
+      database: DatabaseApi<M, TransactionalConnection>,
+    ) => Promise<Result>,
+  ) => Promise<Result>
 }
 
-export type ColumnsOfView<BV> = BV extends BuildView<infer Columns> ? Columns : never
+export type ColumnsOfView<BV> =
+  BV extends BuildView<infer Columns> ? Columns : never
 
 export type ViewApi<Columns> = {
   /** Issue a `SELECT *` query to the API. */
@@ -78,7 +97,7 @@ export type TableApi<Columns> = {
   ): Select<Pick<Columns, Column>, Columns>
   /** Issue an `INSERT` statement. */
   insert<InsertColumns extends Partial<ColumnTypesOf<Columns>>>(
-    ...rows: InsertColumns[]
+    ...rows: [InsertColumns, ...InsertColumns[]]
   ): Insert<InsertColumns, Columns, number>
   /** Issue an `UPDATE` statement. */
   update(row: Partial<ColumnTypesOf<Columns>>): Update<Columns, number>
@@ -91,7 +110,7 @@ export interface HasWhereClause<Columns> {
   /** Add a condition where the given column equals the given value. */
   where<Column extends keyof Columns>(
     column: Column,
-    value: Columns[Column],
+    value: InferColumn<Columns[Column]>,
   ): this
   /** Add a unary `WHERE` condition. */
   where<Column extends keyof Columns>(
@@ -102,13 +121,15 @@ export interface HasWhereClause<Columns> {
   where<Column extends keyof Columns>(
     column: Column,
     operator: BinaryOperator,
-    value: ColumnTypeOf<Columns[Column]>,
+    value: InferColumn<Columns[Column]>,
   ): this
 }
 
 /** Select query API. */
-export interface Select<SelectColumns, Columns>
-  extends HasWhereClause<Columns> {
+export interface Select<
+  SelectColumns,
+  Columns,
+> extends HasWhereClause<Columns> {
   /** Issue the query, expecting an array of results. */
   fetch(): Promise<ColumnTypesOf<SelectColumns>[]>
   /** Issue the query, returning a single result, or throwing.. */
@@ -177,11 +198,11 @@ export interface Update<Columns, Returning> extends HasWhereClause<Columns> {
   /** Execute the statement. */
   execute(): Promise<Returning>
   /** Specify a `RETURNING *` clause. */
-  returning(all: "*"): Update<Columns, Columns[]>
+  returning(all: "*"): Update<Columns, ColumnTypesOf<Columns>[]>
   /** Specify a `RETURNING` clause with the chosen columns. */
   returning<Column extends keyof Columns>(
-    columns: Column[],
-  ): Update<Columns, Pick<Columns, Column>[]>
+    ...columns: Column[]
+  ): Update<Columns, ColumnTypesOf<Pick<Columns, Column>>[]>
 }
 
 /** Delete statement API. */
@@ -189,11 +210,11 @@ export interface Delete<Columns, Returning> extends HasWhereClause<Columns> {
   /** Execute the statement. */
   execute(): Promise<Returning>
   /** Specify a `RETURNING *` clause. */
-  returning(all: "*"): Delete<Columns, Columns[]>
+  returning(all: "*"): Delete<Columns, ColumnTypesOf<Columns>[]>
   /** Specify a `RETURNING` clause with the chosen columns. */
   returning<Column extends keyof Columns>(
-    columns: Column[],
-  ): Delete<Columns, Pick<Columns, Column>[]>
+    ...columns: Column[]
+  ): Delete<Columns, ColumnTypesOf<Pick<Columns, Column>>[]>
 }
 
 export type UnaryOperator = ElementOf<typeof UNARY_OPERATORS>

package/src/api/createDatabase.ts

@@ -1,13 +1,38 @@
-import type { BuildTable, BuildView, SchemaMembers, Schema } from "../schemaBuilder"
-import type { Connection, DatabaseApi } from "./api.types"
+import type {
+  BuildTable,
+  BuildView,
+  SchemaMembers,
+  Schema,
+} from "../schemaBuilder"
+import type {
+  Connection,
+  DatabaseApi,
+  TransactionalConnection,
+} from "./api.types"
 import { DatabaseTable } from "./DatabaseTable"
 import { DatabaseView } from "./DatabaseView"
+import { UnsupportedTransactionError } from "./UnsupportedTransactionError"
 
-export function createDatabase<M extends SchemaMembers>(
-  connection: Connection,
+export function createDatabase<M extends SchemaMembers, C extends Connection>(
+  connection: C,
   schema: Schema<M>,
 ) {
-  const api = { connection }
+  const api = {
+    connection,
+    transaction: async <Result>(
+      work: (
+        database: DatabaseApi<M, TransactionalConnection>,
+      ) => Promise<Result>,
+    ) => {
+      const transaction = connection.transaction
+      if (!transaction) {
+        throw new UnsupportedTransactionError()
+      }
+      return transaction((scopedConnection) =>
+        work(createDatabase(scopedConnection, schema)),
+      )
+    },
+  }
   for (const [property, member] of Object.entries(schema.tables)) {
     const table = member as BuildTable<unknown>
     Object.defineProperty(api, property, {
@@ -20,5 +45,5 @@ export function createDatabase<M extends SchemaMembers>(
       value: new DatabaseView(connection, view.$tableData),
     })
   }
-  return api as DatabaseApi<M>
+  return api as DatabaseApi<M, C>
 }

package/src/api/index.ts

@@ -2,3 +2,4 @@ export * from "./api.types"
 export * from "./DatabaseTable"
 export * from "./DatabaseView"
 export * from "./createDatabase"
+export * from "./UnsupportedTransactionError"

package/src/bun/bun.ts

@@ -1,27 +1,140 @@
 import type { Database } from "bun:sqlite"
-import type { DefaultRow, Connection } from "../api/api.types"
+import type {
+  Connection,
+  DefaultRow,
+  TransactionalConnection,
+  TransactionWork,
+} from "../api/api.types"
+
+type TransactionState = {
+  active: boolean
+  nextSavepoint: number
+}
 
 export class BunConnection implements Connection {
   private readonly db: Database
+  private pending = Promise.resolve()
 
   constructor(db: Database) {
     this.db = db
   }
 
   async query<Row = DefaultRow>(sql: string) {
-    return this.db.query(sql).all() as Row[]
+    return this.exclusive(() => query<Row>(this.db, sql))
   }
 
   async script(statements: string[]) {
-    this.db.run("BEGIN")
+    await this.exclusive(() => script(this.db, statements, "BEGIN"))
+  }
+
+  async transaction<Result>(work: TransactionWork<Result>) {
+    return this.exclusive(async () => {
+      await run(this.db, "BEGIN IMMEDIATE")
+      const state: TransactionState = { active: true, nextSavepoint: 0 }
+      const connection = new BunTransactionConnection(this.db, state)
+
+      try {
+        const result = await work(connection)
+        connection.close()
+        await run(this.db, "COMMIT")
+        return result
+      } catch (error) {
+        connection.close()
+        await run(this.db, "ROLLBACK")
+        throw error
+      } finally {
+        state.active = false
+      }
+    })
+  }
+
+  private async exclusive<Result>(work: () => Promise<Result>) {
+    const previous = this.pending
+    let release!: () => void
+    this.pending = new Promise<void>((resolve) => {
+      release = resolve
+    })
+
+    await previous
     try {
-      for (const s of statements) {
-        this.db.run(s)
+      return await work()
+    } finally {
+      release()
+    }
+  }
+}
+
+class BunTransactionConnection implements TransactionalConnection {
+  private readonly db: Database
+  private readonly state: TransactionState
+  private active = true
+
+  constructor(db: Database, state: TransactionState) {
+    this.db = db
+    this.state = state
+  }
+
+  async query<Row = DefaultRow>(sql: string) {
+    this.assertActive()
+    return query<Row>(this.db, sql)
+  }
+
+  async script(statements: string[]) {
+    this.assertActive()
+    await this.transaction(async (connection) => {
+      for (const statement of statements) {
+        await connection.query(statement)
       }
-      this.db.run("COMMIT")
+    })
+  }
+
+  async transaction<Result>(work: TransactionWork<Result>) {
+    this.assertActive()
+    const name = `outlaw_transaction_${++this.state.nextSavepoint}`
+    await run(this.db, `SAVEPOINT ${name}`)
+    const connection = new BunTransactionConnection(this.db, this.state)
+
+    try {
+      const result = await work(connection)
+      connection.close()
+      await run(this.db, `RELEASE SAVEPOINT ${name}`)
+      return result
     } catch (error) {
-      this.db.run("ROLLBACK")
+      connection.close()
+      await run(this.db, `ROLLBACK TO SAVEPOINT ${name}`)
+      await run(this.db, `RELEASE SAVEPOINT ${name}`)
       throw error
     }
   }
+
+  close() {
+    this.active = false
+  }
+
+  private assertActive() {
+    if (!this.active || !this.state.active) {
+      throw new Error("Transaction connection is no longer active.")
+    }
+  }
+}
+
+async function query<Row>(db: Database, sql: string) {
+  return db.query(sql).all() as Row[]
+}
+
+async function run(db: Database, sql: string) {
+  db.run(sql)
+}
+
+async function script(db: Database, statements: string[], begin: "BEGIN") {
+  await run(db, begin)
+  try {
+    for (const statement of statements) {
+      await run(db, statement)
+    }
+    await run(db, "COMMIT")
+  } catch (error) {
+    await run(db, "ROLLBACK")
+    throw error
+  }
 }

package/src/cowboyMigration/CowboyConnection.ts

@@ -1,5 +1,5 @@
 import type { Fixtures, Schema, SchemaMembers, Seeds } from "../schemaBuilder"
-import type { Connection, DefaultRow } from "../api"
+import type { Connection, DefaultRow, Transaction } from "../api"
 import type { SchemaHack } from "./cowboyMigration.types"
 import { CowboyMigrator } from "./CowboyMigrator"
 import { CowboySeeder } from "./CowboySeeder"
@@ -15,36 +15,68 @@ export class CowboyConnection implements Connection {
   private readonly raw: Connection
   private readonly schema: Schema<SchemaMembers>
   private readonly options: CowboyOptions
-  private shotFirst = false
+  private readiness?: Promise<void>
+  readonly transaction?: Transaction
 
-  constructor(raw: Connection, schema: Schema<SchemaMembers>, options?: CowboyOptions) {
+  constructor(
+    raw: Connection,
+    schema: Schema<SchemaMembers>,
+    options?: CowboyOptions,
+  ) {
     this.raw = raw
     this.schema = schema
     this.options = options ?? {}
+    const transaction = raw.transaction?.bind(raw)
+    if (transaction) {
+      this.transaction = async (work) => {
+        await this.ready()
+        return transaction(work)
+      }
+    }
   }
 
   async query<Row = DefaultRow>(sql: string) {
-    if (!this.shotFirst) {
-      await this.shotgun()
-    }
+    await this.ready()
     return this.raw.query(sql) as Promise<Row[]>
   }
 
   async script(statements: string[]) {
-    if (!this.shotFirst) {
-      await this.shotgun()
-    }
+    await this.ready()
     await this.raw.script(statements)
   }
 
   async reset() {
-    this.shotFirst = false
+    try {
+      await this.readiness
+    } catch {
+      // A failed initialization is already reset by ready().
+    }
+    this.readiness = undefined
+  }
+
+  private ready() {
+    if (this.readiness) {
+      return this.readiness
+    }
+
+    const readiness = this.shotgun().catch((error: unknown) => {
+      if (this.readiness === readiness) {
+        this.readiness = undefined
+      }
+      throw error
+    })
+    this.readiness = readiness
+    return readiness
   }
 
   private async shotgun() {
-    this.shotFirst = true
-    await new CowboyMigrator(this.raw, this.schema, this.options.hacks ?? []).migrate()
-    const hasSeeds = this.options.seeds || (this.options.runFixtures && this.options.fixtures)
+    await new CowboyMigrator(
+      this.raw,
+      this.schema,
+      this.options.hacks ?? [],
+    ).migrate()
+    const hasSeeds =
+      this.options.seeds || (this.options.runFixtures && this.options.fixtures)
     if (hasSeeds) {
       await new CowboySeeder(
         this.raw,

package/src/queryBuilder/DeleteBuilder.ts

@@ -20,13 +20,15 @@ export class DeleteBuilder implements Delete<any, any> {
 
   async execute(): Promise<any> {
     const result = await this.connection.query(generateDelete(this.command))
-    return this.command.returning ? Mappings.results(this.table, result) : result
+    return this.command.returning
+      ? Mappings.results(this.table, result)
+      : result
   }
 
   returning(all: "*"): Delete<any, any[]>
-  returning(columns: string[]): Delete<any, Pick<any, any>[]>
-  returning(columns: any): Delete<any, any[]> | Delete<any, Pick<any, any>[]> {
-    this.command.returning = columns === "*" ? ["*"] : columns
+  returning(...columns: string[]): Delete<any, Pick<any, any>[]>
+  returning(...columns: ("*" | string)[]): Delete<any, any[]> {
+    this.command.returning = columns[0] === "*" ? ["*"] : columns
     return this
   }
 

package/src/queryBuilder/UpdateBuilder.ts

@@ -24,13 +24,15 @@ export class UpdateBuilder implements Update<any, any> {
 
   async execute(): Promise<any> {
     const result = await this.connection.query(generateUpdate(this.command))
-    return this.command.returning ? Mappings.results(this.table, result) : result
+    return this.command.returning
+      ? Mappings.results(this.table, result)
+      : result
   }
 
   returning(all: "*"): Update<any, any[]>
-  returning(columns: string[]): Update<any, Pick<any, any>[]>
-  returning(columns: any): Update<any, any[]> | Update<any, Pick<any, any>[]> {
-    this.command.returning = columns === "*" ? ["*"] : columns
+  returning(...columns: string[]): Update<any, Pick<any, any>[]>
+  returning(...columns: ("*" | string)[]): Update<any, any[]> {
+    this.command.returning = columns[0] === "*" ? ["*"] : columns
     return this
   }