chickadee » postgresql » connect

Opens a connection to the database given in CONNECTION-SPEC, which should be either a PostgreSQL connection string or an alist with entries consisting of a symbol and a value. The symbols should be connection keywords recognized by PostgreSQL's connection function. See the list of PQconnectdbParams parameter keywords in the PostgreSQL documentation. At the time of writing, they are host, hostaddr, port, dbname, user, password, connect_timeout, options, sslmode, service.

If any parameter is not specified, or the CONNECTION-SPEC was not supplied at all, the regular libpq rules apply. That means it falls back to checking various environment variables and settings from pg_service.conf, as well as passwords from pgpass. This is to be preferred over hardcoding connection settings in your code.

Using an alist for CONNECTION-SPEC is recommended; when available (when using libpq from Postgres 9.0 or later), PQconnectStartParams will be used. This prevents parsing errors when keys or values contain "special" characters like equals signs or single quotes. This also adds a layer of security for when connection specifier components come from an untrusted source.

TYPE-PARSERS is an optional alist that maps PostgreSQL type names to parser procedures, TYPE-UNPARSERS is an optional alist that maps predicates to unparser procedures. They default to (default-type-parsers) and (default-type-unparsers), respectively (see below).

The return value is a connection-object.

Important: You cannot use the same connection from multiple threads. If you need to talk to the same server from different threads, simply create a second connection.

Also note that while these bindings use the non-blocking interface to connect to PostgreSQL, if you specify a hostname (using the host-keyword), the function might not be able to yield because the resolver will block. If you don't want this, you'd have to call some kind of custom asynchronous resolver.