initial commit

1 files changed, 158 insertions, 0 deletions

diff --git a/README.markdown b/README.markdown
new file mode 100644
index 0000000..3640704
--- /dev/null
+++ b/README.markdown
@@ -0,0 +1,158 @@
+lem-postgres
+============
+
+
+About
+-----
+
+lem-postgres is a [PostgreSQL][] library for the [Lua Event Machine][lem].
+It allows you to query PostgreSQL databases without blocking
+other coroutines.
+
+[lem]: https://github.com/esmil/lem
+[postgresql]: http://www.postgresql.org/
+
+Installation
+------------
+
+Get the source and do
+
+    make
+    make install
+
+This installs the library under `/usr/local/lib/lua/5.1/`.
+Use
+
+    make PREFIX=<your custom path> install
+
+to install to `<your custom path>/lib/lua/5.1/`.
+
+
+Usage
+-----
+
+Import the module using something like
+
+    local postgres = require 'lem.postgres'
+
+This sets `postgres` to a table with a single function.
+
+* __postgres.connect(conninfo)__
+
+  Connect to the database given by parameters in the `conninfo` string.
+  Returns a new database connection object on success,
+  or otherwise `nil` followed by an error message.
+
+The metatable of database connection objects can be found under
+__postgres.Connection__.
+
+Database connection objects has the following methods.
+
+* __db:close()__
+
+  Close the database connection.
+
+  Returns `true` on success or otherwise `nil, 'already closed'`,
+  if the connection was already closed.
+
+* __db:reset()__
+
+  Reset the database connection.
+
+  Returns `true` on success or otherwise `nil` followed by an error message.
+  If another coroutine is using this database connection the error message
+  will be `'busy'`.
+  If the connection is closed the error message will be `'closed'`.
+  If another coroutine closes this connection while the reset is going on
+  the error message be `'interrupted'`.
+
+* __db:exec(query, ...)__
+
+  Execute an SQL query. If the query string is parametized
+  (using $1, $2 etc.) the parameters must be given after the
+  query string.
+
+  If the query is a SELECT the result will be returned in a Lua table
+  with entries 1, 2, ... for each row.
+  Each row is again a Lua table with entries 1, 2, ... for each
+  returned column.
+
+  Returns `true` or the result of the SELECT statement on success,
+  or otherwise `nil` followed by an error message.
+  If another coroutine is using this database connection the error message
+  will be `'busy'`.
+  If the connection is closed the error message will be `'closed'`.
+  If another coroutine closes this connection while the reset is going on
+  the error message be `'interrupted'`.
+
+* __db:prepare(name, query)__
+
+  Creates a prepared SQL statement under the given name.
+
+  Returns `true` on success or otherwise `nil` followed by an error message.
+  If another coroutine is using this database connection the error message
+  will be `'busy'`.
+  If the connection is closed the error message will be `'closed'`.
+  If another coroutine closes this connection while the reset is going on
+  the error message be `'interrupted'`.
+
+* __db:run(name, ...)__
+
+  Runs the prepared statement given by the name. If the statement
+  is parameterized (using $1, $2 etc.) the parameters must be given
+  after the name of the statement.
+
+  If the prepared statement is a SELECT the result will be returned in
+  a Lua table with entries 1, 2, ... for each row.
+  Each row is again a Lua table with entries 1, 2, ... for each
+  returned column.
+
+  Returns `true` or the result of the SELECT statement on success,
+  or otherwise `nil` followed by an error message.
+  If another coroutine is using this database connection the error message
+  will be `'busy'`.
+  If the connection is closed the error message will be `'closed'`.
+  If another coroutine closes this connection while the reset is going on
+  the error message be `'interrupted'`.
+
+* __db:put(line)__
+
+  This method should be called after a `COPY <table> FROM STDIN`-query.
+  Call it once for each row in the table.
+
+  Returns `true` on success or otherwise `nil` followed by an error message.
+
+* __db:done([error])__
+
+  When all rows of a `COPY <table> FROM STDIN`-query have been sent to the
+  server, call this method to signal end of transmission.
+
+  If an error message is supplied this will signal an error to the server.
+
+  Returns `true` on success or otherwise `nil` followed by an error message.
+  Calling this method with an error argument will also cause it to return
+  `nil` followed by an error message.
+
+* __db:get()__
+
+  Call this method to receive rows after a `COPY <table> TO STDIN`-query.
+
+  Returns one complete line as a Lua string or `true` to signal end of
+  transmission.
+  On error `nil` followed by an error message will be returned.
+
+
+License
+-------
+
+lem-postgres is free software. It is distributed under the terms of the
+[GNU General Public License][gpl].
+
+[gpl]: http://www.fsf.org/licensing/licenses/gpl.html
+
+
+Contact
+-------
+
+Please send bug reports, patches, feature requests, praise and general gossip
+to me, Emil Renner Berthing <esmil@mailme.dk>.