Database Connection Functions

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

• PQsetdbLogin Makes a new connection to a backend.

  PGconn *PQsetdbLogin(const char *pghost,
                  const char *pgport,
                  const char *pgoptions,
                  const char *pgtty,
                  const char *dbName,
                  const char *login,
                  const char *pwd);

  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. PQsetdbLogin 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.

• PQsetdb Makes a new connection to a backend.

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

  This is a macro that calls PQsetdbLogin() with null pointers for the login and pwd parameters.

• PQconndefaults Returns the database name of the connection.

  PQconninfoOption *PQconndefaults(void)
  
  struct PQconninfoOption
  	{
  		char   *keyword;   /* The keyword of the option	*/
  		char   *environ;   /* Fallback environment variable name */
  		char   *compiled;  /* Fallback compiled in default value */
  		char   *val;	   /* Options value */
  		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 options - don't
  				      create a field by default */
  		int	dispsize;  /* Field size in characters for dialog */
  	};
  

  Returns the address of the connection options structure. This may be used to determine all possible options and their current values.

• 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);