pgx para Go: guia completo com exemplos

Introdução ao pgx: um poderoso driver PostgreSQL para Go

A biblioteca pgx (PostgreSQL eXtended) é um driver moderno e de alto desempenho, além de um conjunto de ferramentas para trabalhar com PostgreSQL a partir da linguagem de programação Go. Ao contrário do pacote padrão database/sql, o pgx fornece acesso direto ao protocolo PostgreSQL, o que proporciona um ganho significativo de desempenho e acesso a recursos exclusivos do SGBD, como LISTEN/NOTIFY, protocolo COPY, trabalho com arrays e tipos compostos, e muito mais.

Por que usar pgx em vez do padrão database/sql? Primeiro, o pgx é 30-50% mais rápido devido à ausência de abstrações desnecessárias. Segundo, ele suporta todos os recursos modernos do PostgreSQL 12+ (e versões mais recentes). Terceiro, o pgx fornece uma API rica para trabalhar com conexões, pool de conexões, consultas preparadas e transações. Finalmente, o pgx é totalmente compatível com database/sql através de um adaptador especial, permitindo seu uso em projetos que já utilizam a interface padrão.

Instalação do pgx

A instalação do pgx em um projeto Go é feita com o comando padrão go get. Para trabalhar com PostgreSQL, você precisará instalar o pacote principal pgx e, possivelmente, módulos adicionais:

# Instalação do pacote principal pgx v5 (versão recomendada)\ngo get github.com/jackc/pgx/v5\n\n# Instalação do pacote para trabalhar com pool de conexões\ngo get github.com/jackc/pgx/v5/pgxpool\n\n# Instalação do adaptador para compatibilidade com database/sql\ngo get github.com/jackc/pgx/v5/stdlib

Após executar esses comandos, você poderá importar o pgx em seus arquivos Go. Certifique-se de ter o Go versão 1.18 ou superior instalado, pois o pgx v5 usa generics.

Início rápido: primeira conexão ao PostgreSQL

Vamos escrever um programa simples que se conecta ao banco de dados PostgreSQL e executa uma consulta. Suponha que você tenha o PostgreSQL em execução em localhost:5432, o banco de dados se chama testdb, o usuário testuser com senha 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    // String de conexão\n    connStr := "postgres://testuser:testpass@localhost:5432/testdb"\n\n    // Estabelece a conexão\n    conn, err := pgx.Connect(context.Background(), connStr)\n    if err != nil {\n        log.Fatalf("Não foi possível conectar ao BD: %v", err)\n    }\n    defer conn.Close(context.Background())\n\n    // Executa uma consulta simples\n    var greeting string\n    err = conn.QueryRow(context.Background(), "SELECT 'Hello, PostgreSQL!'").Scan(&greeting)\n    if err != nil {\n        log.Fatalf("Erro ao executar consulta: %v", err)\n    }\n\n    fmt.Println(greeting)\n}

Este código estabelece uma conexão, executa uma consulta e exibe o resultado. Observe o uso de context.Background() — esta é a forma padrão de passar contexto em Go, que permite controlar timeouts e cancelamento de operações.

Principais métodos e funções do pgx

Vamos examinar os métodos e funções mais importantes da biblioteca pgx. Para cada método, forneceremos uma descrição, parâmetros e um exemplo de código funcional.

1. pgx.Connect — estabelecendo uma conexão

O que faz: Cria uma nova conexão com o PostgreSQL. Esta é a principal forma de começar a trabalhar com o banco de dados.

Parâmetros:

\n
• ctx context.Context — contexto para gerenciar o tempo de vida da conexão
\n
• connString string — string de conexão no formato URI ou DSN
\n

Retorna: (*pgx.Conn, error)

Exemplo:

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