Merge branch 'devel' of https://github.com/nim-lang/Nim into devel

src/db_postgres.nim

@@ -10,6 +10,9 @@
 ## A higher level `PostgreSQL`:idx: database wrapper. This interface
 ## is implemented for other databases also.
 ##
+## See also: `db_odbc <db_odbc.html>`_, `db_sqlite <db_sqlite.html>`_,
+## `db_mysql <db_mysql.html>`_.
+##
 ## Parameter substitution
 ## ----------------------
 ##
@@ -27,7 +30,7 @@
 ##
 ## 2. ``SqlPrepared`` using ``$1, $2, $3, ...``
 ##
-##  .. code-block:: Nim
+## .. code-block:: Nim
 ##   prepare(db, "myExampleInsert",
 ##           sql"""INSERT INTO myTable
 ##                 (colA, colB, colC)
@@ -162,8 +165,10 @@ proc setupQuery(db: DbConn, stmtName: SqlPrepared,
 
 proc prepare*(db: DbConn; stmtName: string, query: SqlQuery;
               nParams: int): SqlPrepared =
+  ## Creates a new ``SqlPrepared`` statement. Parameter substitution is done
+  ## via ``$1``, ``$2``, ``$3``, etc.
   if nParams > 0 and not string(query).contains("$1"):
-    dbError("""parameter substitution expects "$1" """)
+    dbError("parameter substitution expects \"$1\"")
   var res = pqprepare(db, stmtName, query.string, int32(nParams), nil)
   if pqResultStatus(res) != PGRES_COMMAND_OK: dbError(db)
   return SqlPrepared(stmtName)
@@ -282,6 +287,15 @@ proc getValue*(db: DbConn, query: SqlQuery,
   var x = pqgetvalue(setupQuery(db, query, args), 0, 0)
   result = if isNil(x): "" else: $x
 
+proc getValue*(db: DbConn, stmtName: SqlPrepared,
+               args: varargs[string, `$`]): string {.
+               tags: [ReadDbEffect].} =
+  ## 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.
+  var x = pqgetvalue(setupQuery(db, stmtName, args), 0, 0)
+  result = if isNil(x): "" else: $x
+
 proc tryInsertID*(db: DbConn, query: SqlQuery,
                   args: varargs[string, `$`]): int64 {.
                   tags: [WriteDbEffect].}=