pgsql (PostgreSQL) module for Qore
by David Nichols / Qore Technologies, s.r.o.

Requires qore 0.9+ and PostgreSQL client headers and libraries to build

This module is released under a choice of two licenses: LGPL 2.1 and MIT; see
COPYING.LGPL and COPYING.MIT for more information

The driver supports the following features:
* All builtin PostgreSQL data types are supported including:
  - Basic types: boolean, bytea, int2, int4, int8, float4, float8, numeric, money
  - Text types: text, varchar, char, name
  - Date/time types: date, time, timetz, timestamp, timestamptz, interval
  - Structured types: json, jsonb, xml
  - Network types: macaddr, inet, cidr
  - Geometric types: point, line, lseg, box, path, polygon, circle
  - Binary types: bytea, bit, varbit
* Multi-dimensional arrays are supported for binding and retrieving
* Is thread-safe
* Stored procedure execution is supported
* Transaction management is supported
* Transparent character encoding conversion is supported if necessary
* The "optimal-numbers" option is set by default as of module version 2.2
* Supports a server timezone setting for correctly handling date/time values
  when communicating with a DB server in another time zone
* The prepared statement API is supported (SQLStatement class)
* Automatic reconnection to the server if the connection is lost (when not in a transaction)
* Full support for PostgreSQL error codes in exceptions

The driver's name is "pgsql" and the Datasource type constant is SQL::DSPGSQL
Example: Datasource db = new Datasource(DSPGSQL);
Example: Datasource db = new Datasource("pgsql");
Example: Datasource db = new Datasource("pgsql:user/pass@dbname%hostname:5432");

The Qore pgsql driver uses binary communication with PostgreSQL servers and sets
per-connection variables based on server settings (i.e. it automatically determines
if the server is using floats or 64-bit integers for time values, etc).

This module is stable and has been extensively tested.

Documentation: docs/pgsql-module-doc.html (generated by Doxygen)
Test script: test/pgsql.qtest


DRIVER OPTIONS
--------------

The driver supports the following options:
* "optimal-numbers": return numeric types as an integer if possible, otherwise as
  an arbitrary-precision number (default)
* "string-numbers": return numeric types as strings (for backwards-compatibility)
* "numeric-numbers": return numeric types as arbitrary-precision number values
* "timezone": set the server's time zone (region name like "Europe/Prague" or
  UTC offset like "+01:00")

Options can be set in the Datasource constructor:
  Datasource db("pgsql:user/pass@dbname{numeric-numbers,timezone=Europe/Vienna}");


LICENSE
-------
The source code is released under the LGPL 2.1 and MIT licenses; either license
may be used at the user's discretion. Note that both licenses are treated
equally by the Qore library in the sense that both licenses allow the module
to be loaded without restrictions by the Qore library (even when the Qore
library is initialized in GPL mode).
See COPYING.MIT and COPYING.LGPL for details on the open-source licenses.


BUILD AND INSTALL
-----------------

PostgreSQL DBI module requires PostgreSQL 8+ client libraries and headers.
If your PostgreSQL libraries are in a non-standard location you can use the
--with-pgsql configure option or set the PGSQL_DIR environment variable.

Using CMake (recommended):

  mkdir build
  cd build
  cmake ..
  make
  sudo make install

Using autotools:

  ./configure
  make
  sudo make install

The configure script will find out where your qore module directory is found
and set this for the install directory.


BUILD FROM GIT
--------------

For autotools:
  ./reconf.sh
  ./configure
  make
  sudo make install

For CMake:
  mkdir build
  cd build
  cmake ..
  make
  sudo make install


RUNNING TESTS
-------------

Set the QORE_DB_CONNSTR_PGSQL environment variable to a valid PostgreSQL
connection string, then run:

  qore test/pgsql.qtest

Example:
  export QORE_DB_CONNSTR_PGSQL="pgsql:testuser/testpass@testdb%localhost:5432"
  qore test/pgsql.qtest

Docker-based tests are also available in test/docker_test/