# pgx — High-Performance PostgreSQL Driver for Go

> A pure Go PostgreSQL driver and toolkit that provides low-level access to PostgreSQL features including COPY, LISTEN/NOTIFY, and custom types, with superior performance.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# pgx — High-Performance PostgreSQL Driver for Go

## Quick Use
```bash
go get github.com/jackc/pgx/v5
```
```go
conn, _ := pgx.Connect(context.Background(), "postgres://user:pass@localhost:5432/db")
var name string
conn.QueryRow(context.Background(), "SELECT name FROM users WHERE id=$1", 1).Scan(&name)
```

## Introduction
pgx is a pure Go driver and toolkit for PostgreSQL that goes beyond the standard database/sql interface. It provides direct access to PostgreSQL-specific features like COPY protocol, LISTEN/NOTIFY, large objects, and custom type mapping while delivering better performance than database/sql for most workloads.

## What pgx Does
- Implements the PostgreSQL wire protocol in pure Go with binary format support
- Provides both a native interface and a database/sql compatible adapter (pgxpool/stdlib)
- Supports connection pooling with health checks and automatic reconnection
- Handles PostgreSQL-specific types (arrays, composites, ranges, enums) natively
- Implements COPY protocol for high-speed bulk data loading and extraction

## Architecture Overview
pgx communicates with PostgreSQL using the binary wire protocol by default, avoiding text serialization overhead for numeric and timestamp types. The pgxpool package manages a pool of connections with configurable min/max sizes, health checks, and idle timeouts. Type mapping is handled by the pgtype package which provides codec-based encoding for all PostgreSQL types, including user-defined ones.

## Self-Hosting & Configuration
- Install: `go get github.com/jackc/pgx/v5`
- Connect with a DSN string or structured pgx.ConnConfig
- Use pgxpool.New() for connection pooling in concurrent applications
- Configure pool size, connection lifetime, and health check intervals
- Register custom types with pgtype.Map for composite or enum types

## Key Features
- Binary protocol by default yields faster scanning for numeric, timestamp, and UUID types
- Native COPY support for bulk imports at PostgreSQL wire-speed
- LISTEN/NOTIFY integration for real-time event-driven architectures
- Batch queries send multiple statements in a single network round-trip
- Prepared statement caching reduces per-query overhead in long-lived connections

## Comparison with Similar Tools
- **lib/pq** — older pure Go driver using text protocol; pgx is faster and more actively maintained
- **database/sql** — standard Go interface; pgx's native API exposes PostgreSQL features database/sql cannot
- **GORM** — full ORM that can use pgx as its underlying driver for PostgreSQL
- **sqlx** — adds struct scanning to database/sql; pgx has built-in struct scanning via pgx.CollectRows
- **sqlc** — generates type-safe Go from SQL; works with pgx as the runtime driver

## FAQ
**Q:** Should I use pgx native or the database/sql adapter?
A: Use native pgx for new projects to access all PostgreSQL features. Use the adapter if you need compatibility with database/sql libraries.

**Q:** How does pgx handle connection pooling?
A: Use pgxpool.Pool which manages connections with configurable limits, health checks, and graceful shutdown.

**Q:** Does pgx support prepared statements?
A: Yes. By default pgx uses an automatic statement cache that prepares queries on first use and reuses them.

**Q:** Can I use pgx with GORM?
A: Yes. GORM's PostgreSQL driver uses pgx under the hood since GORM v2.

## Sources
- https://github.com/jackc/pgx
- https://pkg.go.dev/github.com/jackc/pgx/v5

---
Source: https://tokrepo.com/en/workflows/pgx-high-performance-postgresql-driver-go-04625dc3
Author: Script Depot