PQconnectdb

PQconnectdb is a function in PostgreSQL's libpq library that establishes a new connection to a PostgreSQL database using a connection string. It is declared as PGconn* PQconnectdb(const char *conninfo).

It performs the connection synchronously, blocking until the server accepts or rejects the connection. It returns a pointer to a PGconn structure which can be used with other libpq functions. If the connection attempt fails, the returned PGconn is still non-null but its status is CONNECTION_BAD; you should check PQstatus and PQerrorMessage for details.

The connection information is supplied as a connection string composed of key=value pairs separated by spaces (for example "host=localhost port=5432 dbname=mydb user=postgres password=secret"). The string can be built from environment variables or literals. You can also specify parameters separately using PQconnectdbParams for a parameterized approach; but PQconnectdb itself takes a single string.

After obtaining a valid connection, standard operations follow: verify with PQstatus(conn) == CONNECTION_OK, then use PQexec or other functions to run queries. Remember to call PQfinish(conn) to close the connection and free resources when done.

PQconnectdb is suitable for simple, blocking connection setup in applications where synchronous initialization is acceptable. For asynchronous connection establishment, libpq provides alternative functions such as PQconnectStart and PQconnectPoll or PQconnectdbParams.