Under development — the help is being filled in plugin by plugin.
Help/Plugin reference/postgres
Plugin reference

postgres

PostgreSQL client over libpq — connection, Exec, and random-access result reads.

21 functionsnamespace postgressource plugins/postgres/PostgresPlugin.c

PostgreSQL client for DominScript over libpq — the official PostgreSQL C client library. Verb nomenclature mirrors the libpq names 1:1 (PQconnectdb → postgres.Connectdb, PQexec → postgres.Exec, PQgetvalue → postgres.GetValue, …), so the official libpq documentation maps directly onto the verbs.

Handle model

postgres.Connectdb returns a connection handle; postgres.Exec returns a result handle for every statement — including failed ones, which is the libpq convention: check postgres.ResultStatus, then read rows, then postgres.Clear the result. Result handles support random-access row/column reads (Ntuples × Nfields grid), unlike the mysql plugin's forward-only cursor. Each handle is single-owner (the plugin-family convention).

Connection lifecycle

Opening from a conninfo string, checking, resetting, closing.

postgres.Connectdb

postgres.Connectdb($ConnInfo) -> i64 conn

Opens a connection from a libpq conninfo string, e.g. "host=127.0.0.1 port=5432 dbname=test user=postgres" (mirror of PQconnectdb). Always returns a handle — check postgres.Status to see whether the connection actually succeeded.

Parameters
Parameter Type Description
ConnInfo string libpq conninfo string (key=value pairs).

postgres.Status

postgres.Status($Conn) -> i32 (0 = CONNECTION_OK)

Connection status (mirror of PQstatus); 0 means CONNECTION_OK.

Parameters
Parameter Type Description
Conn int Connection handle.
When to use

Always check Status right after Connectdb — Connectdb itself does not fail, the handle carries the error.

postgres.ErrorMessage

postgres.ErrorMessage($Conn) -> string

The connection-level error text (mirror of PQerrorMessage); "" when there is none.

Parameters
Parameter Type Description
Conn int Connection handle.

postgres.Db

postgres.Db($Conn) -> string

The database name of the connection (mirror of PQdb).

Parameters
Parameter Type Description
Conn int Connection handle.

postgres.BackendPid

postgres.BackendPid($Conn) -> i32

The server-side process id of the backend serving this connection (mirror of PQbackendPID).

Parameters
Parameter Type Description
Conn int Connection handle.

postgres.Reset

postgres.Reset($Conn) -> i32 0

Closes and re-establishes the same connection (mirror of PQreset).

Parameters
Parameter Type Description
Conn int Connection handle.

postgres.Finish

postgres.Finish($Conn) -> i32 0

Closes the connection and frees the handle (mirror of PQfinish). Valid on failed connections too.

Parameters
Parameter Type Description
Conn int Connection handle.

Statements

Executing SQL and inspecting the result status.

postgres.Exec

postgres.Exec($Conn, $Sql) -> i64 result

Executes an SQL statement and returns a result handle (mirror of PQexec) — for failed statements too; inspect postgres.ResultStatus. Clear every result with postgres.Clear.

Parameters
Parameter Type Description
Conn int Connection handle.
Sql string SQL statement text.

postgres.ResultStatus

postgres.ResultStatus($Result) -> i32

The result status code (mirror of PQresultStatus): 1 = PGRES_COMMAND_OK (no rows), 2 = PGRES_TUPLES_OK (rows available); higher values are errors.

Parameters
Parameter Type Description
Result int Result handle.

postgres.ResultErrorMessage

postgres.ResultErrorMessage($Result) -> string

The error text attached to a failed result (mirror of PQresultErrorMessage).

Parameters
Parameter Type Description
Result int Result handle.

postgres.CmdTuples

postgres.CmdTuples($Result) -> string

The affected-row count of the last command, as text (mirror of PQcmdTuples) — libpq reports this as a string.

Parameters
Parameter Type Description
Result int Result handle.

postgres.EscapeLiteral

postgres.EscapeLiteral($Conn, $Str) -> string

Escapes text as a complete SQL literal, quotes included (mirror of PQescapeLiteral).

Parameters
Parameter Type Description
Conn int Connection handle.
Str string Raw text to escape.
When to use

Escape every piece of untrusted text before formatting it into SQL. Note the result already includes the surrounding quotes.

Result grid

Random-access reads over the Ntuples × Nfields grid.

postgres.Ntuples

postgres.Ntuples($Result) -> i32

Number of rows in the result (mirror of PQntuples).

Parameters
Parameter Type Description
Result int Result handle.

postgres.Nfields

postgres.Nfields($Result) -> i32

Number of columns in the result (mirror of PQnfields).

Parameters
Parameter Type Description
Result int Result handle.

postgres.Fname

postgres.Fname($Result, $Col) -> string

Column name by 0-based index (mirror of PQfname).

Parameters
Parameter Type Description
Result int Result handle.
Col int 0-based column index.

postgres.Fnumber

postgres.Fnumber($Result, $Name) -> i32

Column index by name; -1 when not found (mirror of PQfnumber).

Parameters
Parameter Type Description
Result int Result handle.
Name string Column name.

postgres.GetValue

postgres.GetValue($Result, $Row, $Col) -> string

The cell at (row, column) as text (mirror of PQgetvalue); "" for NULL — use postgres.GetIsNull to distinguish.

Parameters
Parameter Type Description
Result int Result handle.
Row int 0-based row index.
Col int 0-based column index.

postgres.GetValueInt

postgres.GetValueInt($Result, $Row, $Col) -> i64

The cell at (row, column) parsed as an integer.

Parameters
Parameter Type Description
Result int Result handle.
Row int 0-based row index.
Col int 0-based column index.

postgres.GetIsNull

postgres.GetIsNull($Result, $Row, $Col) -> i32 1|0

1 when the cell is SQL NULL (mirror of PQgetisnull).

Parameters
Parameter Type Description
Result int Result handle.
Row int 0-based row index.
Col int 0-based column index.

postgres.GetLength

postgres.GetLength($Result, $Row, $Col) -> i32

The byte length of the cell's text (mirror of PQgetlength).

Parameters
Parameter Type Description
Result int Result handle.
Row int 0-based row index.
Col int 0-based column index.

postgres.Clear

postgres.Clear($Result) -> i32 0

Releases a result handle (mirror of PQclear). Clear every result, including failed ones.

Parameters
Parameter Type Description
Result int Result handle.

Worked example

plugin "../plugins/postgres/PostgresPlugin";
plugin "../plugins/print/PrintPlugin";

void main()
{
    i64 $C = postgres.Connectdb("host=127.0.0.1 port=5432 dbname=shop user=postgres");
    if (postgres.Status($C) != 0)
    {
        printf("connect failed: %s\n", postgres.ErrorMessage($C));
        postgres.Finish($C);
        return;
    }

    i64 $R = postgres.Exec($C, "SELECT id, name FROM people ORDER BY id");
    if (postgres.ResultStatus($R) == 2)  /* PGRES_TUPLES_OK */
    {
        i32 $I = 0;
        for ($I = 0; $I < postgres.Ntuples($R); $I += 1)
        {
            printf("row id=%d name=%s\n",
                   postgres.GetValueInt($R, $I, 0), postgres.GetValue($R, $I, 1));
        }
    }
    postgres.Clear($R);
    postgres.Finish($C);
}