Description
A PostgreSQL driver for node.js that focuses on performance.
Requirements
- node.js -- v6.3.0 or newer
Install
npm install pg2
Examples
- Buffered SELECT query:
var Client = ; var c = host: '127.0.0.1' user: 'foo' password: 'bar' db: 'test'; c; c;
- Streamed SELECT query:
var Client = ; var c = host: '127.0.0.1' user: 'foo' password: 'bar' db: 'test'; c; ; c;
- Using arrays (faster) instead of objects for rows:
var Client = ; var c = host: '127.0.0.1' user: 'foo' password: 'bar' db: 'test'; c; c;
- Using positional parameters in a query:
var Client = ; var c = host: '127.0.0.1' user: 'foo' password: 'bar' db: 'test'; c; c;
API
require('pg2')
returns a Client object
Client properties
-
connected - boolean -
true
if the Client instance is currently connected to the server. -
backendParams - object - Once authenticated, this value will contain any backend status values. If no such values have been received, the value of this property will be
null
. -
key - object - Once authenticated, this object will contain two properties (
pid
andkey
) which is used to uniquely identify this connection on the server. -
status - integer - Indicates the backend transaction status. Valid values:
73
- Not in a transactional block84
- In a transactional block69
- In a failed transactional block (queries will be rejected until block is ended)
Client events
-
ready() - A connection to the server has been established and authentication was successful.
-
error(< Error >err) - An error occurred at the connection level.
-
close() - The connection has been closed.
Client methods
-
(constructor)([< object >config]) - Creates and returns a new Client instance. Valid
config
options include:-
user - string - Username for authentication. Default: (OS username of current logged in user)
-
password - string - Password for authentication. Default:
''
-
host - string - Hostname or IP address of the server. Default:
'localhost'
-
port - integer - Port number of the server. Default:
5432
-
db - string - A database to automatically select after authentication. Default:
''
-
keepalive - mixed - If
true
, this enables TCP keepalive probes using the OS default initial delay value. If a number, this both enables TCP keepalive probes and sets the initial delay value to the given value. Default:true
-
streamType - string - Set to
'normal'
to use node's full-featured streams instead of simpler streams. The main difference is that the simpler streams do not implement.read()
support. Default:'simple'
-
-
query(< string >query[, < array >values][, < object >options][, < function >callback]) - mixed - Enqueues the given
query
. Ifcallback
is not supplied, aResultStream
instance is returned.values
can be an array of values that correspond to positional placeholders insidequery
. Validoptions
are:-
arrays - boolean - When
true
, arrays are used to store row values instead of an object keyed on column names. (Note: using arrays performs better) Default:false
-
hwm - integer - This is the
highWaterMark
to use forRowStream
instances emitted by aResultStream
instance. This only applies when streaming rows. Default: (node's default)16
-
-
connect([< function >callback]) - (void) - Explicitly attempts to connect to the server. Note that calling
query()
will implicitly attempt a connection if one is not already made. If not connected,callback
is added as a one-time'ready'
event listener. -
end() - (void) - Closes the connection once all queries in the queue have been executed.
-
destroy() - (void) - Closes the connection immediately, even if there are other queries still in the queue. Any/all queries still in the queue are properly notified.
ResultStream
is an object stream that emits RowStream
instances. In the case of multiple statements/queries passed to query()
(separated by ;
), there will be one RowStream
instance for each statement/query.
RowStream
is an object stream that emits rows.
TODO (in no particular order)
-
Allow passing back of data type OIDs for columns sent by the server
-
client.abort()
that implicitly opens a new, temporary connection to kill the currently running query -
COPY data support (both in and out)