# lib/pq architecture

> Architecture diagram of the GitHub repository lib/pq, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lib/pq
- Repository: https://github.com/lib/pq

## Overview

pq is a Go PostgreSQL driver for database/sql. Its main workflow is: an application supplies a DSN or Config, database/sql obtains a driver connection, and that connection negotiates a PostgreSQL session, executes statements, and returns decoded rows or errors. Separate product capabilities include bulk COPY, LISTEN/NOTIFY, authentication and TLS, and PostgreSQL-specific types. The source index and excerpts show key internal dependencies; some subsystem links below are documented by the README, while unsampled implementation details are left unconnected.

Main entry points: [`conn.go`](https://github.com/lib/pq/blob/main/conn.go) (Database connection), [`internal/proto/proto.go`](https://github.com/lib/pq/blob/main/internal/proto/proto.go) (Wire protocol), [`encode.go`](https://github.com/lib/pq/blob/main/encode.go) (Value encoding), [`rows.go`](https://github.com/lib/pq/blob/main/rows.go) (Result rows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Driver entry"]
  node_driver["SQL driver registration<br/>[doc.go]"]
  node_config["DSN configuration<br/>[connector.go]"]
  node_connector["Connection connector<br/>[connector.go]"]
end

subgraph group_session["Connection and protocol"]
  node_connection["Database connection<br/>[conn.go]"]
  node_protocol["Wire protocol<br/>[proto.go]"]
  node_statement["Statements and queries<br/>[conn.go]"]
  node_rows["Result rows<br/>[rows.go]"]
end

subgraph group_features["PostgreSQL features"]
  node_copy["Bulk COPY<br/>[copy.go]"]
  node_listener["Notification listener<br/>[notify.go]"]
  node_auth["SCRAM authentication<br/>[scram.go]"]
  node_kerberos["Kerberos integration<br/>[krb.go]"]
  node_tls["TLS and certificates<br/>[ssl.go]"]
end

subgraph group_support["Types and support"]
  node_encoding["Value encoding<br/>[encode.go]"]
  node_pgpass["Password file lookup<br/>[pgpass.go]"]
  node_pgservice["Service file lookup<br/>[pgservice.go]"]
  node_types["PostgreSQL type IDs<br/>[types.go]"]
  node_arrays["Array values<br/>[array.go]"]
  node_hstore["Hstore values<br/>[hstore.go]"]
  node_errors["Server errors<br/>[error.go]"]
  node_errorcodes["Error codes<br/>[pqerror.go]"]
  node_timestamps["Timestamp handling<br/>[pqtime.go]"]
end

node_application(("Go application"))
node_postgres[("PostgreSQL server")]

node_application -->|"opens driver"| node_driver
node_application -->|"provides DSN"| node_config
node_application -->|"opens pool"| node_connector
node_connector -->|"creates connection"| node_connection
node_connection -->|"exchanges protocol"| node_postgres
node_connection -->|"uses messages"| node_protocol
node_connection -->|"looks up password"| node_pgpass
node_connection -->|"uses SCRAM"| node_auth
node_config -->|"reads service"| node_pgservice
node_statement -->|"executes on"| node_connection
node_connection -->|"prepares query"| node_statement
node_statement -->|"routes COPY"| node_copy
node_connection -->|"encodes parameters"| node_encoding
node_encoding -->|"uses type IDs"| node_types
node_encoding -->|"formats timestamps"| node_timestamps
node_rows -->|"reads messages"| node_protocol
node_rows -->|"uses type IDs"| node_types
node_connection -->|"returns results"| node_rows
node_copy -->|"uses messages"| node_protocol
node_listener -->|"uses messages"| node_protocol
node_connection -.->|"negotiates TLS"| node_tls
node_connection -.->|"supports GSS"| node_kerberos
node_connection -->|"parses server errors"| node_errors
node_errors -->|"uses error codes"| node_errorcodes
node_application -->|"subscribes notifications"| node_listener

click node_driver "https://github.com/lib/pq/blob/main/doc.go"
click node_config "https://github.com/lib/pq/blob/main/connector.go"
click node_connector "https://github.com/lib/pq/blob/main/connector.go"
click node_connection "https://github.com/lib/pq/blob/main/conn.go"
click node_protocol "https://github.com/lib/pq/blob/main/internal/proto/proto.go"
click node_statement "https://github.com/lib/pq/blob/main/conn.go"
click node_encoding "https://github.com/lib/pq/blob/main/encode.go"
click node_rows "https://github.com/lib/pq/blob/main/rows.go"
click node_copy "https://github.com/lib/pq/blob/main/copy.go"
click node_listener "https://github.com/lib/pq/blob/main/notify.go"
click node_auth "https://github.com/lib/pq/blob/main/internal/scram/scram.go"
click node_kerberos "https://github.com/lib/pq/blob/main/auth/kerberos/krb.go"
click node_tls "https://github.com/lib/pq/blob/main/ssl.go"
click node_pgpass "https://github.com/lib/pq/blob/main/internal/pgpass/pgpass.go"
click node_pgservice "https://github.com/lib/pq/blob/main/internal/pgservice/pgservice.go"
click node_types "https://github.com/lib/pq/blob/main/oid/types.go"
click node_arrays "https://github.com/lib/pq/blob/main/array.go"
click node_hstore "https://github.com/lib/pq/blob/main/hstore/hstore.go"
click node_errors "https://github.com/lib/pq/blob/main/error.go"
click node_errorcodes "https://github.com/lib/pq/blob/main/pqerror/pqerror.go"
click node_timestamps "https://github.com/lib/pq/blob/main/internal/pqtime/pqtime.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_driver,node_config,node_connector toneBlue
class node_connection,node_protocol,node_statement,node_rows,node_postgres toneAmber
class node_copy,node_listener,node_auth,node_kerberos,node_tls toneMint
class node_encoding,node_pgpass,node_pgservice,node_types,node_arrays,node_hstore,node_errors,node_errorcodes,node_timestamps toneRose
class node_application toneIndigo
```

## Components

### Driver entry

- [SQL driver registration](https://github.com/lib/pq/blob/main/doc.go): `doc.go`
- [DSN configuration](https://github.com/lib/pq/blob/main/connector.go): `connector.go`
- [Connection connector](https://github.com/lib/pq/blob/main/connector.go): `connector.go`

### Connection and protocol

- [Database connection](https://github.com/lib/pq/blob/main/conn.go): `conn.go`
- [Wire protocol](https://github.com/lib/pq/blob/main/internal/proto/proto.go): `internal/proto/proto.go`
- [Statements and queries](https://github.com/lib/pq/blob/main/conn.go): `conn.go`
- [Result rows](https://github.com/lib/pq/blob/main/rows.go): `rows.go`

### PostgreSQL features

- [Bulk COPY](https://github.com/lib/pq/blob/main/copy.go): `copy.go`
- [Notification listener](https://github.com/lib/pq/blob/main/notify.go): `notify.go`
- [SCRAM authentication](https://github.com/lib/pq/blob/main/internal/scram/scram.go): `internal/scram/scram.go`
- [Kerberos integration](https://github.com/lib/pq/blob/main/auth/kerberos/krb.go): `auth/kerberos/krb.go`
- [TLS and certificates](https://github.com/lib/pq/blob/main/ssl.go): `ssl.go`

### Types and support

- [Value encoding](https://github.com/lib/pq/blob/main/encode.go): `encode.go`
- [Password file lookup](https://github.com/lib/pq/blob/main/internal/pgpass/pgpass.go): `internal/pgpass/pgpass.go`
- [Service file lookup](https://github.com/lib/pq/blob/main/internal/pgservice/pgservice.go): `internal/pgservice/pgservice.go`
- [PostgreSQL type IDs](https://github.com/lib/pq/blob/main/oid/types.go): `oid/types.go`
- [Array values](https://github.com/lib/pq/blob/main/array.go): `array.go`
- [Hstore values](https://github.com/lib/pq/blob/main/hstore/hstore.go): `hstore/hstore.go`
- [Server errors](https://github.com/lib/pq/blob/main/error.go): `error.go`
- [Error codes](https://github.com/lib/pq/blob/main/pqerror/pqerror.go): `pqerror/pqerror.go`
- [Timestamp handling](https://github.com/lib/pq/blob/main/internal/pqtime/pqtime.go): `internal/pqtime/pqtime.go`

### Other components

- **Go application**
- **PostgreSQL server**

## Connections

- Go application → SQL driver registration: opens driver (evidence: `README.md`)
- Go application → DSN configuration: provides DSN (evidence: `README.md`)
- Go application → Connection connector: opens pool (evidence: `README.md`)
- Connection connector → Database connection: creates connection (evidence: `connector.go`)
- Database connection → PostgreSQL server: exchanges protocol (evidence: `README.md`)
- Database connection → Wire protocol: uses messages (evidence: `conn.go`)
- Database connection → Password file lookup: looks up password (evidence: `conn.go`)
- Database connection → SCRAM authentication: uses SCRAM (evidence: `conn.go`)
- DSN configuration → Service file lookup: reads service (evidence: `connector.go`)
- Statements and queries → Database connection: executes on (evidence: `conn.go`)
- Database connection → Statements and queries: prepares query (evidence: `conn.go`)
- Statements and queries → Bulk COPY: routes COPY (evidence: `conn.go`)
- Database connection → Value encoding: encodes parameters (evidence: `conn.go`)
- Value encoding → PostgreSQL type IDs: uses type IDs (evidence: `encode.go`)
- Value encoding → Timestamp handling: formats timestamps (evidence: `encode.go`)
- Result rows → Wire protocol: reads messages (evidence: `rows.go`)
- Result rows → PostgreSQL type IDs: uses type IDs (evidence: `rows.go`)
- Database connection → Result rows: returns results (evidence: `conn.go`)
- Bulk COPY → Wire protocol: uses messages (evidence: `copy.go`)
- Notification listener → Wire protocol: uses messages (evidence: `notify.go`)
- Database connection → TLS and certificates: negotiates TLS
- Database connection → Kerberos integration: supports GSS (evidence: `README.md`)
- Database connection → Server errors: parses server errors (evidence: `conn.go`)
- Server errors → Error codes: uses error codes (evidence: `error.go`)
- Go application → Notification listener: subscribes notifications (evidence: `README.md`)
