OPTIONAL
SYNOPSIS
        int pg_connect (string conn, string fun)
        int pg_connect (string conn, string fun, string|object obj, mixed extra, ...)
        int pg_connect (string conn, closure cl, mixed extra, ...)

DESCRIPTION
        Open a database connection as directed by <conn>, and assign the
        callback function <fun>/<cl> with the optional <extra> parameters
        to it.

        The object holding the callback function becomes the controlling
        object; obiously it is an error to assign more than one connection
        to the same controlling object.

        The <conn> string is in the format accepted by Postgres'
        PQconnectStart() API functions. Pass an empty string to use the
        default options, or a string holding the '<key>=<value>' options
        separated by whitespace.
        
        The most useful options are:
          dbname:   The database name
          user:     The user name to connect as.
          password: Password to be used.

        Return 0 on success, and -1 on failure.

        The function is available only if the driver is compiled with
        PostgreSQL support. In that case, __PGSQL__ is defined.

        The efun triggers a privilege violation ("pgsql", "pg_connect").

HISTORY
        Added in 3.3.445.
        LDMud 3.3.640 added the privilege violation.

SEE ALSO
        pgsql(C), pg_query(E), pg_pending(E), pg_conv_string(E), pg_close(E),
        privilege_violation(M)
