Database Connection Functions

The following routines deal with making a connection to a backend from a C program.

• PQsetdb Makes a new connection to a backend.

  PGconn *PQsetdb(char *pghost,
                  char *pgport,
                  char *pgoptions,
                  char *pgtty,
                  char *dbName);

  If any argument is NULL, then the corresponding environment variable is checked. If the environment variable is also not set, then hardwired defaults are used. PQsetdb always returns a valid PGconn pointer. The PQstatus (see below) command should be called to ensure that a connection was properly made before queries are sent via the connection. libpq programmers should be careful to maintain the PGconn abstraction. Use the accessor functions below to get at the contents of PGconn. Avoid directly referencing the fields of the PGconn structure as they are subject to change in the future.

• PQdb Returns the database name of the connection.

  char *PQdb(PGconn *conn)

• PQhost Returns the host name of the connection.

  char *PQhost(PGconn *conn)

• PQoptions Returns the pgoptions used in the connection.

  char *PQoptions(PGconn *conn)

• PQport Returns the pgport of the connection.

  char *PQport(PGconn *conn)

• PQtty Returns the pgtty of the connection.

  char *PQtty(PGconn *conn)

• PQstatus Returns the status of the connection. The status can be CONNECTION_OK or CONNECTION_BAD.

  ConnStatusType *PQstatus(PGconn *conn)

• PQerrorMessage Returns the error message associated with the connection

  char *PQerrorMessage(PGconn* conn);

• PQfinish Close the connection to the backend. Also frees memory used by the PGconn structure. The PGconn pointer should not be used after PQfinish has been called.

  void PQfinish(PGconn *conn)

• PQreset Reset the communication port with the backend. This function will close the IPC socket connection to the backend and attempt to reestablish a new connection to the same backend.

  void PQreset(PGconn *conn)

• PQtrace Enables tracing of messages passed between the frontend and the backend. The messages are echoed to the debug_port file stream.

  void PQtrace(PGconn *conn,
               FILE* debug_port);

• PQuntrace Disables tracing of messages passed between the frontend and the backend.

  void PQuntrace(PGconn *conn);