From 1c8496a3ad909cc094b61aad83157bc185da0e44 Mon Sep 17 00:00:00 2001 From: Andreas Rumpf Date: Thu, 4 Feb 2010 00:47:59 +0100 Subject: [PATCH] cleanup of library docs --- src/db_postgres.nim | 82 +++++++++++++++++++++++++-------------------- 1 file changed, 46 insertions(+), 36 deletions(-) diff --git a/src/db_postgres.nim b/src/db_postgres.nim index cac5420d46..3296e688a7 100755 --- a/src/db_postgres.nim +++ b/src/db_postgres.nim @@ -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 +