Interfaces

src/interfaces/ contains the client libraries that user code links against to talk to a PostgreSQL server. They are independent of the backend; they speak the wire protocol and otherwise don't know about pages, WAL, or shared memory.

What ships in core

Interface	Source	Description
libpq	src/interfaces/libpq/	The official C client library. Synchronous (PQexec) and asynchronous (PQsendQuery + PQconsumeInput + PQgetResult) APIs. The substrate of nearly every PostgreSQL driver.
libpq-oauth	src/interfaces/libpq-oauth/	OAuth flows for libpq, implementing SASL-OAUTHBEARER. Loaded as a plugin when needed.
ECPG	src/interfaces/ecpg/	Embedded SQL preprocessor for C. Translates EXEC SQL ... into libpq calls. SQL standard.

That's it. Drivers for other languages (psycopg, JDBC, npgsql, asyncpg, ...) live in their own repos and link against libpq (or implement the protocol from scratch).

libpq

Source: src/interfaces/libpq/. Headers: src/include/libpq/ (server) and src/interfaces/libpq/libpq-fe.h, libpq-int.h (client).

The library exposes:

• Connection management (PQconnectdb, PQconnectdbParams, PQfinish).
• Synchronous query exec (PQexec, PQexecParams, PQexecPrepared).
• Asynchronous query exec (PQsendQuery, PQconsumeInput, PQgetResult).
• Single-row mode (PQsetSingleRowMode).
• Pipeline mode (PQenterPipelineMode, PQpipelineSync).
• COPY (PQputCopyData, PQgetCopyData, PQputCopyEnd).
• Notice processing, trace, large objects, error reporting, SSL/GSS, threading helpers.

The implementation is split across fe-connect.c (connection setup and SSL/GSS/SASL handshake), fe-exec.c (query API), fe-protocol3.c (protocol-3 message handling), fe-misc.c, fe-print.c, fe-secure-*.c (SSL backends), and fe-auth*.c (auth methods).

For the deeper tour, see libpq.

ECPG

Source: src/interfaces/ecpg/. The Embedded SQL precompiler. It reads *.pgc files containing C with EXEC SQL directives and emits plain C that calls the ECPG runtime, which itself sits on top of libpq.

Used for code that wants to look like SQL/C standard:

EXEC SQL CONNECT TO mydb USER bob;
EXEC SQL SELECT name INTO :name FROM users WHERE id = :id;
EXEC SQL DISCONNECT;

ECPG ships with:

• preproc/ — the precompiler itself (a parser similar to the backend's, but emitting C).
• ecpglib/ — the runtime that the generated code links against.
• pgtypeslib/ — pure-C implementations of numeric, date, timestamp, etc., usable client-side.
• compatlib/ — Informix-style compatibility helpers.
• include/ — the headers EXEC SQL-using code includes.

ECPG is mostly maintained for compatibility — newer client code typically prefers a higher-level driver — but it remains a supported part of the project and is tested in CI.

Wire protocol

Both libpq and ECPG speak the PostgreSQL frontend/backend wire protocol, currently version 3 (introduced in 7.4). The protocol is documented in doc/src/sgml/protocol.sgml and is the union of two sub-protocols:

• Simple query. Q "select 1;" → RowDescription, DataRow*, CommandComplete, ReadyForQuery.
• Extended query. Parse → ParameterDescription, Bind → Bind, Describe, Execute, Sync → message stream → ReadyForQuery.

Plus authentication, COPY (in/out), error/notice messages, async notifications (LISTEN/NOTIFY), parameter status updates, and the replication-protocol extensions used by walsender/walreceiver.

All messages are length-prefixed; the first byte (after the length on the backend-side response, or before it on the frontend side) is a type tag.

How drivers in other languages work

A typical driver either:

1. Wraps libpq via FFI. psycopg2, npgsql (older), Ruby's pg gem, Erlang's epgsql (some modes), etc. Cheap to implement; inherits all of libpq's auth methods and protocol features.
2. Reimplements protocol 3 natively. psycopg3 (with psycopg-c), asyncpg, pgx (Go), JDBC, npgsql (newer). More work but lets the driver do connection pooling, true async, or pipeline-mode optimally without libpq's threading constraints.

In either case, the driver targets the published wire protocol and the on-disk text/binary representations of types — both of which the project commits to maintaining backwards-compatibility for.

SSL, GSSAPI, SCRAM, OAUTH

Authentication is negotiated at connection time via the Authentication* messages. Built-in methods:

• Trust (no auth)
• Password (cleartext, deprecated)
• MD5 (deprecated; SCRAM is preferred)
• SCRAM-SHA-256 (default since 14)
• GSSAPI / Kerberos
• LDAP (server validates against an LDAP server)
• Cert (mutual TLS)
• SSPI (Windows)
• PAM
• RADIUS
• BSD auth
• SASL OAUTHBEARER (newer; via libpq-oauth)

Each method has frontend support in fe-auth*.c and backend support in src/backend/libpq/auth-*.c.

SSL/TLS is provided by either OpenSSL (fe-secure-openssl.c) or — historically — GnuTLS. Negotiated as an optional pre-startup SSLRequest byte; the server replies S or N.

Building extensions that include libpq

Most extensions are server-side (loaded into the backend) and don't need libpq. But some — like dblink and postgres_fdw — talk to other databases. They link against libpq from inside the backend, which is allowed but requires care: the backend has its own malloc replacement, so libpq calls are routed through the standard libc allocator.

Pages in this section

• libpq — connection options, query API, async/pipeline modes, threading.
• ECPG (this overview is the documentation; see doc/src/sgml/ecpg.sgml for the full reference).