(index ("open" 0) ("db-dbtype" 1019) ("db-conn" 1223) ("close" 1589) ("exec" 1967) ("for-each-row" 2444) ("get-rows" 3303) ("get-one-row" 4017) ("get-one" 5024) ("now" 5806))
(def (sig (procedure "(open dbtype dbinit)" (id open))) (p "Opens a connection to the database of type " (tt "dbtype") " with connection information in the " (tt "dbinit") " alist.  An opaque " (tt "db") " handle is returned.") (p "The following symbols are accepted as " (tt "dbtype") ":") (ul (li (tt "sqlite3")) (li (tt "pg")) (li (tt "mysql"))) (p "Depending on the backend, the " (tt "dbinit") " alist supports the following keys:") (ul (li (tt "dbname") ": The database name (pg), schema name (mysql) or filename (sqlite3).") (li (tt "host") ": The host to connect to (pg, mysql).") (li (tt "user") ": The user to connect as (pg, mysql).") (li (tt "password") ": The " (tt "user") "'s password (pg, mysql).")) (p "If any are omitted, the database driver's defaults are used.  In the case of MySQL, this means " (tt ".my.cnf") " is consulted, and in the case of Postgres, " (tt ".pgpass") " and various " (tt "PG") " environment variables are consulted.  Check the manual of your database system for more info."))
(def (sig (procedure "(db-dbtype db)" (id db-dbtype))) (p "Returns the symbol of " (tt "db") "'s backend driver, as it was supplied to the " (tt "open") " call which returned the " (tt "db") " object."))
(def (sig (procedure "(db-conn db)" (id db-conn))) (p "Returns the underlying backend-specific raw connection object of " (tt "db") "'s backend driver, as created by the " (tt "open") " call which returned the " (tt "db") " object.") (p "This can be used whenever some database-specific feature is needed for which this egg does not (yet) provide an abstraction."))
(def (sig (procedure "(close db)" (id close))) (p "Close the connection to " (tt "db") ".") (p "NOTE: In the case of MySQL, this is a no-op, because the underlying driver egg doesn't support closing connections explicitly.  It does register a finalizer, so you should be able to force it by losing all references to the " (tt "db") " object and forcing a garbage collection."))
(def (sig (procedure "(exec db query . params)" (id exec))) (p "Execute the " (tt "query") " for its side-effects on the database connection " (tt "db") ".  " (tt "params") " should be rest arguments which replace the corresponding \"" (tt "?") "\" placeholders in " (tt "query") ".") (p "Example:") (highlight scheme "(define mydb (open 'sqlite3 '((dbname . \"/tmp/db\"))))\n(exec mydb\n      \"INSERT INTO films (name, year) VALUES (?, ?)\"\n      \"The Godfather\" 1972)"))
(def (sig (procedure "(for-each-row proc db query . params)" (id for-each-row))) (p "Execute the " (tt "query") " on the database connection " (tt "db") " and invoke the procedure " (tt "proc") " for every row.  " (tt "params") " should be rest arguments which replace the corresponding \"" (tt "?") "\"  placeholders in " (tt "query") ".") (p "The procedure should accept one argument, which will be a vector containing the tuple's fields.") (p "Example:") (highlight scheme "(define mydb (open 'sqlite3 '((dbname . \"/tmp/db\"))))\n(for-each-row (lambda (tuple)\n\t        (print (vector-ref tuple 0) \" -- \" (vector-ref tuple 1)))\n              mydb\n              \"SELECT name, year FROM films WHERE name = ? OR name = ?\"\n              \"The Godfather\" \"Alien\")\n\n;; This will print something like:\n;; The Godfather -- 1972\n;; Alien -- 1979"))
(def (sig (procedure "(get-rows db query . params)" (id get-rows))) (p "Execute the " (tt "query") " on the database connection " (tt "db") " and return the entire set, represented as a list of tuple vectors.  The " (tt "params") " should be rest arguments which replace the corresponding \"" (tt "?") "\" placeholders in " (tt "query") ".") (p "Example:") (highlight scheme "(define mydb (open 'sqlite3 '((dbname . \"/tmp/db\"))))\n(let ((tuples (get-rows\n                mydb\n                \"SELECT name, year FROM films WHERE name = ? OR name = ?\"\n                \"The Godfather\" \"Alien\")))\n  (pp tuples))\n;; This will print something like:\n;; (#(\"The Godfather\" 1972)\n;;   (\"Alien\" 1979))"))
(def (sig (procedure "(get-one-row db query . params)" (id get-one-row))) (p "Execute the " (tt "query") " on the database connection " (tt "db") " and return the first row in the set.  The " (tt "params") " should be rest arguments which replace the corresponding \"" (tt "?") "\"  placeholders in " (tt "query") ".") (p "The returned row is represented by a vector with the row's fields or " (tt "#f") " if the query returns an empty set.") (p "NOTE: This will still retrieve the entire result set, despite only returning the one row.  So it's still up to you to add " (tt "LIMIT 1") " or " (tt "FETCH FIRST ROW ONLY") " to your query!") (p "Example:") (highlight scheme "(define mydb (open 'sqlite3 '((dbname . \"/tmp/db\"))))\n(let ((tuple (get-one-row\n               mydb\n               \"SELECT name, year FROM films WHERE name = ?\"\n               \"The Godfather\")))\n  (print (vector-ref tuple 0) \" -- \" (vector-ref tuple 1)))\n;; This will print something like:\n;; The Godfather -- 1972"))
(def (sig (procedure "(get-one db query . params)" (id get-one))) (p "Like " (tt "get-one-row") ", except it returns only the first " (i "field") " of the first row in the set (or " (tt "#f") " if the set is empty).") (p "NOTE: This will still retrieve the entire result set, despite only returning the one row.  So it's still up to you to add " (tt "LIMIT 1") " or " (tt "FETCH FIRST ROW ONLY") " to your query!") (p "Example:") (highlight scheme "(define mydb (open 'sqlite3 '((dbname . \"/tmp/db\"))))\n(let ((tuple (get-one-row\n               mydb\n               \"SELECT name, year FROM films WHERE name = ?\"\n               \"The Godfather\")))\n  (print (vector-ref tuple 0) \" -- \" (vector-ref tuple 1)))\n;; This will print something like:\n;; The Godfather -- 1972"))
(def (sig (procedure "(now db)" (id now))) (p "Returns a string representing the current date/time, using the syntax required by the database to which " (tt "db") " is a connection."))
