diff options
Diffstat (limited to 'README.markdown')
| -rw-r--r-- | README.markdown | 158 |
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>. |