disinterpreter / ml_pgsql

Postgre.SQL module for MTA-SA

Description

Simple module for MTA that provides Postgre.SQL client API.
I accept any support regarding the module development. Feel free to make PRs and Issues.

Installation

Information about Installation provided on the Releases page.

Functions

pg_conn function

Syntax

userdata pg_conn(string connection)

Description

Attempts to make connection with your Postgre.SQL server.

Parameters

string connection - connection query string.
Might look like:

• postgresql://USER:PASSWORD@IP:PORT/dbname?connect_timeout=3
• hostaddr=IP port=5432 dbname=DBNAME user=USERNAME password=PASSWORD

Return value

If the connection attempt is successfull, the function returns connection handle.
On the failure, the function returns 2 values:

• false (bool)
• Error message (string)

Example of usage

local conn,err = pg_conn("postgresql://user:[email protected]:5432/mydb?connect_timeout=3");	
if (err ~= nil) then
   print(err)
   return 1;
end

pg_query function

Syntax

userdata pg_query(userdata connection, string query)

Description

Sends query to the Postgre.SQL server with provided data. String escaping supports as well.

Parameters

userdata connection - connection handle (see pg_conn).
string query - query to send to the Postgre.SQL server.

Return value

If query was sent successfully, the function returns userdata with the query result handle.
On the failure, the function returns 2 values:

• false (bool)
• Error message (string)

Example of usage

local query,qerr = pg_query(conn, "SELECT $1 as a, $2 as b", -67, 2)
if (query == false)  then
    iprint(qerr)
end	

pg_poll function

Syntax

table pg_poll(userdata query)	

Description

Gets the data from the query result handle.

Parameters

userdata query - query result handle (see pg_query).

Return value

On the success, the function returns a table.
On the failure, the function returns 1 value:

• false (bool)

Example of usage

local query,qerr = pg_query(conn, "SELECT $1 as a, $2 as b", -67, 2)
if (query == false)  then
    iprint(qerr)
end
iprint(pg_poll(query));

pg_free function

Syntax

bool pg_free(userdata query)

Description

Frees memory after executing the query (in case it didn't happen before).

Parameters

userdata query - query result handle (see pg_query).

Return value

If the query result handle is valid, the function returns true (bool).
Otherwise the function returns false (bool).

Example of usage

local query,qerr = pg_query(conn, "SELECT $1 as a, $2 as b", -67, 2)
pg_free(query)

pg_exec function

Syntax

bool pg_exec(userdata connection, string query)

Description

Sends query to the Postgre.SQL server, except it doesn't return any data like pg_query.

Parameters

userdata connection - connection handle (see pg_conn).
string query - query to send to the Postgre.SQL server.

Return value

If query was successfully sent, the function returns userdata with the query result handle.
On the failure, the function returns 2 values:

• false (bool)
• Error message (string)

Example of usage

local exec = pg_exec(conn, "INSERT INTO users (name, password, money) VALUES ($1,$2,$3)", "a man", "mypasswd", "13");
iprint(exec);

pg_close function

Syntax

bool pg_close(userdata connection)

Description

Closes connection with the Posgre.SQL server.

Parameters

userdata connection - connection handle (see pg_conn).

Return value

If connection was closed successfully, the function returns true (bool).
On the failure, the function returns false (bool).

Example of usage

local conn,err = pg_conn("postgresql://user:[email protected]:5432/mydb?connect_timeout=3");

... (some code here)

pg_close(conn);

ml_pgsql's Issues

Async query

Need to add a callback to query

Linux

linux builds, when it will more stable.

Clientside transactions

There is good way to implement user transactions

Example API:

userdata pg_begin_tx(userdata connection)
Execute query CREATE TRANSACTION, set it status 'open' and save into local transactions storage.

userdata pg_rollback_tx(userdata transaction)
Get transaction from storage. If transaction is open and valid, rollback it with ROLLBACK and set 'rollbacked' status.
Abort transaction when has no instances in storage

userdata pg_commit_tx(userdata transaction)
Get transaction from storage and commit it with COMMIT if opened and set 'commited' status.
Abort transaction when has no instances in storage

Client database transactions control implementation may prevent problems with concurrent execution and add more performance features (for instance, execute whole transaction in one query)