1/*-------------------------------------------------------------------------
3 * libpq-be-fe-helpers.h
4 * Helper functions for using libpq in extensions
6 * Code built directly into the backend is not allowed to link to libpq
7 * directly. Extension code is allowed to use libpq however. However, libpq
8 * used in extensions has to be careful not to block inside libpq, otherwise
9 * interrupts will not be processed, leading to issues like unresolvable
10 * deadlocks. Backend code also needs to take care to acquire/release an
11 * external fd for the connection, otherwise fd.c's accounting of fd's is
14 * This file provides helper functions to make it easier to comply with these
15 * rules. It is a header only library as it needs to be linked into each
16 * extension using libpq, and it seems too small to be worth adding a
17 * dedicated static library for.
19 * TODO: For historical reasons the connections established here are not put
20 * into non-blocking mode. That can lead to blocking even when only the async
21 * libpq functions are used. This should be fixed.
23 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
24 * Portions Copyright (c) 1994, Regents of the University of California
26 * src/include/libpq/libpq-be-fe-helpers.h
28 *-------------------------------------------------------------------------
30#ifndef LIBPQ_BE_FE_HELPERS_H
31#define LIBPQ_BE_FE_HELPERS_H
48 * PQconnectdb() wrapper that reserves a file descriptor and processes
49 * interrupts during connection establishment.
51 * Throws an error if AcquireExternalFD() fails, but does not throw if
52 * connection establishment itself fails. Callers need to use PQstatus() to
53 * check if connection establishment succeeded.
70 * Like libpqsrv_connect(), except that this is a wrapper for
71 * PQconnectdbParams().
91 * PQfinish() wrapper that additionally releases the reserved file descriptor.
93 * It is allowed to call this with a NULL pgconn iff NULL was returned by
100 * If no connection was established, we haven't reserved an FD for it (or
101 * already released it). This rule makes it easier to write PG_CATCH()
102 * handlers for this facility's users.
104 * See also libpqsrv_connect_internal().
114/* internal helper functions follow */
118 * Helper function for all connection establishment functions.
124 * We must obey fd.c's limit on non-virtual file descriptors. Assume that
125 * a PGconn represents one long-lived FD. (Doing this here also ensures
126 * that VFDs are closed if needed to make room.)
130#ifndef WIN32 /* can't write #if within ereport() macro */
132 (
errcode(ERRCODE_SQLCLIENT_UNABLE_TO_ESTABLISH_SQLCONNECTION),
133 errmsg(
"could not establish connection"),
134 errdetail(
"There are too many open files on the local server."),
135 errhint(
"Raise the server's \"max_files_per_process\" and/or \"ulimit -n\" limits.")));
138 (
errcode(ERRCODE_SQLCLIENT_UNABLE_TO_ESTABLISH_SQLCONNECTION),
139 errmsg(
"could not establish connection"),
140 errdetail(
"There are too many open files on the local server."),
141 errhint(
"Raise the server's \"max_files_per_process\" setting.")));
147 * Helper function for all connection establishment functions.
153 * With conn == NULL libpqsrv_disconnect() wouldn't release the FD. So do
163 * Can't wait without a socket. Note that we don't want to close the libpq
164 * connection yet, so callers can emit a useful error.
170 * WaitLatchOrSocket() can conceivably fail, handle that case here instead
171 * of requiring all callers to do so.
178 * Poll connection until we have OK or FAILED status.
180 * Per spec for PQconnectPoll, first wait till socket is write-ready.
193 * Windows needs a different test while waiting for
215 /* If socket is ready, advance the libpq state machine */
223 * If an error is thrown here, the callers won't call
224 * libpqsrv_disconnect() with a conn, so release resources
236 * PQexec() wrapper that processes interrupts.
238 * Unless PQsetnonblocking(conn, 1) is in effect, this can't process
239 * interrupts while pushing the query text to the server. Consider that
240 * setting if query strings can be long relative to TCP buffer size.
242 * This has the preconditions of PQsendQuery(), not those of PQexec(). Most
243 * notably, PQexec() would silently discard any prior query results.
254 * PQexecParams() wrapper that processes interrupts.
256 * See notes at libpqsrv_exec().
262 const Oid *paramTypes,
263 const char *
const *paramValues,
264 const int *paramLengths,
265 const int *paramFormats,
270 paramLengths, paramFormats, resultFormat))
276 * Like PQexec(), loop over PQgetResult() until it returns NULL or another
277 * terminal state. Return the last non-NULL result or the terminal state.
286 /* Wait for, and collect, the next PGresult. */
291 break;
/* query is complete, or failure */
294 * Emulate PQexec()'s behavior of returning the last result when there
310 * Perform the equivalent of PQgetResult(), but watch for interrupts.
316 * Collect data until PQgetResult is ready to get the result without
337 /* Consume whatever data is available from the socket */
340 /* trouble; expect PQgetResult() to return NULL */
345 /* Now we can collect and return the next PGresult */
350 * Submit a cancel request to the given connection, waiting only until
353 * We sleep interruptibly until we receive confirmation that the cancel
354 * request has been accepted, and if it is, return NULL; if the cancel
355 * request fails, return an error message string (which is not to be
358 * For other problems (to wit: OOM when strdup'ing an error message from
359 * libpq), this function can ereport(ERROR).
361 * Note: this function leaks a string's worth of memory when reporting
362 * libpq errors. Make sure to call it in a transient memory context.
364static inline const char *
368 const char *
error = NULL;
371 if (cancel_conn == NULL)
372 return "out of memory";
374 /* In what follows, do not leak any PGcancelConn on any errors. */
393 break;
/* success! */
395 /* If timeout has expired, give up, else get sleep time. */
398 if (cur_timeout <= 0)
400 error =
"cancel request timed out";
417 /* Sleep until there's something to do */
437 * libpqsrv_notice_receiver
439 * Custom notice receiver for libpq connections.
441 * This function is intended to be set via PQsetNoticeReceiver() so that
442 * NOTICE, WARNING, and similar messages from the connection are reported via
443 * ereport(), instead of being printed to stderr.
445 * Because this will be called from libpq with a "real" (not wrapped)
446 * PGresult, we need to temporarily ignore libpq-be-fe.h's wrapper macros
447 * for PGresult and also PQresultErrorMessage, and put back the wrappers
448 * afterwards. That's not pretty, but there seems no better alternative.
451#undef PQresultErrorMessage
458 const char *prefix = (
const char *)
arg;
461 * Trim the trailing newline from the message text returned from
462 * PQresultErrorMessage(), as it always includes one, to produce cleaner
466 len = strlen(message);
467 if (
len > 0 && message[
len - 1] ==
'\n')
474 #define PGresult libpqsrv_PGresult
475 #define PQresultErrorMessage libpqsrv_PQresultErrorMessage
477#endif /* LIBPQ_BE_FE_HELPERS_H */
long TimestampDifferenceMilliseconds(TimestampTz start_time, TimestampTz stop_time)
TimestampTz GetCurrentTimestamp(void)
Datum now(PG_FUNCTION_ARGS)
static Datum values[MAXATTR]
int errmsg_internal(const char *fmt,...)
int errdetail(const char *fmt,...)
int errhint(const char *fmt,...)
int errcode(int sqlerrcode)
int errmsg(const char *fmt,...)
#define ereport(elevel,...)
void ReleaseExternalFD(void)
bool AcquireExternalFD(void)
PGcancelConn * PQcancelCreate(PGconn *conn)
PostgresPollingStatusType PQcancelPoll(PGcancelConn *cancelConn)
void PQcancelFinish(PGcancelConn *cancelConn)
int PQcancelSocket(const PGcancelConn *cancelConn)
char * PQcancelErrorMessage(const PGcancelConn *cancelConn)
int PQcancelStart(PGcancelConn *cancelConn)
PostgresPollingStatusType PQconnectPoll(PGconn *conn)
ConnStatusType PQstatus(const PGconn *conn)
PGconn * PQconnectStart(const char *conninfo)
PGconn * PQconnectStartParams(const char *const *keywords, const char *const *values, int expand_dbname)
void PQfinish(PGconn *conn)
int PQsocket(const PGconn *conn)
int PQsendQueryParams(PGconn *conn, const char *command, int nParams, const Oid *paramTypes, const char *const *paramValues, const int *paramLengths, const int *paramFormats, int resultFormat)
int PQconsumeInput(PGconn *conn)
int PQsendQuery(PGconn *conn, const char *query)
int PQisBusy(PGconn *conn)
static const JsonPathKeyword keywords[]
int WaitLatchOrSocket(Latch *latch, int wakeEvents, pgsocket sock, long timeout, uint32 wait_event_info)
void ResetLatch(Latch *latch)
static const char * libpqsrv_cancel(PGconn *conn, TimestampTz endtime)
static PGresult * libpqsrv_exec(PGconn *conn, const char *query, uint32 wait_event_info)
static PGconn * libpqsrv_connect_params(const char *const *keywords, const char *const *values, int expand_dbname, uint32 wait_event_info)
static PGconn * libpqsrv_connect(const char *conninfo, uint32 wait_event_info)
static void libpqsrv_connect_prepare(void)
static PGresult * libpqsrv_get_result(PGconn *conn, uint32 wait_event_info)
static void libpqsrv_notice_receiver(void *arg, const PGresult *res)
static void libpqsrv_connect_internal(PGconn *conn, uint32 wait_event_info)
static void libpqsrv_disconnect(PGconn *conn)
#define PQresultErrorMessage
static PGresult * libpqsrv_exec_params(PGconn *conn, const char *command, int nParams, const Oid *paramTypes, const char *const *paramValues, const int *paramLengths, const int *paramFormats, int resultFormat, uint32 wait_event_info)
static PGresult * libpqsrv_get_result_last(PGconn *conn, uint32 wait_event_info)
PostgresPollingStatusType
char * pchomp(const char *in)
#define CHECK_FOR_INTERRUPTS()
#define WL_SOCKET_READABLE
#define WL_EXIT_ON_PM_DEATH
#define WL_SOCKET_CONNECTED
#define WL_SOCKET_WRITEABLE