postgreSQL.connection.open

Syntax

postgreSQL.connection.open (conninfo)

Params

conninfo is a string specifying the connection parameters.

Action

Opens a connection to the specified database server.

Returns

A reference to the new connection.

Examples

connectionRef = postgreSQL.connection.open ("hostaddr=192.168.1.3 user=test password=test")

« 63009680

Notes

The conninfo string consists of a number of key-value pairs:

host is the domain name of the database server. Default is the empty string. On Mac OS X, you can also specify the path of a directory, e.g. '/tmp', containing the Unix domain socket of a database server running on the local machine.

hostaddr is the IP address of the database server. Default is the empty string. When specified, this parameter takes precedence over the host parameter and is useful for avoiding the overhead of domain name resolution when opening a new connection.

port is the port number on which the database server listens for incoming connections. Default is 5432.

dbname is the name of the database to connect to on the database server. Default is equal to the specified user name.

user is the user name used to authenticate to the database server. Default is the empty string, or if your operating system supports it, the name of the current user.

password is the password used to authenticate to the database server. Default is the empty string.

options specifies debug options to activate on the database server. Default is the empty string.

If a key is specified more than once in the conninfo string, later occurences take precedence. The key and the assigned value are separated by equal signs, multiple key-value pairs are separated by whitespace. Single quotes in a value must be escaped with a backslash. Values containing whitespace must be enclosed in single quotes. You can use postgreSQL.util.buildConnInfoString to construct a legal conninfo string.

The new connection automatically starts a new transaction and sets the transaction isolation level to serializable. Call postgreSQL.connection.commit to finalize any changes you made to the database. Call postgreSQL.connection.rollback to roll back all changes you made since last calling postgreSQL.connection.commit or since opening the connection. Any changes not yet committed when closing the connection will be rolled back automatically. To turn off this default behaviour, you can switch to auto-commit mode by calling postgreSQL.connection.setAutoCommit.

To conserve system resources both on the client and the server, it is critically important that you call postgreSQL.connection.close when you no longer need the connection. Therefore, all code executed after opening the connection should run inside a try statement with the corresponding else block taking care of closing the connection even in case a script error is encountered.

The overhead of starting a new backend process on the server and authenticating to it may lead to inacceptable latency if you call this verb from within a web application or a similar scenario where low latency is important. In such cases, you can minimize latency by calling postgreSQL.pool.create once from your applications startup code to create a dynamic pool of open connections and then call postgreSQL.connection.grab to obtain connection references from that pool.

See Also

postgreSQL.connection.close

postgreSQL.connection.commit

postgreSQL.connection.rollback

postgreSQL.connection.setAutoCommit

postgreSQL.pool.create

postgreSQL.util.buildConnInfoString