This module implements a threaded connection pool
This is currently very experimental.
Copyright (c) 2020 Bung
Types
DBPool = ref DBPoolObj
DBConn = ref DBConnObj
DBSqlPrepared = object pstmt: SqlPrepared dbConn: DBConn
Procs
proc newDBConn(writer: ptr Channel[DBResult]): DBConn {...}{.raises: [], tags: [TimeEffect].}
proc close(self: DBConn): owned(Future[void]) {...}{.raises: [Exception], tags: [TimeEffect, RootEffect, ReadIOEffect].}
proc expired(self: DBConn; timeout: Duration): bool {...}{.raises: [], tags: [TimeEffect].}
proc newDBPool(uriStr: string | Uri): Future[DBPool]
- min pool size max pool size max idle timeout exceed then close,affected freeConns,numOpen max open timeout max lifetime exceed then close,affected freeConns,numOpen
proc close(self: DBPool): Future[void] {...}{.raises: [Exception], tags: [RootEffect].}
proc fetchConn(self: DBPool): Future[DBConn] {...}{.raises: [Exception, ValueError], tags: [RootEffect, TimeEffect, ReadIOEffect, WriteIOEffect, IOEffect].}
- conn returns a newly-opened or new DBconn.
proc rawQuery(self: DBPool; query: string; onlyFirst: static[bool] = false): Future[ ResultSet[string]]
proc query(self: DBPool; pstmt: DBSqlPrepared; params: varargs[SqlParam, asParam]): Future[ResultSet[ResultValue]] {...}{. raises: [Exception, ValueError], tags: [RootEffect].}
proc rawExec(self: DBPool; query: string): Future[ResultSet[string]] {...}{. raises: [Exception, ValueError], tags: [RootEffect, TimeEffect, ReadIOEffect, WriteIOEffect, IOEffect].}
proc prepare(self: DBPool; query: string): Future[DBSqlPrepared] {...}{. raises: [Exception, ValueError], tags: [RootEffect, TimeEffect, ReadIOEffect, WriteIOEffect, IOEffect].}
proc finalize(self: DBPool; pstmt: DBSqlPrepared): Future[void] {...}{. raises: [Exception], tags: [RootEffect].}
proc reset(self: DBPool; pstmt: DBSqlPrepared): Future[void] {...}{. raises: [Exception], tags: [RootEffect].}
proc exec(conn: DBPool; query: SqlQuery; args: varargs[string, `$`]): Future[ ResultSet[string]] {...}{.raises: [Exception, ValueError], tags: [RootEffect, TimeEffect, ReadIOEffect, WriteIOEffect, IOEffect].}
proc query(conn: DBPool; query: SqlQuery; args: varargs[string, `$`]; onlyFirst: static[bool] = false): Future[ResultSet[string]]
proc tryQuery(conn: DBPool; query: SqlQuery; args: varargs[string, `$`]): Future[ bool] {...}{.raises: [Exception, ValueError], tags: [RootEffect, TimeEffect, ReadIOEffect, WriteIOEffect, IOEffect].}
- tries to execute the query and returns true if successful, false otherwise.
proc getRow(conn: DBPool; query: SqlQuery; args: varargs[string, `$`]): Future[ Row] {...}{.raises: [Exception, ValueError], tags: [RootEffect, TimeEffect, ReadIOEffect, WriteIOEffect, IOEffect].}
- Retrieves a single row. If the query doesn't return any rows, this proc will return a Row with empty strings for each column.
proc getAllRows(conn: DBPool; query: SqlQuery; args: varargs[string, `$`]): Future[ seq[Row]] {...}{.raises: [Exception, ValueError], tags: [RootEffect, TimeEffect, ReadIOEffect, WriteIOEffect, IOEffect].}
- executes the query and returns the whole result dataset.
proc getValue(conn: DBPool; query: SqlQuery; args: varargs[string, `$`]): Future[ string] {...}{.raises: [Exception, ValueError], tags: [RootEffect, TimeEffect, ReadIOEffect, WriteIOEffect, IOEffect].}
- executes the query and returns the first column of the first row of the result dataset. Returns "" if the dataset contains no rows or the database value is NULL.
proc tryInsertId(conn: DBPool; query: SqlQuery; args: varargs[string, `$`]): Future[ int64] {...}{.raises: [Exception, ValueError], tags: [RootEffect, TimeEffect, ReadIOEffect, WriteIOEffect, IOEffect].}
- executes the query (typically "INSERT") and returns the generated ID for the row or -1 in case of an error.
proc insertId(conn: DBPool; query: SqlQuery; args: varargs[string, `$`]): Future[ int64] {...}{.raises: [Exception, ValueError], tags: [RootEffect, TimeEffect, ReadIOEffect, WriteIOEffect, IOEffect].}
- executes the query (typically "INSERT") and returns the generated ID for the row.
proc tryInsert(conn: DBPool; query: SqlQuery; pkName: string; args: varargs[string, `$`]): Future[int64] {...}{. raises: [Exception, ValueError], tags: [RootEffect, TimeEffect, ReadIOEffect, WriteIOEffect, IOEffect].}
- same as tryInsertID
proc insert(conn: DBPool; query: SqlQuery; pkName: string; args: varargs[string, `$`]): Future[int64] {...}{. raises: [Exception, ValueError], tags: [RootEffect, TimeEffect, ReadIOEffect, WriteIOEffect, IOEffect].}
- same as insertId