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>.
