Add PostgreSQL FOR UPDATE getters

Add a PostgreSQL-specific getRecordForUpdate helper that appends FOR UPDATE to the generated SELECT statement so callers can lock a row inside an explicit transaction. generateProcsForModels now always emits a direct-connection get<RecordName>ForUpdate proc that accepts db_postgres.DbConn. There is intentionally no dbType overload for this API, because reacquiring a connection via withConnection would defeat the lock's transactional scope. The source docs and README now document the new helper and show the intended usage pattern inside inTransaction: db.inTransaction: var item = conn.getTodoItemForUpdate(todoId) item.priority += 1 discard conn.updateTodoItem(item)
Update documentation for new signature changes, bump version.
2026-03-24 22:04:49 -05:00 · 2026-03-24 21:48:51 -05:00 · 2026-03-24 21:39:25 -05:00
3 changed files with 357 additions and 72 deletions
--- a/README.rst
+++ b/README.rst
@@ -83,7 +83,7 @@ Using Fiber ORM we can generate a data access layer with:
 .. code-block:: Nim
   # db.nim
   import std/[options]
-   import db_connectors/db_postgres
+   import db_connector/db_postgres
   import fiber_orm
   import ./models.nim

@@ -100,32 +100,90 @@ Using Fiber ORM we can generate a data access layer with:

   generateLookup(TodoDB, TimeEntry, @["todoItemId"])

-This will generate the following procedures:
+This will generate procedures like the following in two flavors:
+
+* a `dbType` flavor that acquires a connection via `withConnection`
+* a connection flavor that operates directly on an existing
+  `conn: D` where `D: DbConnType`

 .. code-block:: Nim
   proc getTodoItem*(db: TodoDB, id: UUID): TodoItem;
+   proc getTodoItem*[D: DbConnType](conn: D, id: UUID): TodoItem;
+   proc getTodoItemForUpdate*(conn: db_postgres.DbConn, id: UUID): TodoItem;
+   proc tryGetTodoItem*(db: TodoDB, id: UUID): Option[TodoItem];
+   proc tryGetTodoItem*[D: DbConnType](conn: D, id: UUID): Option[TodoItem];
   proc getTodoItemIfItExists*(db: TodoDB, id: UUID): Option[TodoItem];
-   proc getAllTodoItems*(db: TodoDB): seq[TodoItem];
+   proc getTodoItemIfItExists*[D: DbConnType](
+     conn: D, id: UUID): Option[TodoItem];
+   proc getAllTodoItems*(db: TodoDB,
+     pagination = none[PaginationParams]()): PagedRecords[TodoItem];
+   proc getAllTodoItems*[D: DbConnType](conn: D,
+     pagination = none[PaginationParams]()): PagedRecords[TodoItem];
   proc createTodoItem*(db: TodoDB, rec: TodoItem): TodoItem;
+   proc createTodoItem*[D: DbConnType](conn: D, rec: TodoItem): TodoItem;
   proc updateTodoItem*(db: TodoDB, rec: TodoItem): bool;
+   proc updateTodoItem*[D: DbConnType](conn: D, rec: TodoItem): bool;
+   proc createOrUpdateTodoItem*(db: TodoDB, rec: TodoItem): TodoItem;
+   proc createOrUpdateTodoItem*[D: DbConnType](
+     conn: D, rec: TodoItem): TodoItem;
   proc deleteTodoItem*(db: TodoDB, rec: TodoItem): bool;
+   proc deleteTodoItem*[D: DbConnType](conn: D, rec: TodoItem): bool;
   proc deleteTodoItem*(db: TodoDB, id: UUID): bool;
+   proc deleteTodoItem*[D: DbConnType](conn: D, id: UUID): bool;

   proc findTodoItemsWhere*(db: TodoDB, whereClause: string,
-     values: varargs[string, dbFormat]): seq[TodoItem];
+     values: varargs[string, dbFormat],
+     pagination = none[PaginationParams]()): PagedRecords[TodoItem];
+   proc findTodoItemsWhere*[D: DbConnType](conn: D, whereClause: string,
+     values: varargs[string, dbFormat],
+     pagination = none[PaginationParams]()): PagedRecords[TodoItem];

   proc getTimeEntry*(db: TodoDB, id: UUID): TimeEntry;
+   proc getTimeEntry*[D: DbConnType](conn: D, id: UUID): TimeEntry;
   proc getTimeEntryIfItExists*(db: TodoDB, id: UUID): Option[TimeEntry];
-   proc getAllTimeEntries*(db: TodoDB): seq[TimeEntry];
+   proc getTimeEntryIfItExists*[D: DbConnType](
+     conn: D, id: UUID): Option[TimeEntry];
+   proc getAllTimeEntries*(db: TodoDB,
+     pagination = none[PaginationParams]()): PagedRecords[TimeEntry];
+   proc getAllTimeEntries*[D: DbConnType](conn: D,
+     pagination = none[PaginationParams]()): PagedRecords[TimeEntry];
   proc createTimeEntry*(db: TodoDB, rec: TimeEntry): TimeEntry;
+   proc createTimeEntry*[D: DbConnType](conn: D, rec: TimeEntry): TimeEntry;
   proc updateTimeEntry*(db: TodoDB, rec: TimeEntry): bool;
+   proc updateTimeEntry*[D: DbConnType](conn: D, rec: TimeEntry): bool;
   proc deleteTimeEntry*(db: TodoDB, rec: TimeEntry): bool;
+   proc deleteTimeEntry*[D: DbConnType](conn: D, rec: TimeEntry): bool;
   proc deleteTimeEntry*(db: TodoDB, id: UUID): bool;
+   proc deleteTimeEntry*[D: DbConnType](conn: D, id: UUID): bool;

   proc findTimeEntriesWhere*(db: TodoDB, whereClause: string,
-     values: varargs[string, dbFormat]): seq[TimeEntry];
+     values: varargs[string, dbFormat],
+     pagination = none[PaginationParams]()): PagedRecords[TimeEntry];
+   proc findTimeEntriesWhere*[D: DbConnType](conn: D, whereClause: string,
+     values: varargs[string, dbFormat],
+     pagination = none[PaginationParams]()): PagedRecords[TimeEntry];

-   proc findTimeEntriesByTodoItemId(db: TodoDB, todoItemId: UUID): seq[TimeEntry];
+   proc findTimeEntriesByTodoItemId*(db: TodoDB, todoItemId: UUID,
+     pagination = none[PaginationParams]()): PagedRecords[TimeEntry];
+   proc findTimeEntriesByTodoItemId*[D: DbConnType](
+     conn: D, todoItemId: UUID,
+     pagination = none[PaginationParams]()): PagedRecords[TimeEntry];
+
+Use the `dbType` flavor when the caller does not already have a connection.
+Use the connection flavor inside `withConnection` or `inTransaction`.
+The generated `get<RecordName>ForUpdate` helper is PostgreSQL-specific and
+is only available for direct PostgreSQL connections.
+
+Warning: do not call the `dbType` flavor from inside `inTransaction`.
+Those overloads call `withConnection` and may acquire a different
+connection, causing the statements to execute outside the active
+transaction.
+
+.. code-block:: Nim
+   db.inTransaction:
+     var item = conn.getTodoItemForUpdate(todoId)
+     item.priority += 1
+     discard conn.updateTodoItem(item)

 Object-Relational Modeling
 ==========================
@@ -133,11 +191,11 @@ Object-Relational Modeling
 Model Class
 -----------

-Fiber ORM uses simple Nim `object`s and `ref object`s as model classes.
+Fiber ORM uses simple Nim objects and ref objects as model classes.
 Fiber ORM expects there to be one table for each model class.

 Name Mapping
-````````````
+^^^^^^^^^^^^
 Fiber ORM uses `snake_case` for database identifiers (column names, table
 names, etc.) and `camelCase` for Nim identifiers. We automatically convert
 model names to and from table names (`TodoItem` <-> `todo_items`), as well
@@ -168,7 +226,7 @@ procedures in the `fiber_orm/util`_ module for details.
 .. _util: fiber_orm/util.html

 ID Field
-````````
+^^^^^^^^

 Fiber ORM expects every model class to have a field named `id`, with a
 corresponding `id` column in the model table. This field must be either a
@@ -257,8 +315,10 @@ Many of the Fiber ORM macros expect a database object type to be passed.
 In the example above the `pool.DbConnPool`_ object is used as database
 object type (aliased as `TodoDB`). This is the intended usage pattern, but
 anything can be passed as the database object type so long as there is a
-defined `withConn` template that provides an injected `conn: DbConn` object
+defined `withConnection` template that provides an injected `conn: DbConn` object
 to the provided statement body.
+The generated connection-flavor procedures are intended to work directly
+with that `conn` value.

 For example, a valid database object implementation that opens a new
 connection for every request might look like this:
@@ -269,7 +329,7 @@ connection for every request might look like this:
   type TodoDB* = object
     connString: string

-   template withConn*(db: TodoDB, stmt: untyped): untyped =
+   template withConnection*(db: TodoDB, stmt: untyped): untyped =
     let conn {.inject.} = open("", "", "", db.connString)
     try: stmt
     finally: close(conn)
--- a/fiber_orm.nimble
+++ b/fiber_orm.nimble
@@ -1,6 +1,6 @@
 # Package

-version       = "4.1.0"
+version       = "4.2.0"
 author        = "Jonathan Bernard"
 description   = "Lightweight Postgres ORM for Nim."
 license       = "GPL-3.0"
--- a/src/fiber_orm.nim
+++ b/src/fiber_orm.nim
@@ -100,39 +100,89 @@
 ##
 ##    generateLookup(TodoDB, TimeEntry, @["todoItemId"])
 ##
-## This will generate the following procedures:
+## This will generate procedures like the following in two flavors:
+##
+## * a `dbType` flavor that acquires a connection via `withConnection`
+## * a connection flavor that operates directly on an existing
+##   `conn: D` where `D: DbConnType`
 ##
 ## .. code-block:: Nim
 ##    proc getTodoItem*(db: TodoDB, id: UUID): TodoItem;
-##
+##    proc getTodoItem*[D: DbConnType](conn: D, id: UUID): TodoItem;
+##    proc getTodoItemForUpdate*(conn: db_postgres.DbConn, id: UUID): TodoItem;
+##    proc tryGetTodoItem*(db: TodoDB, id: UUID): Option[TodoItem];
+##    proc tryGetTodoItem*[D: DbConnType](conn: D, id: UUID): Option[TodoItem];
+##    proc getTodoItemIfItExists*(db: TodoDB, id: UUID): Option[TodoItem];
+##    proc getTodoItemIfItExists*[D: DbConnType](
+##      conn: D, id: UUID): Option[TodoItem];
 ##    proc createTodoItem*(db: TodoDB, rec: TodoItem): TodoItem;
+##    proc createTodoItem*[D: DbConnType](conn: D, rec: TodoItem): TodoItem;
 ##    proc updateTodoItem*(db: TodoDB, rec: TodoItem): bool;
-##    proc createOrUpdateTodoItem*(db: TodoDB, rec: TodoItem): bool;
+##    proc updateTodoItem*[D: DbConnType](conn: D, rec: TodoItem): bool;
+##    proc createOrUpdateTodoItem*(db: TodoDB, rec: TodoItem): TodoItem;
+##    proc createOrUpdateTodoItem*[D: DbConnType](
+##      conn: D, rec: TodoItem): TodoItem;
 ##    proc deleteTodoItem*(db: TodoDB, rec: TodoItem): bool;
+##    proc deleteTodoItem*[D: DbConnType](conn: D, rec: TodoItem): bool;
 ##    proc deleteTodoItem*(db: TodoDB, id: UUID): bool;
+##    proc deleteTodoItem*[D: DbConnType](conn: D, id: UUID): bool;
 ##
 ##    proc getAllTodoItems*(db: TodoDB,
-##      pagination = none[PaginationParams]()): seq[TodoItem];
+##      pagination = none[PaginationParams]()): PagedRecords[TodoItem];
+##    proc getAllTodoItems*[D: DbConnType](conn: D,
+##      pagination = none[PaginationParams]()): PagedRecords[TodoItem];
 ##
 ##    proc findTodoItemsWhere*(db: TodoDB, whereClause: string,
 ##      values: varargs[string, dbFormat], pagination = none[PaginationParams]()
-##      ): seq[TodoItem];
+##      ): PagedRecords[TodoItem];
+##    proc findTodoItemsWhere*[D: DbConnType](conn: D, whereClause: string,
+##      values: varargs[string, dbFormat], pagination = none[PaginationParams]()
+##      ): PagedRecords[TodoItem];
 ##
 ##    proc getTimeEntry*(db: TodoDB, id: UUID): TimeEntry;
+##    proc getTimeEntry*[D: DbConnType](conn: D, id: UUID): TimeEntry;
 ##    proc createTimeEntry*(db: TodoDB, rec: TimeEntry): TimeEntry;
+##    proc createTimeEntry*[D: DbConnType](conn: D, rec: TimeEntry): TimeEntry;
 ##    proc updateTimeEntry*(db: TodoDB, rec: TimeEntry): bool;
+##    proc updateTimeEntry*[D: DbConnType](conn: D, rec: TimeEntry): bool;
 ##    proc deleteTimeEntry*(db: TodoDB, rec: TimeEntry): bool;
+##    proc deleteTimeEntry*[D: DbConnType](conn: D, rec: TimeEntry): bool;
 ##    proc deleteTimeEntry*(db: TodoDB, id: UUID): bool;
+##    proc deleteTimeEntry*[D: DbConnType](conn: D, id: UUID): bool;
 ##
 ##    proc getAllTimeEntries*(db: TodoDB,
-##      pagination = none[PaginationParams]()): seq[TimeEntry];
+##      pagination = none[PaginationParams]()): PagedRecords[TimeEntry];
+##    proc getAllTimeEntries*[D: DbConnType](conn: D,
+##      pagination = none[PaginationParams]()): PagedRecords[TimeEntry];
 ##
 ##    proc findTimeEntriesWhere*(db: TodoDB, whereClause: string,
 ##      values: varargs[string, dbFormat], pagination = none[PaginationParams]()
-##      ): seq[TimeEntry];
+##      ): PagedRecords[TimeEntry];
+##    proc findTimeEntriesWhere*[D: DbConnType](conn: D, whereClause: string,
+##      values: varargs[string, dbFormat], pagination = none[PaginationParams]()
+##      ): PagedRecords[TimeEntry];
 ##
-##    proc findTimeEntriesByTodoItemId(db: TodoDB, todoItemId: UUID,
-##      pagination = none[PaginationParams]()): seq[TimeEntry];
+##    proc findTimeEntriesByTodoItemId*(db: TodoDB, todoItemId: UUID,
+##      pagination = none[PaginationParams]()): PagedRecords[TimeEntry];
+##    proc findTimeEntriesByTodoItemId*[D: DbConnType](
+##      conn: D, todoItemId: UUID,
+##      pagination = none[PaginationParams]()): PagedRecords[TimeEntry];
+##
+## Use the `dbType` flavor when the caller does not already have a connection.
+## Use the connection flavor inside `withConnection` or `inTransaction`.
+## The generated `get<RecordName>ForUpdate` helper is PostgreSQL-specific and
+## is only available for direct PostgreSQL connections.
+##
+## Warning: do not call the `dbType` flavor from inside `inTransaction`.
+## Those overloads call `withConnection` and may acquire a different
+## connection, causing the statements to execute outside the active
+## transaction.
+##
+## .. code-block:: Nim
+##    db.inTransaction:
+##      var item = conn.getTodoItemForUpdate(todoId)
+##      item.priority += 1
+##      discard conn.updateTodoItem(item)
 ##
 ## Object-Relational Modeling
 ## ==========================
@@ -140,11 +190,11 @@
 ## Model Class
 ## -----------
 ##
-## Fiber ORM uses simple Nim `object`s and `ref object`s as model classes.
+## Fiber ORM uses simple Nim objects and ref objects as model classes.
 ## Fiber ORM expects there to be one table for each model class.
 ##
 ## Name Mapping
-## ````````````
+## ^^^^^^^^^^^^
 ## Fiber ORM uses `snake_case` for database identifiers (column names, table
 ## names, etc.) and `camelCase` for Nim identifiers. We automatically convert
 ## model names to and from table names (`TodoItem` <-> `todo_items`), as well
@@ -175,7 +225,7 @@
 ## .. _util: fiber_orm/util.html
 ##
 ## ID Field
-## ````````
+## ^^^^^^^^
 ##
 ## Fiber ORM expects every model class to have a field named `id`, with a
 ## corresponding `id` column in the model table. This field must be either a
@@ -266,6 +316,8 @@
 ## anything can be passed as the database object type so long as there is a
 ## defined `withConnection` template that provides a `conn: DbConn` object
 ## to the provided statement body.
+## The generated connection-flavor procedures are intended to work directly
+## with that `conn` value.
 ##
 ## For example, a valid database object implementation that opens a new
 ## connection for every request might look like this:
@@ -285,7 +337,7 @@
 ## .. _pool.DbConnPool: fiber_orm/pool.html#DbConnPool
 ##
 import std/[json, macros, options, sequtils, strutils]
-import db_connector/db_common
+import db_connector/[db_common, db_postgres]
 import uuids

 from std/unicode import capitalize
@@ -402,6 +454,23 @@ template getRecord*[D: DbConnType](db: D, modelType: type, id: typed): untyped =

  rowToModel(modelType, row)

+template getRecordForUpdate*(db: db_postgres.DbConn, modelType: type, id: typed): untyped =
+  ## Fetch a record by id and lock it with `FOR UPDATE`.
+  ##
+  ## This is PostgreSQL-specific and should only be used inside a transaction.
+  let sqlStmt =
+    "SELECT " & columnNamesForModel(modelType).join(",") &
+    " FROM " & tableName(modelType) &
+    " WHERE id = ? FOR UPDATE"
+
+  logQuery("getRecordForUpdate", sqlStmt, [("id", $id)])
+  let row = db.getRow(sql(sqlStmt), @[$id])
+
+  if allIt(row, it.len == 0):
+    raise newException(NotFoundError, "no " & modelName(modelType) & " record for id " & $id)
+
+  rowToModel(modelType, row)
+
 template tryGetRecord*[D: DbConnType](db: D, modelType: type, id: typed): untyped =
  ## Fetch a record by id.
  let sqlStmt =
@@ -587,23 +656,50 @@ template findViaJoinTable*[D: DbConnType](

 macro generateProcsForModels*(dbType: type, modelTypes: openarray[type]): untyped =
  ## Generate all standard access procedures for the given model types. For a
-  ## `model class`_ named `TodoItem`, this will generate the following
-  ## procedures:
+  ## `model class`_ named `TodoItem`, this will generate `dbType` and
+  ## connection overloads for procedures like the following:
  ##
  ## .. code-block:: Nim
  ##    proc getTodoItem*(db: TodoDB, id: idType): TodoItem;
-  ##    proc getAllTodoItems*(db: TodoDB): TodoItem;
+  ##    proc getTodoItem*[D: DbConnType](conn: D, id: idType): TodoItem;
+  ##    proc getTodoItemForUpdate*(conn: db_postgres.DbConn, id: idType): TodoItem;
+  ##    proc tryGetTodoItem*(db: TodoDB, id: idType): Option[TodoItem];
+  ##    proc tryGetTodoItem*[D: DbConnType](conn: D, id: idType): Option[TodoItem];
+  ##    proc getTodoItemIfItExists*(db: TodoDB, id: idType): Option[TodoItem];
+  ##    proc getTodoItemIfItExists*[D: DbConnType](
+  ##      conn: D, id: idType): Option[TodoItem];
+  ##    proc getAllTodoItems*(db: TodoDB): PagedRecords[TodoItem];
+  ##    proc getAllTodoItems*[D: DbConnType](conn: D): PagedRecords[TodoItem];
  ##    proc createTodoItem*(db: TodoDB, rec: TodoItem): TodoItem;
+  ##    proc createTodoItem*[D: DbConnType](conn: D, rec: TodoItem): TodoItem;
  ##    proc deleteTodoItem*(db: TodoDB, rec: TodoItem): bool;
+  ##    proc deleteTodoItem*[D: DbConnType](conn: D, rec: TodoItem): bool;
  ##    proc deleteTodoItem*(db: TodoDB, id: idType): bool;
+  ##    proc deleteTodoItem*[D: DbConnType](conn: D, id: idType): bool;
  ##    proc updateTodoItem*(db: TodoDB, rec: TodoItem): bool;
-  ##    proc createOrUpdateTodoItem*(db: TodoDB, rec: TodoItem): bool;
+  ##    proc updateTodoItem*[D: DbConnType](conn: D, rec: TodoItem): bool;
+  ##    proc createOrUpdateTodoItem*(db: TodoDB, rec: TodoItem): TodoItem;
+  ##    proc createOrUpdateTodoItem*[D: DbConnType](
+  ##      conn: D, rec: TodoItem): TodoItem;
  ##
  ##    proc findTodoItemsWhere*(
-  ##      db: TodoDB, whereClause: string, values: varargs[string]): TodoItem;
+  ##      db: TodoDB,
+  ##      whereClause: string,
+  ##      values: varargs[string, dbFormat],
+  ##      pagination = none[PaginationParams]()): PagedRecords[TodoItem];
+  ##    proc findTodoItemsWhere*[D: DbConnType](
+  ##      conn: D,
+  ##      whereClause: string,
+  ##      values: varargs[string, dbFormat],
+  ##      pagination = none[PaginationParams]()): PagedRecords[TodoItem];
  ##
  ## `dbType` is expected to be some type that has a defined `withConnection`
  ## procedure (see `Database Object`_ for details).
+  ## The `dbType` overloads are convenience wrappers around `withConnection`.
+  ## Inside `inTransaction`, prefer the overloads that take `conn: D` where
+  ## `D: DbConnType` so all operations use the transaction connection.
+  ## The generated `get<RecordName>ForUpdate` helper is PostgreSQL-specific and
+  ## is only available for direct PostgreSQL connections.
  ##
  ## .. _Database Object: #database-object
  result = newStmtList()
@@ -615,6 +711,7 @@ macro generateProcsForModels*(dbType: type, modelTypes: openarray[type]): untype

    let modelName = $(t.getType[1])
    let getName = ident("get" & modelName)
+    let getForUpdateName = ident("get" & modelName & "ForUpdate")
    let tryGetName = ident("tryGet" & modelName)
    let getIfExistsName = ident("get" & modelName & "IfItExists")
    let getAllName = ident("getAll" & pluralize(modelName))
@@ -628,17 +725,35 @@ macro generateProcsForModels*(dbType: type, modelTypes: openarray[type]): untype
      proc `getName`*(db: `dbType`, id: `idType`): `t` =
        db.withConnection conn: result = getRecord(conn, `t`, id)

+      proc `getName`*[D: DbConnType](conn: D, id: `idType`): `t` =
+        result = getRecord(conn, `t`, id)
+
+      proc `getForUpdateName`*(conn: db_postgres.DbConn, id: `idType`): `t` =
+        result = getRecordForUpdate(conn, `t`, id)
+
      proc `tryGetName`*(db: `dbType`, id: `idType`): Option[`t`] =
        db.withConnection conn: result = tryGetRecord(conn, `t`, id)

+      proc `tryGetName`*[D: DbConnType](conn: D, id: `idType`): Option[`t`] =
+        result = tryGetRecord(conn, `t`, id)
+
      proc `getIfExistsName`*(db: `dbType`, id: `idType`): Option[`t`] =
        db.withConnection conn:
          try: result = some(getRecord(conn, `t`, id))
          except NotFoundError: result = none[`t`]()

+      proc `getIfExistsName`*[D: DbConnType](conn: D, id: `idType`): Option[`t`] =
+        try: result = some(getRecord(conn, `t`, id))
+        except NotFoundError: result = none[`t`]()
+
      proc `getAllName`*(db: `dbType`, pagination = none[PaginationParams]()): PagedRecords[`t`] =
        db.withConnection conn: result = getAllRecords(conn, `t`, pagination)

+      proc `getAllName`*[D: DbConnType](
+          conn: D,
+          pagination = none[PaginationParams]()): PagedRecords[`t`] =
+        result = getAllRecords(conn, `t`, pagination)
+
      proc `findWhereName`*(
          db: `dbType`,
          whereClause: string,
@@ -647,21 +762,43 @@ macro generateProcsForModels*(dbType: type, modelTypes: openarray[type]): untype
        db.withConnection conn:
          result = findRecordsWhere(conn, `t`, whereClause, values, pagination)

+      proc `findWhereName`*[D: DbConnType](
+          conn: D,
+          whereClause: string,
+          values: varargs[string, dbFormat],
+          pagination = none[PaginationParams]()): PagedRecords[`t`] =
+        result = findRecordsWhere(conn, `t`, whereClause, values, pagination)
+
      proc `createName`*(db: `dbType`, rec: `t`): `t` =
        db.withConnection conn: result = createRecord(conn, rec)

+      proc `createName`*[D: DbConnType](conn: D, rec: `t`): `t` =
+        result = createRecord(conn, rec)
+
      proc `updateName`*(db: `dbType`, rec: `t`): bool =
        db.withConnection conn: result = updateRecord(conn, rec)

+      proc `updateName`*[D: DbConnType](conn: D, rec: `t`): bool =
+        result = updateRecord(conn, rec)
+
      proc `createOrUpdateName`*(db: `dbType`, rec: `t`): `t` =
        db.inTransaction: result = createOrUpdateRecord(conn, rec)

+      proc `createOrUpdateName`*[D: DbConnType](conn: D, rec: `t`): `t` =
+        result = createOrUpdateRecord(conn, rec)
+
      proc `deleteName`*(db: `dbType`, rec: `t`): bool =
        db.withConnection conn: result = deleteRecord(conn, rec)

+      proc `deleteName`*[D: DbConnType](conn: D, rec: `t`): bool =
+        result = deleteRecord(conn, rec)
+
      proc `deleteName`*(db: `dbType`, id: `idType`): bool =
        db.withConnection conn: result = deleteRecord(conn, `t`, id)

+      proc `deleteName`*[D: DbConnType](conn: D, id: `idType`): bool =
+        result = deleteRecord(conn, `t`, id)
+
 macro generateLookup*(dbType: type, modelType: type, fields: seq[string]): untyped =
  ## Create a lookup procedure for a given set of field names. For example,
  ## given the TODO database demostrated above,
@@ -673,42 +810,49 @@ macro generateLookup*(dbType: type, modelType: type, fields: seq[string]): untyp
  ##
  ## .. code-block:: Nim
  ##    proc findTodoItemsByOwnerAndPriority*(db: SampleDB,
-  ##      owner: string, priority: int): seq[TodoItem]
+  ##      owner: string, priority: int,
+  ##      pagination = none[PaginationParams]()): PagedRecords[TodoItem]
+  ##    proc findTodoItemsByOwnerAndPriority*[D: DbConnType](conn: D,
+  ##      owner: string, priority: int,
+  ##      pagination = none[PaginationParams]()): PagedRecords[TodoItem]
+  ##
+  ## Use the `db` overload for standalone calls and the `conn` overload inside
+  ## `withConnection` or `inTransaction`.
  let fieldNames = fields[1].mapIt($it)
  let procName = ident("find" & pluralize($modelType.getType[1]) & "By" & fieldNames.mapIt(it.capitalize).join("And"))
-
-  # Create proc skeleton
-  result = quote do:
-    proc `procName`*(db: `dbType`): PagedRecords[`modelType`] =
-      db.withConnection conn: result = findRecordsBy(conn, `modelType`)
-
  var callParams = quote do: @[]

-  # Add dynamic parameters for the proc definition and inner proc call
+  # Add dynamic parameters for the generated proc and inner proc call.
  for n in fieldNames:
    let paramTuple = newNimNode(nnkPar)
    paramTuple.add(newColonExpr(ident("field"), newLit(identNameToDb(n))))
    paramTuple.add(newColonExpr(ident("value"), ident(n)))
-
-    # Add the parameter to the outer call (the generated proc)
-    # result[3] is ProcDef -> [3]: FormalParams
-    result[3].add(newIdentDefs(ident(n), ident("string")))
-
-    # Build up the AST for the inner procedure call
    callParams[1].add(paramTuple)

-  # Add the optional pagination parameters to the generated proc definition
-  result[3].add(newIdentDefs(
+  let dbProcDefAST = quote do:
+    proc `procName`*(db: `dbType`): PagedRecords[`modelType`] =
+      db.withConnection conn:
+        result = findRecordsBy(conn, `modelType`, `callParams`, pagination)
+
+  let connProcDefAST = quote do:
+    proc `procName`*[D: DbConnType](conn: D): PagedRecords[`modelType`] =
+      result = findRecordsBy(conn, `modelType`, `callParams.copyNimTree`, pagination)
+
+  for n in fieldNames:
+    dbProcDefAST[3].add(newIdentDefs(ident(n), ident("string")))
+    connProcDefAST[3].add(newIdentDefs(ident(n), ident("string")))
+
+  dbProcDefAST[3].add(newIdentDefs(
    ident("pagination"), newEmptyNode(),
    quote do: none[PaginationParams]()))

-  # Add the call params to the inner procedure call
-  # result[6][0][1][0][1] is
-  #   ProcDef -> [6]: StmtList (body) -> [0]: Command ->
-  #     [2]: StmtList (withConnection body) -> [0]: Asgn (result =) ->
-  #     [1]: Call (inner findRecords invocation)
-  result[6][0][2][0][1].add(callParams)
-  result[6][0][2][0][1].add(quote do: pagination)
+  connProcDefAST[3].add(newIdentDefs(
+    ident("pagination"), newEmptyNode(),
+    quote do: none[PaginationParams]()))
+
+  result = newStmtList()
+  result.add dbProcDefAST
+  result.add connProcDefAST

 macro generateProcsForFieldLookups*(dbType: type, modelsAndFields: openarray[tuple[t: type, fields: seq[string]]]): untyped =
  result = newStmtList()
@@ -718,32 +862,38 @@ macro generateProcsForFieldLookups*(dbType: type, modelsAndFields: openarray[tup
    let fieldNames = i[1][1][1].mapIt($it)

    let procName = ident("find" & $modelType & "sBy" & fieldNames.mapIt(it.capitalize).join("And"))
-
-    # Create proc skeleton
-    let procDefAST = quote do:
-      proc `procName`*(db: `dbType`): PagedRecords[`modelType`] =
-        db.withConnection conn: result = findRecordsBy(conn, `modelType`)
-
    var callParams = quote do: @[]

-    # Add dynamic parameters for the proc definition and inner proc call
+    # Add dynamic parameters for the generated proc and inner proc call.
    for n in fieldNames:
      let paramTuple = newNimNode(nnkPar)
      paramTuple.add(newColonExpr(ident("field"), newLit(identNameToDb(n))))
      paramTuple.add(newColonExpr(ident("value"), ident(n)))
-
-      procDefAST[3].add(newIdentDefs(ident(n), ident("string")))
      callParams[1].add(paramTuple)

-    # Add the optional pagination parameters to the generated proc definition
-    procDefAST[3].add(newIdentDefs(
+    let dbProcDefAST = quote do:
+      proc `procName`*(db: `dbType`): PagedRecords[`modelType`] =
+        db.withConnection conn:
+          result = findRecordsBy(conn, `modelType`, `callParams`, pagination)
+
+    let connProcDefAST = quote do:
+      proc `procName`*[D: DbConnType](conn: D): PagedRecords[`modelType`] =
+        result = findRecordsBy(conn, `modelType`, `callParams.copyNimTree`, pagination)
+
+    for n in fieldNames:
+      dbProcDefAST[3].add(newIdentDefs(ident(n), ident("string")))
+      connProcDefAST[3].add(newIdentDefs(ident(n), ident("string")))
+
+    dbProcDefAST[3].add(newIdentDefs(
      ident("pagination"), newEmptyNode(),
      quote do: none[PaginationParams]()))

-    procDefAST[6][0][1][0][1].add(callParams)
-    procDefAST[6][0][1][0][1].add(quote do: pagination)
+    connProcDefAST[3].add(newIdentDefs(
+      ident("pagination"), newEmptyNode(),
+      quote do: none[PaginationParams]()))

-    result.add procDefAST
+    result.add dbProcDefAST
+    result.add connProcDefAST

 macro generateJoinTableProcs*(
    dbType, model1Type, model2Type: type,
@@ -755,11 +905,19 @@ macro generateJoinTableProcs*(
  ## This macro will generate the following procedures:
  ##
  ## .. code-block:: Nim
-  ##    proc findTodoItemsByTimeEntry*(db: SampleDB, timeEntry: TimeEntry): seq[TodoItem]
-  ##    proc findTimeEntriesByTodoItem*(db: SampleDB, todoItem: TodoItem): seq[TimeEntry]
+  ##    proc getTodoItemsByTimeEntry*(db: SampleDB, timeEntry: TimeEntry,
+  ##      pagination = none[PaginationParams]()): PagedRecords[TodoItem]
+  ##    proc getTodoItemsByTimeEntry*[D: DbConnType](conn: D, timeEntry: TimeEntry,
+  ##      pagination = none[PaginationParams]()): PagedRecords[TodoItem]
+  ##    proc getTimeEntriesByTodoItem*(db: SampleDB, todoItem: TodoItem,
+  ##      pagination = none[PaginationParams]()): PagedRecords[TimeEntry]
+  ##    proc getTimeEntriesByTodoItem*[D: DbConnType](conn: D, todoItem: TodoItem,
+  ##      pagination = none[PaginationParams]()): PagedRecords[TimeEntry]
  ##
  ## `dbType` is expected to be some type that has a defined `withConnection`
  ## procedure (see `Database Object`_ for details).
+  ## As with the other generated helpers, use the connection overloads when
+  ## you are already inside `withConnection` or `inTransaction`.
  ##
  ## .. _Database Object: #database-object
  result = newStmtList()
@@ -791,6 +949,18 @@ macro generateJoinTableProcs*(
          id,
          pagination)

+    proc `getModel1Name`*[D: DbConnType](
+        conn: D,
+        id: `id2Type`,
+        pagination = none[PaginationParams]()): PagedRecords[`model1Type`] =
+      result = findViaJoinTable(
+        conn,
+        `joinTableNameNode`,
+        `model1Type`,
+        `model2Type`,
+        id,
+        pagination)
+
    proc `getModel1Name`*(
        db: `dbType`,
        rec: `model2Type`,
@@ -803,10 +973,21 @@ macro generateJoinTableProcs*(
          rec,
          pagination)

+    proc `getModel1Name`*[D: DbConnType](
+        conn: D,
+        rec: `model2Type`,
+        pagination = none[PaginationParams]()): PagedRecords[`model1Type`] =
+      result = findViaJoinTable(
+        conn,
+        `joinTableNameNode`,
+        `model1Type`,
+        rec,
+        pagination)
+
    proc `getModel2Name`*(
        db: `dbType`,
        id: `id1Type`,
-        pagination = none[PaginationParams]()): Pagedrecords[`model2Type`] =
+        pagination = none[PaginationParams]()): PagedRecords[`model2Type`] =
      db.withConnection conn:
        result = findViaJoinTable(
          conn,
@@ -816,10 +997,22 @@ macro generateJoinTableProcs*(
          id,
          pagination)

+    proc `getModel2Name`*[D: DbConnType](
+        conn: D,
+        id: `id1Type`,
+        pagination = none[PaginationParams]()): PagedRecords[`model2Type`] =
+      result = findViaJoinTable(
+        conn,
+        `joinTableNameNode`,
+        `model2Type`,
+        `model1Type`,
+        id,
+        pagination)
+
    proc `getModel2Name`*(
        db: `dbType`,
        rec: `model1Type`,
-        pagination = none[PaginationParams]()): Pagedrecords[`model2Type`] =
+        pagination = none[PaginationParams]()): PagedRecords[`model2Type`] =
      db.withConnection conn:
        result = findViaJoinTable(
          conn,
@@ -828,6 +1021,17 @@ macro generateJoinTableProcs*(
          rec,
          pagination)

+    proc `getModel2Name`*[D: DbConnType](
+        conn: D,
+        rec: `model1Type`,
+        pagination = none[PaginationParams]()): PagedRecords[`model2Type`] =
+      result = findViaJoinTable(
+        conn,
+        `joinTableNameNode`,
+        `model2Type`,
+        rec,
+        pagination)
+
    proc associate*(
        db: `dbType`,
        rec1: `model1Type`,
@@ -835,6 +1039,12 @@ macro generateJoinTableProcs*(
      db.withConnection conn:
        associate(conn, `joinTableNameNode`, rec1, rec2)

+    proc associate*[D: DbConnType](
+        conn: D,
+        rec1: `model1Type`,
+        rec2: `model2Type`): void =
+      associate(conn, `joinTableNameNode`, rec1, rec2)
+
    proc associate*(
        db: `dbType`,
        rec2: `model2Type`,
@@ -842,7 +1052,22 @@ macro generateJoinTableProcs*(
      db.withConnection conn:
        associate(conn, `joinTableNameNode`, rec1, rec2)

+    proc associate*[D: DbConnType](
+        conn: D,
+        rec2: `model2Type`,
+        rec1: `model1Type`): void =
+      associate(conn, `joinTableNameNode`, rec1, rec2)
+
 template inTransaction*(db, body: untyped) =
+  ## Execute `body` inside a transaction using a single connection bound to
+  ## `conn`.
+  ##
+  ## When calling generated Fiber ORM helpers inside this block, use the
+  ## overloads that take `conn: D` where `D: DbConnType`. Do not call the
+  ## overloads that take the outer database object, because those call
+  ## `withConnection` again and may acquire a different connection.
+  ## If you need to lock a PostgreSQL row before modifying it, use the
+  ## generated `get<RecordName>ForUpdate` helper.
  db.withConnection conn:
    conn.exec(sql"BEGIN TRANSACTION")
    try: