cleanup of library docs
This commit is contained in:
Andreas Rumpf
parent
e62ef0ff60
commit
eca05d2a33
13 changed files with 216 additions and 114 deletions
|
|
@ -1,14 +1,25 @@
|
|||
# Nimrod mySQL database wrapper
|
||||
# (c) 2009 Andreas Rumpf
|
||||
#
|
||||
#
|
||||
# Nimrod's Runtime Library
|
||||
# (c) Copyright 2010 Andreas Rumpf
|
||||
#
|
||||
# See the file "copying.txt", included in this
|
||||
# distribution, for details about the copyright.
|
||||
#
|
||||
|
||||
## A higher level `mySQL`:idx: database wrapper. The same interface is
|
||||
## implemented for other databases too.
|
||||
|
||||
import strutils, mysql
|
||||
|
||||
type
|
||||
TDbHandle* = PMySQL
|
||||
TRow* = seq[string]
|
||||
EDb* = object of EIO
|
||||
|
||||
proc dbError(db: TDbHandle) {.noreturn.} =
|
||||
TDbConn* = PMySQL ## encapsulates a database connection
|
||||
TRow* = seq[string] ## a row of a dataset
|
||||
EDb* = object of EIO ## exception that is raised if a database error occurs
|
||||
|
||||
TSqlQuery* = distinct string ## an SQL query string
|
||||
|
||||
proc dbError(db: TDbConn) {.noreturn.} =
|
||||
## raises an EDb exception.
|
||||
var e: ref EDb
|
||||
new(e)
|
||||
|
|
@ -23,13 +34,13 @@ proc dbError*(msg: string) {.noreturn.} =
|
|||
raise e
|
||||
|
||||
when false:
|
||||
proc dbQueryOpt*(db: TDbHandle, query: string, args: openarray[string]) =
|
||||
proc dbQueryOpt*(db: TDbConn, query: string, args: openarray[string]) =
|
||||
var stmt = mysql_stmt_init(db)
|
||||
if stmt == nil: dbError(db)
|
||||
if mysql_stmt_prepare(stmt, query, len(query)) != 0:
|
||||
dbError(db)
|
||||
var
|
||||
bind: seq[MYSQL_BIND]
|
||||
binding: seq[MYSQL_BIND]
|
||||
discard mysql_stmt_close(stmt)
|
||||
|
||||
proc dbQuote(s: string): string =
|
||||
|
|
@ -49,33 +60,16 @@ proc dbFormat(formatstr: string, args: openarray[string]): string =
|
|||
else:
|
||||
add(result, c)
|
||||
|
||||
proc dbTryQuery*(db: TDbHandle, query: string, args: openarray[string]): bool =
|
||||
proc TryQuery*(db: TDbConn, query: string, args: openarray[string]): bool =
|
||||
## tries to execute the query and returns true if successful, false otherwise.
|
||||
var q = dbFormat(query, args)
|
||||
return mysqlRealQuery(db, q, q.len) == 0'i32
|
||||
|
||||
proc dbQuery*(db: TDbHandle, query: string, args: openarray[string]) =
|
||||
proc Query*(db: TDbConn, query: string, args: openarray[string]) =
|
||||
## executes the query and raises EDB if not successful.
|
||||
var q = dbFormat(query, args)
|
||||
if mysqlRealQuery(db, q, q.len) != 0'i32: dbError(db)
|
||||
|
||||
proc dbTryInsertID*(db: TDbHandle, query: string,
|
||||
args: openarray[string]): int64 =
|
||||
var q = dbFormat(query, args)
|
||||
if mysqlRealQuery(db, q, q.len) != 0'i32:
|
||||
result = -1'i64
|
||||
else:
|
||||
result = mysql_insert_id(db)
|
||||
|
||||
proc dbInsertID*(db: TDbHandle, query: string, args: openArray[string]): int64 =
|
||||
result = dbTryInsertID(db, query, args)
|
||||
if result < 0: dbError(db)
|
||||
|
||||
proc dbQueryAffectedRows*(db: TDbHandle, query: string,
|
||||
args: openArray[string]): int64 =
|
||||
## runs the query (typically "UPDATE") and returns the
|
||||
## number of affected rows
|
||||
dbQuery(db, query, args)
|
||||
result = mysql_affected_rows(db)
|
||||
|
||||
|
||||
proc newRow(L: int): TRow =
|
||||
newSeq(result, L)
|
||||
for i in 0..L-1: result[i] = ""
|
||||
|
|
@ -84,33 +78,13 @@ proc properFreeResult(sqlres: PMYSQL_RES, row: cstringArray) =
|
|||
if row != nil:
|
||||
while mysqlFetchRow(sqlres) != nil: nil
|
||||
mysqlFreeResult(sqlres)
|
||||
|
||||
proc dbGetAllRows*(db: TDbHandle, query: string,
|
||||
args: openarray[string]): seq[TRow] =
|
||||
result = @[]
|
||||
dbQuery(db, query, args)
|
||||
var sqlres = mysqlUseResult(db)
|
||||
if sqlres != nil:
|
||||
var L = int(mysql_num_fields(sqlres))
|
||||
var row: cstringArray
|
||||
var j = 0
|
||||
while true:
|
||||
row = mysqlFetchRow(sqlres)
|
||||
if row == nil: break
|
||||
setLen(result, j+1)
|
||||
newSeq(result[j], L)
|
||||
for i in 0..L-1: result[j][i] = $row[i]
|
||||
inc(j)
|
||||
mysqlFreeResult(sqlres)
|
||||
|
||||
iterator dbRows*(db: TDbHandle, query: string,
|
||||
args: openarray[string]): TRow =
|
||||
for r in items(dbGetAllRows(db, query, args)): yield r
|
||||
|
||||
iterator dbFastRows*(db: TDbHandle, query: string,
|
||||
args: openarray[string]): TRow =
|
||||
# this is carefully optimized, so that the memory is reused!
|
||||
dbQuery(db, query, args)
|
||||
iterator FastRows*(db: TDbConn, query: string,
|
||||
args: openarray[string]): TRow =
|
||||
## executes the query and iterates over the result dataset. This is very
|
||||
## fast, but potenially dangerous: If the for-loop-body executes another
|
||||
## query, the results can be undefined. For Postgres it is safe though.
|
||||
Query(db, query, args)
|
||||
var sqlres = mysqlUseResult(db)
|
||||
if sqlres != nil:
|
||||
var L = int(mysql_num_fields(sqlres))
|
||||
|
|
@ -125,21 +99,75 @@ iterator dbFastRows*(db: TDbHandle, query: string,
|
|||
yield result
|
||||
properFreeResult(sqlres, row)
|
||||
|
||||
proc dbGetValue*(db: TDbHandle, query: string,
|
||||
args: openarray[string]): string =
|
||||
proc GetAllRows*(db: TDbConn, query: string,
|
||||
args: openarray[string]): seq[TRow] =
|
||||
## executes the query and returns the whole result dataset.
|
||||
result = @[]
|
||||
Query(db, query, args)
|
||||
var sqlres = mysqlUseResult(db)
|
||||
if sqlres != nil:
|
||||
var L = int(mysql_num_fields(sqlres))
|
||||
var row: cstringArray
|
||||
var j = 0
|
||||
while true:
|
||||
row = mysqlFetchRow(sqlres)
|
||||
if row == nil: break
|
||||
setLen(result, j+1)
|
||||
newSeq(result[j], L)
|
||||
for i in 0..L-1: result[j][i] = $row[i]
|
||||
inc(j)
|
||||
mysqlFreeResult(sqlres)
|
||||
|
||||
iterator Rows*(db: TDbConn, query: string,
|
||||
args: openarray[string]): TRow =
|
||||
## same as `FastRows`, but slower and safe.
|
||||
for r in items(GetAllRows(db, query, args)): yield r
|
||||
|
||||
proc GetValue*(db: TDbConn, query: string,
|
||||
args: openarray[string]): string =
|
||||
## executes the query and returns the result dataset's the first column
|
||||
## of the first row. Returns "" if the dataset contains no rows. This uses
|
||||
## `FastRows`, so it inherits its fragile behaviour.
|
||||
result = ""
|
||||
for row in dbFastRows(db, query, args):
|
||||
for row in FastRows(db, query, args):
|
||||
result = row[0]
|
||||
break
|
||||
|
||||
proc dbClose*(db: TDbHandle) =
|
||||
proc TryInsertID*(db: TDbConn, query: string,
|
||||
args: openarray[string]): int64 =
|
||||
## executes the query (typically "INSERT") and returns the
|
||||
## generated ID for the row or -1 in case of an error.
|
||||
var q = dbFormat(query, args)
|
||||
if mysqlRealQuery(db, q, q.len) != 0'i32:
|
||||
result = -1'i64
|
||||
else:
|
||||
result = mysql_insert_id(db)
|
||||
|
||||
proc InsertID*(db: TDbConn, query: string, args: openArray[string]): int64 =
|
||||
## executes the query (typically "INSERT") and returns the
|
||||
## generated ID for the row.
|
||||
result = TryInsertID(db, query, args)
|
||||
if result < 0: dbError(db)
|
||||
|
||||
proc QueryAffectedRows*(db: TDbConn, query: string,
|
||||
args: openArray[string]): int64 =
|
||||
## runs the query (typically "UPDATE") and returns the
|
||||
## number of affected rows
|
||||
Query(db, query, args)
|
||||
result = mysql_affected_rows(db)
|
||||
|
||||
proc Close*(db: TDbConn) =
|
||||
## closes the database connection.
|
||||
if db != nil: mysqlClose(db)
|
||||
|
||||
proc dbOpen*(connection, user, password, database: string): TDbHandle =
|
||||
proc Open*(connection, user, password, database: string): TDbConn =
|
||||
## opens a database connection. Raises `EDb` if the connection could not
|
||||
## be established.
|
||||
result = mysqlInit(nil)
|
||||
if result != nil:
|
||||
if mysqlRealConnect(result, "", user, password, database,
|
||||
0'i32, nil, 0) == nil:
|
||||
dbClose(result)
|
||||
result = nil
|
||||
if result == nil: dbError("could not open database connection")
|
||||
if mysqlRealConnect(result, "", user, password, database,
|
||||
0'i32, nil, 0) == nil:
|
||||
var errmsg = $mysql_error(result)
|
||||
Close(result)
|
||||
dbError(errmsg)
|
||||
|
||||
|
|
|
|||
|
|
@ -1,20 +1,31 @@
|
|||
# Nimrod PostgreSQL database wrapper
|
||||
# (c) 2010 Andreas Rumpf
|
||||
#
|
||||
#
|
||||
# Nimrod's Runtime Library
|
||||
# (c) Copyright 2010 Andreas Rumpf
|
||||
#
|
||||
# See the file "copying.txt", included in this
|
||||
# distribution, for details about the copyright.
|
||||
#
|
||||
|
||||
## A higher level `PostgreSQL`:idx: database wrapper. This interface
|
||||
## is implemented for other databases too.
|
||||
|
||||
import strutils, postgres
|
||||
|
||||
type
|
||||
TDbConn* = PPGconn ## encapsulates a database connection
|
||||
TDbConn* = PPGconn ## encapsulates a database connection
|
||||
TRow* = seq[string] ## a row of a dataset
|
||||
EDb* = object of EIO ## exception that is raised if a database error occurs
|
||||
|
||||
TSqlQuery* = distinct string ## an SQL query string
|
||||
|
||||
proc sql*(query: string): TSqlQuery {.noSideEffect, inline.} =
|
||||
## constructs a TSqlQuery from the string `query`: If assertions are turned
|
||||
## off, it does nothing. If assertions are turned on, the string is checked
|
||||
## for SQL security holes. This is supposed to be used as a
|
||||
## raw-string-literal modifier: ``sql"update user set counter = counter + 1"``
|
||||
## constructs a TSqlQuery from the string `query`. This is supposed to be
|
||||
## used as a raw-string-literal modifier:
|
||||
## ``sql"update user set counter = counter + 1"``
|
||||
##
|
||||
## If assertions are turned off, it does nothing. If assertions are turned
|
||||
## on, later versions will check the string for valid syntax.
|
||||
result = TSqlQuery(query)
|
||||
|
||||
proc dbError(db: TDbConn) {.noreturn.} =
|
||||
|
|
@ -32,8 +43,6 @@ proc dbError*(msg: string) {.noreturn.} =
|
|||
raise e
|
||||
|
||||
proc dbQuote(s: string): string =
|
||||
#if s.len > 0 and allCharsInSet(s, {'0'..'9'}): result = s
|
||||
#else:
|
||||
result = "'"
|
||||
for c in items(s):
|
||||
if c == '\'': add(result, "''")
|
||||
|
|
@ -50,15 +59,15 @@ proc dbFormat(formatstr: TSqlQuery, args: openarray[string]): string =
|
|||
else:
|
||||
add(result, c)
|
||||
|
||||
proc dbTryQuery*(db: TDbConn, query: TSqlQuery,
|
||||
args: openarray[string]): bool =
|
||||
proc TryQuery*(db: TDbConn, query: TSqlQuery,
|
||||
args: openarray[string]): bool =
|
||||
## tries to execute the query and returns true if successful, false otherwise.
|
||||
var q = dbFormat(query, args)
|
||||
var res = PQExec(db, q)
|
||||
result = PQresultStatus(res) == PGRES_COMMAND_OK
|
||||
PQclear(res)
|
||||
|
||||
proc dbQuery*(db: TDbConn, query: TSqlQuery, args: openarray[string]) =
|
||||
proc Query*(db: TDbConn, query: TSqlQuery, args: openarray[string]) =
|
||||
## executes the query and raises EDB if not successful.
|
||||
var q = dbFormat(query, args)
|
||||
var res = PQExec(db, q)
|
||||
|
|
@ -81,8 +90,8 @@ proc setRow(res: PPGresult, r: var TRow, line, cols: int) =
|
|||
var x = PQgetvalue(res, line, col)
|
||||
add(r[col], x)
|
||||
|
||||
iterator dbFastRows*(db: TDbConn, query: TSqlQuery,
|
||||
args: openarray[string]): TRow =
|
||||
iterator FastRows*(db: TDbConn, query: TSqlQuery,
|
||||
args: openarray[string]): TRow =
|
||||
## executes the query and iterates over the result dataset. This is very
|
||||
## fast, but potenially dangerous: If the for-loop-body executes another
|
||||
## query, the results can be undefined. For Postgres it is safe though.
|
||||
|
|
@ -94,49 +103,48 @@ iterator dbFastRows*(db: TDbConn, query: TSqlQuery,
|
|||
yield result
|
||||
PQclear(res)
|
||||
|
||||
proc dbGetAllRows*(db: TDbConn, query: TSqlQuery,
|
||||
args: openarray[string]): seq[TRow] =
|
||||
proc GetAllRows*(db: TDbConn, query: TSqlQuery,
|
||||
args: openarray[string]): seq[TRow] =
|
||||
## executes the query and returns the whole result dataset.
|
||||
result = @[]
|
||||
for r in dbFastRows(db, query, args):
|
||||
for r in FastRows(db, query, args):
|
||||
result.add(r)
|
||||
|
||||
iterator dbRows*(db: TDbConn, query: TSqlQuery,
|
||||
args: openarray[string]): TRow =
|
||||
## same as `dbFastRows`, but slower and safe.
|
||||
for r in items(dbGetAllRows(db, query, args)): yield r
|
||||
iterator Rows*(db: TDbConn, query: TSqlQuery,
|
||||
args: openarray[string]): TRow =
|
||||
## same as `FastRows`, but slower and safe.
|
||||
for r in items(GetAllRows(db, query, args)): yield r
|
||||
|
||||
proc dbGetValue*(db: TDbConn, query: TSqlQuery,
|
||||
args: openarray[string]): string =
|
||||
proc GetValue*(db: TDbConn, query: TSqlQuery,
|
||||
args: openarray[string]): string =
|
||||
## executes the query and returns the result dataset's the first column
|
||||
## of the first row. Returns "" if the dataset contains no rows. This uses
|
||||
## `dbFastRows`, so it inherits its fragile behaviour.
|
||||
## of the first row. Returns "" if the dataset contains no rows.
|
||||
var x = PQgetvalue(setupQuery(db, query, args), 0, 0)
|
||||
result = if isNil(x): "" else: $x
|
||||
|
||||
proc dbTryInsertID*(db: TDbConn, query: TSqlQuery,
|
||||
args: openarray[string]): int64 =
|
||||
proc TryInsertID*(db: TDbConn, query: TSqlQuery,
|
||||
args: openarray[string]): int64 =
|
||||
## executes the query (typically "INSERT") and returns the
|
||||
## generated ID for the row or -1 in case of an error. For Postgre this adds
|
||||
## ``RETURNING id`` to the query, so it only works if your primary key is
|
||||
## named ``id``.
|
||||
var val = dbGetValue(db, TSqlQuery(string(query) & " RETURNING id"), args)
|
||||
var val = GetValue(db, TSqlQuery(string(query) & " RETURNING id"), args)
|
||||
if val.len > 0:
|
||||
result = ParseBiggestInt(val)
|
||||
else:
|
||||
result = -1
|
||||
|
||||
proc dbInsertID*(db: TDbConn, query: TSqlQuery,
|
||||
args: openArray[string]): int64 =
|
||||
proc InsertID*(db: TDbConn, query: TSqlQuery,
|
||||
args: openArray[string]): int64 =
|
||||
## executes the query (typically "INSERT") and returns the
|
||||
## generated ID for the row. For Postgre this adds
|
||||
## ``RETURNING id`` to the query, so it only works if your primary key is
|
||||
## named ``id``.
|
||||
result = dbTryInsertID(db, query, args)
|
||||
result = TryInsertID(db, query, args)
|
||||
if result < 0: dbError(db)
|
||||
|
||||
proc dbQueryAffectedRows*(db: TDbConn, query: TSqlQuery,
|
||||
args: openArray[string]): int64 =
|
||||
proc QueryAffectedRows*(db: TDbConn, query: TSqlQuery,
|
||||
args: openArray[string]): int64 =
|
||||
## executes the query (typically "UPDATE") and returns the
|
||||
## number of affected rows.
|
||||
var q = dbFormat(query, args)
|
||||
|
|
@ -145,12 +153,14 @@ proc dbQueryAffectedRows*(db: TDbConn, query: TSqlQuery,
|
|||
result = parseBiggestInt($PQcmdTuples(res))
|
||||
PQclear(res)
|
||||
|
||||
proc dbClose*(db: TDbConn) =
|
||||
proc Close*(db: TDbConn) =
|
||||
## closes the database connection.
|
||||
if db != nil: PQfinish(db)
|
||||
|
||||
proc dbOpen*(connection, user, password, database: string): TDbConn =
|
||||
## opens a database connection.
|
||||
proc Open*(connection, user, password, database: string): TDbConn =
|
||||
## opens a database connection. Raises `EDb` if the connection could not
|
||||
## be established.
|
||||
result = PQsetdbLogin(nil, nil, nil, nil, database, user, password)
|
||||
if PQStatus(result) != CONNECTION_OK: dbError(result) # result = nil
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#
|
||||
#
|
||||
# Nimrod's Runtime Library
|
||||
# (c) Copyright 2009 Andreas Rumpf
|
||||
# (c) Copyright 2010 Andreas Rumpf
|
||||
#
|
||||
# See the file "copying.txt", included in this
|
||||
# distribution, for details about the copyright.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#
|
||||
#
|
||||
# Nimrod's Runtime Library
|
||||
# (c) Copyright 2009 Andreas Rumpf
|
||||
# (c) Copyright 2010 Andreas Rumpf
|
||||
#
|
||||
# See the file "copying.txt", included in this
|
||||
# distribution, for details about the copyright.
|
||||
|
|
@ -16,6 +16,11 @@
|
|||
##
|
||||
## Currently only requesting URLs is implemented. The implementation depends
|
||||
## on the libcurl library!
|
||||
##
|
||||
## **Deprecated since version 0.8.0:** Use the httpclient module instead.
|
||||
##
|
||||
|
||||
{.deprecated.}
|
||||
|
||||
import libcurl, streams
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue