pgx for Go: Complete Guide with Examples

Introduction to pgx: A Powerful PostgreSQL Driver for Go

The pgx library (PostgreSQL eXtended) is a modern, high-performance driver and toolkit for working with PostgreSQL from the Go programming language. Unlike the standard database/sql package, pgx provides direct access to the PostgreSQL protocol, offering significant performance gains and access to unique DBMS features such as LISTEN/NOTIFY, the COPY protocol, working with arrays and composite types, and much more.

Why use pgx instead of the standard database/sql? First, pgx is 30-50% faster due to the absence of unnecessary abstractions. Second, it supports all modern features of PostgreSQL 12+ (and newer versions). Third, pgx provides a rich API for working with connections, connection pools, prepared queries, and transactions. Finally, pgx is fully compatible with database/sql through a special adapter, allowing its use in projects that already use the standard interface.

Installing pgx

Installing pgx into a Go project is done with the standard go get command. To work with PostgreSQL, you will need to install the main pgx package and possibly additional modules:

# Install the main pgx v5 package (recommended version)\ngo get github.com/jackc/pgx/v5\n\n# Install the package for working with connection pools\ngo get github.com/jackc/pgx/v5/pgxpool\n\n# Install the adapter for compatibility with database/sql\ngo get github.com/jackc/pgx/v5/stdlib

After running these commands, you will be able to import pgx into your Go files. Make sure you have Go version 1.18 or higher installed, as pgx v5 uses generics.

Quick Start: First Connection to PostgreSQL

Let's write a simple program that connects to a PostgreSQL database and executes a query. Assume you have PostgreSQL running on localhost:5432, the database is called testdb, the user is testuser with the password testpass.

package main\n\nimport (\n    "context"\n    "fmt"\n    "log"\n    "os"\n\n    "github.com/jackc/pgx/v5"\n)\n\nfunc main() {\n    // Connection string\n    connStr := "postgres://testuser:testpass@localhost:5432/testdb"\n\n    // Establish connection\n    conn, err := pgx.Connect(context.Background(), connStr)\n    if err != nil {\n        log.Fatalf("Failed to connect to DB: %v", err)\n    }\n    defer conn.Close(context.Background())\n\n    // Execute a simple query\n    var greeting string\n    err = conn.QueryRow(context.Background(), "SELECT 'Hello, PostgreSQL!'").Scan(&greeting)\n    if err != nil {\n        log.Fatalf("Query execution error: %v", err)\n    }\n\n    fmt.Println(greeting)\n}

This code establishes a connection, executes a query, and prints the result. Note the use of context.Background() — this is the standard way to pass context in Go, allowing you to control timeouts and cancel operations.

Core Methods and Functions of pgx

Let's look at the most important methods and functions of the pgx library. For each method, we provide a description, parameters, and a working code example.

1. pgx.Connect — Establishing a Connection

What it does: Creates a new connection to PostgreSQL. This is the primary way to start working with the database.

Parameters:

\n
• ctx context.Context — context for managing the connection's lifetime
\n
• connString string — connection string in URI or DSN format
\n

Returns: (*pgx.Conn, error)

Example:

conn, err := pgx.Connect(context.Background(), "postgres://user:pass@localhost:5432/mydb")\nif err != nil {\n    log.