Guide · Open source
How to use pgx: connect Go to PostgreSQL and run queries
Updated · written with AI from the project's own documentation and checked against our catalogue data
pgx is a pure Go driver and toolkit for PostgreSQL. It lets a Go program connect to a PostgreSQL database, run queries, and use PostgreSQL-specific features such as LISTEN/NOTIFY and COPY. This guide is for Go developers who want to install pgx, make a first connection, and understand which interface to use. By the end you will be able to run a query with pgx and know where to look for connection options and the connection pool.
pgxjackc/pgx · ★ 14.4k · MIT Install options & downloads Quick start
- 1Check prerequisites. Confirm you have Go 1.25 or higher and a PostgreSQL 14 or higher database to connect to.
- 2Install pgx. Run go get github.com/jackc/pgx/v5 in your Go project directory.
- 3Set your connection string. Export DATABASE_URL with a PostgreSQL URL such as postgres://username:password@localhost:5432/database_name.
- 4Write the connect code. Call pgx.Connect with context.Background() and the URL, and handle the returned error.
- 5Run a query. Use conn.QueryRow with a $1 placeholder and Scan the results into Go variables.
- 6Choose an interface. Use the native pgx interface or pgxpool for PostgreSQL-only code, or the stdlib adapter if you need database/sql.
What you need before you start
pgx is a Go library, so you need Go installed. The source says pgx supports Go 1.25 or higher and PostgreSQL 14 or higher. The PostgreSQL requirement applies to the database you run your code against.
pgx assumes you are already familiar with Go and database APIs. The README is written for that audience, so beginners with no Go experience may want to learn the basics first.
- Go 1.25 or higher
- PostgreSQL 14 or higher, for the database you connect to
- Basic familiarity with Go
Install pgx with go get
Add the pgx v5 library to your Go module with the command from the README. Run it inside your project directory, where your go.mod file lives.
go get github.com/jackc/pgx/v5Connect to PostgreSQL and run a query
The README example reads the connection URL from the DATABASE_URL environment variable, then calls pgx.Connect. A connection URL looks like postgres://username:password@localhost:5432/database_name. After connecting, QueryRow sends a query with a $1 placeholder, and Scan copies the returned columns into Go variables.
Always close the connection with defer conn.Close. The example also writes errors to standard error and exits with status 1 if connecting or querying fails.
- Set DATABASE_URL to your connection string before running the program.
- Use $1, $2 and so on for query parameters rather than building SQL strings by hand.
- Pass a context.Context to each call, as the example does with context.Background().
package main
import (
"context"
"fmt"
"os"
"github.com/jackc/pgx/v5"
)
func main() {
// urlExample := "postgres://username:password@localhost:5432/database_name"
conn, err := pgx.Connect(context.Background(), os.Getenv("DATABASE_URL"))
if err != nil {
fmt.Fprintf(os.Stderr, "Unable to connect to database: %v\n", err)
os.Exit(1)
}
defer conn.Close(context.Background())
var name string
var weight int64
err = conn.QueryRow(context.Background(), "select name, weight from widgets where id=$1", 42).Scan(&name, &weight)
if err != nil {
fmt.Fprintf(os.Stderr, "QueryRow failed: %v\n", err)
os.Exit(1)
}
fmt.Println(name, weight)
}Configure the connection
pgx.Connect and pgxpool.New accept PostgreSQL connection URLs, such as postgres://user:pass@host:5432/db?sslmode=verify-full, as well as key=value strings. The README points to pgconn.ParseConfig and the PostgreSQL connection string documentation for the supported options and environment variables.
The README also links a getting started guide in the project wiki for a step-by-step walkthrough.
- Connection URLs and key=value strings are both accepted.
- TLS is configured through options such as sslmode in the connection string.
- Supported options are listed in the pgconn.ParseConfig documentation.
Use pgxpool for a connection pool or database/sql for portability
pgx includes pgxpool, a concurrency-safe connection pool, for applications that handle many requests at once. The stdlib package is an adapter for Go's standard database/sql interface.
The README says the native pgx interface is faster, and that many PostgreSQL features such as LISTEN/NOTIFY and COPY are not available through database/sql. It recommends the pgx interface when the application only targets PostgreSQL and no other libraries that require database/sql are in use. You can also use database/sql and convert a connection to the lower-level pgx interface when needed.
- pgx native interface: best when you only target PostgreSQL.
- pgxpool: built-in connection pool, concurrency-safe.
- stdlib: database/sql adapter, for code or libraries that need database/sql.
Use PostgreSQL-specific features
The feature list includes LISTEN / NOTIFY, COPY protocol support for faster bulk data loads, batch queries, and automatic statement preparation and caching. It also supports json and jsonb, hstore, large objects, and savepoints for simulated nested transactions.
The README lists these features without full usage examples, so check the pkg.go.dev API reference for the exact function signatures.
- LISTEN / NOTIFY
- COPY for bulk loads
- Batch queries
- json and jsonb support
- Simulated nested transactions with savepoints
What people use it for
- Building a Go web service that stores data only in PostgreSQL
- Using LISTEN / NOTIFY to react to database events in a Go program
- Loading large datasets quickly with the COPY protocol
- Writing a PostgreSQL proxy, load balancer or logical replication client on the wire protocol packages
Frequently asked questions
How do I install pgx?
Run go get github.com/jackc/pgx/v5 in your Go project directory. The README lists this as the installation command.
What version of Go and PostgreSQL does pgx need?
The README says pgx supports Go 1.25 and higher and PostgreSQL 14 and higher. Those are the versions the project supports.
Is pgx free to use?
pgx is released under the MIT licence, according to the project information. Check the LICENSE file in the repository for the full terms.
What is the difference between pgx and database/sql?
pgx has a native interface that exposes PostgreSQL-specific features such as LISTEN / NOTIFY and COPY. The database/sql interface is a standard Go abstraction that works across databases but does not expose those features. pgx also includes an adapter for database/sql.
What are alternatives to pgx?
The project lists database/sql with lib/pq, GORM, sqlc, and pgx-compatible tools such as scany as comparable options. Choose based on whether you want a driver, an ORM, or a query generator.
Can I use pgx if I need to support multiple databases?
Not through its native interface. The README says pgx's native interface is PostgreSQL-only, so projects that need several databases through database/sql should look at other options.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
pgx is a good fit for Go developers who build services on PostgreSQL alone and want access to features like LISTEN/NOTIFY and COPY, or a built-in connection pool. If you are new to Go, or need your code to work across several databases through database/sql, consider an ORM or a database/sql driver such as lib/pq instead.
Install options & downloads