lem-postgres

About

lem-postgres is a PostgreSQL library for the Lua Event Machine. It allows you to query PostgreSQL databases without blocking other coroutines.

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.

Contact

Please send bug reports, patches, feature requests, praise and general gossip to me, Emil Renner Berthing esmil@mailme.dk.