Improved postgres docs and added untestable tests.

lib/impure/db_postgres.nim

@@ -10,60 +10,56 @@
 ## A higher level `PostgreSQL`:idx: database wrapper. This interface
 ## is implemented for other databases also.
 ##
-##  **Note**: There are two approaches to **parameter substitution** in this module
+## Parameter substitution
-##  1.  ``SqlQuery`` using ``?,?,?,...`` (same as the other db_xxxx modules)
+## ----------------------
+##
+## All ``db_*`` modules support the same form of parameter substitution.
+## That is, using the ``?`` (question mark) to signify the place where a
+## value should be placed. For example:
 ##
 ## .. code-block:: Nim
 ##     sql"INSERT INTO myTable (colA, colB, colC) VALUES (?, ?, ?)"
-##  2.  ``SqlPrepared``  using ``$1,$2,$3,...``  (the Postgres way, using numbered parameters)
+##
+## **Note**: There are two approaches to parameter substitution support by
+## this module.
+##
+## 1.  ``SqlQuery`` using ``?, ?, ?, ...`` (same as all the ``db_*`` modules)
+##
+## 2. ``SqlPrepared`` using ``$1, $2, $3, ...``
 ##
 ##  .. code-block:: Nim
-##   prepare(theDb, "MyExampleInsert",
+##   prepare(db, "myExampleInsert",
 ##           sql"""INSERT INTO myTable
 ##                 (colA, colB, colC)
 ##                 VALUES ($1, $2, $3)""",
 ##           3)
 ##
-## Example:
+## Examples
+## --------
+##
+## Opening a connection to a database
+## ==================================
 ##
 ## .. code-block:: Nim
+##     import db_postgres
+##     let db = open("localhost", "user", "password", "dbname")
+##     db.close()
 ##
-##  import db_postgres, math
+## Creating a table
+## ================
 ##
-##  let theDb = open("localhost", "nim", "nim", "test")
+## .. code-block:: Nim
+##      db.exec(sql"DROP TABLE IF EXISTS myTable")
+##      db.exec(sql("""CREATE TABLE myTable (
+##                       id integer,
+##                       name varchar(50) not null)"""))
 ##
-##  theDb.exec(sql"Drop table if exists myTestTbl")
+## Inserting data
-##  theDb.exec(sql("""create table myTestTbl (
+## ==============
-##     Id    SERIAL PRIMARY KEY,
-##     Name  VARCHAR(50) NOT NULL,
-##     i     INTEGER,
-##     f     NUMERIC(18,10))"""))
 ##
-##  var psql: SqlPrepared = theDb.prepare("testSql",
+## .. code-block:: Nim
-##                                sql"""INSERT INTO myTestTbl (name,i,f)
+##     db.exec(sql"INSERT INTO myTable (id, name) VALUES (0, ?)",
-##                                      VALUES ($1,$2,$3)""", 3)
+##             "Dominik")
-##  theDb.exec(sql"START TRANSACTION")
-##  for i in 1..1000:
-##    if i %% 2 == 0:
-##      # using Postgres prepared statement (SqlPrepare)
-##      theDb.exec(psql, "Item#" & $i, $i, $sqrt(i.float))
-##    else:
-##      # using SqlQuery
-##      theDb.exec(sql"INSERT INTO myTestTbl (name,i,f) VALUES (?,?,?)",
-##              "Item#" & $i, $i, $sqrt(i.float))
-##  theDb.exec(sql"COMMIT")
-##
-##  for x in theDb.fastRows(sql"select * from myTestTbl"):
-##    echo x
-##
-##  let id = theDb.tryInsertId(sql"""INSERT INTO myTestTbl
-##                                   (name,i,f)
-##                                   VALUES (?,?,?)""",
-##                             "Item#1001", 1001, sqrt(1001.0))
-##  echo "Inserted item: ",
-##        theDb.getValue(sql"SELECT name FROM myTestTbl WHERE id=?", id)
-##
-##  theDb.close()
 import strutils, postgres
 
 type
@@ -382,3 +378,6 @@ proc setEncoding*(connection: DbConn, encoding: string): bool {.
   ## sets the encoding of a database connection, returns true for
   ## success, false for failure.
   return pqsetClientEncoding(connection, encoding) == 0
+
+
+# Tests are in ../../tests/untestable/tpostgres.

tests/testament/categories.nim

@@ -394,6 +394,9 @@ proc processCategory(r: var TResults, cat: Category, options: string, fileGlob:
     testNimblePackages(r, cat, pfExtraOnly)
   of "nimble-all":
     testNimblePackages(r, cat, pfAll)
+  of "untestable":
+    # We can't test it because it depends on a third party.
+    discard # TODO: Move untestable tests to someplace else, i.e. nimble repo.
   else:
     for name in os.walkFiles("tests" & DirSep &.? cat.string / fileGlob):
       testSpec r, makeTest(name, options, cat)