Update documentation for new signature changes, bump version.
This commit is contained in:
81
README.rst
81
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,87 @@ 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 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`.
|
||||
|
||||
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.getTodoItem(todoId)
|
||||
item.priority += 1
|
||||
discard conn.updateTodoItem(item)
|
||||
|
||||
Object-Relational Modeling
|
||||
==========================
|
||||
@@ -133,11 +188,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 +223,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 +312,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 +326,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)
|
||||
|
||||
Reference in New Issue
Block a user