Eiffel interface to PostgreSQL is based on libpq, the C
application programmer's interface to PostgreSQL. libpq is a set
of library functions that allow client programs to pass queries
to the PostgreSQL backend server and to receive the results of
these queries.
CONNECTION_STARTED
Waiting for connection to be made.
CONNECTION_MADE
Connection OK; waiting to send.
CONNECTION_AWAITING_RESPONSE
Waiting for a response from the server.
CONNECTION_AUTH_OK
Received authentication; waiting for backend start-up
to finish.
CONNECTION_SSL_STARTUP
Negotiating SSL encryption.
CONNECTION_SETENV
Negotiating environment-driven parameter settings.
PQconndefaults
Returns the default connection options.
PQconninfoOption *PQconndefaults(void);
typedef struct
{
char *keyword; /* The keyword of the option */
char *envvar; /* Fallback environment variable name */
char *compiled; /* Fallback compiled in default value */
char *val; /* Option's current value, or NULL */
char *label; /* Label for field in connect dialog */
char *dispchar; /* Character to display for this field
in a connect dialog. Values are:
"" Display entered value as is
"*" Password field - hide value
"D" Debug option - don't show by default */
int dispsize; /* Field size in characters for dialog */
} PQconninfoOption;
Build a FAST_ARRAY of STRINGs from a_pointer which must be of a
NULL-terminated array of C strings, that is a "char**" String
contents and array itself are copied.
This function opens a new database connection using the
parameters taken from the string conninfo. Unlike
login below, the parameter set can be extended
without changing the function signature, so use of this
function (or its nonblocking analogues PQconnectStart and
PQconnectPoll) is preferred for new application
programming.
The passed string can be empty to use all default
parameters, or it can contain one or more parameter
settings separated by whitespace. Each parameter setting
is in the form keyword = value. Spaces around the equal
sign are optional. To write an empty value or a value
containing spaces, surround it with single quotes, e.g.,
keyword = 'a value'. Single quotes and backslashes within
the value must be escaped with a backslash, i.e., \' and
\\.
The currently recognized parameter key words are:
host: Name of host to connect to. If this begins with a
slash, it specifies Unix-domain communication rather than
TCP/IP communication; the value is the name of the
directory in which the socket file is stored. The default
behavior when host is not specified is to connect to a
Unix-domain socket in /tmp (or whatever socket directory
was specified when PostgreSQL was built). On machines
without Unix-domain sockets, the default is to connect to
localhost.
hostaddr: Numeric IP address of host to connect to. This
should be in the standard IPv4 address format, e.g.,
172.28.40.9. If your machine supports IPv6, you can also
use those addresses. TCP/IP communication is always used
when a nonempty string is specified for this parameter.
Using hostaddr instead of host allows the application to
avoid a host name look-up, which may be important in
applications with time constraints. However, Kerberos
authentication requires the host name. The following
therefore applies: If host is specified without hostaddr,
a host name lookup occurs. If hostaddr is specified
without host, the value for hostaddr gives the remote
address. When Kerberos is used, a reverse name query
occurs to obtain the host name for Kerberos. If both host
and hostaddr are specified, the value for hostaddr gives
the remote address; the value for host is ignored, unless
Kerberos is used, in which case that value is used for
Kerberos authentication. (Note that authentication is
likely to fail if libpq is passed a host name that is not
the name of the machine at hostaddr.) Also, host rather
than hostaddr is used to identify the connection in
~/.pgpass (see Section 27.12).
Without either a host name or host address, libpq will
connect using a local Unix-domain socket; or on machines
without Unix-domain sockets, it will attempt to connect to
localhost.
port: Port number to connect to at the server host, or
socket file name extension for Unix-domain connections.
dbname: The database name. Defaults to be the same as
the user name.
user: PostgreSQL user name to connect as. Defaults to be
the same as the operating system name of the user running
the application.
password: Password to be used if the server demands
password authentication.
connect_timeout: Maximum wait for connection, in seconds
(write as a decimal integer string). Zero or not specified
means wait indefinitely. It is not recommended to use a
timeout of less than 2 seconds.
options: Command-line options to be sent to the server.
tty: Ignored (formerly, this specified where to send
server debug output).
sslmode: This option determines whether or with what
priority an SSL connection will be negotiated with the
server. There are four modes: disable will attempt only
an unencrypted SSL connection; allow will negotiate,
trying first a non-SSL connection, then if that fails,
trying an SSL connection; prefer (the default) will
negotiate, trying first an SSL connection, then if that
fails, trying a regular non-SSL connection; require will
try only an SSL connection.
If PostgreSQL is compiled without SSL support, using
option require will cause an error, while options allow
and prefer will be accepted but libpq will not in fact
attempt an SSL connection.
requiressl: This option is deprecated in favor of the
sslmode setting.
If set to 1, an SSL connection to the server is required
(this is equivalent to sslmode require). libpq will then
refuse to connect if the server does not accept an SSL
connection. If set to 0 (default), libpq will negotiate
the connection type with the server (equivalent to sslmode
prefer). This option is only available if PostgreSQL is
compiled with SSL support.
service: Service name to use for additional
parameters. It specifies a service name in pg3C_service.conf
that holds additional connection parameters. This allows
applications to specify only a service name so connection
parameters can be centrally maintained. See
share/pg_service.conf.sample in the installation directory
for information on how to set up the file.
If any parameter is unspecified, then the corresponding
environment variable (see Section 27.11) is checked. If
the environment variable is not set either, then the
indicated built-in defaults are used.
It closes
the connection to the server and attempt to reestablish a
new connection to the same server, using all the same
parameters previously used. This may be useful for error
recovery if a working connection is lost.
This exception occurs when Void is passed as the expression
to inspect ("inspect on STRING only).
This exception also occurs when the inspected value selects no branch (when the keyword "else"
not used, one "when" branch _must_ be selected). Some value which is not one of the inspect
constants, if there is no Else_part
Build a FAST_ARRAY of STRINGs from a_pointer which must be of a
NULL-terminated array of C strings, that is a "char**" String
contents and array itself are copied.