tessl/golang-github-com-jackc-pgx-v5

pgx is a pure Go driver and toolkit for PostgreSQL providing a native high-performance interface with PostgreSQL-specific features plus a database/sql compatibility adapter.

Overview

Eval results

Files

Tracing & Logging

Name: tessl/golang-github-com-jackc-pgx-v5
Author: tessl

pgx supports instrumentation via tracer interfaces. The tracelog package bridges pgx tracing to traditional loggers. The multitracer package combines multiple tracers.

Tracer Interfaces (pgx package)

Set a tracer on ConnConfig.Tracer (of type QueryTracer). For multi-interface tracers, use multitracer.

QueryTracer

// package: github.com/jackc/pgx/v5

type QueryTracer interface {
    TraceQueryStart(ctx context.Context, conn *Conn, data TraceQueryStartData) context.Context
    TraceQueryEnd(ctx context.Context, conn *Conn, data TraceQueryEndData)
}

type TraceQueryStartData struct {
    SQL  string
    Args []any
}

type TraceQueryEndData struct {
    CommandTag pgconn.CommandTag
    Err        error
}

BatchTracer

type BatchTracer interface {
    TraceBatchStart(ctx context.Context, conn *Conn, data TraceBatchStartData) context.Context
    TraceBatchQuery(ctx context.Context, conn *Conn, data TraceBatchQueryData)
    TraceBatchEnd(ctx context.Context, conn *Conn, data TraceBatchEndData)
}

type TraceBatchStartData struct {
    Batch *Batch
}

type TraceBatchQueryData struct {
    SQL        string
    Args       []any
    CommandTag pgconn.CommandTag
    Err        error
}

type TraceBatchEndData struct {
    Err error
}

CopyFromTracer

type CopyFromTracer interface {
    TraceCopyFromStart(ctx context.Context, conn *Conn, data TraceCopyFromStartData) context.Context
    TraceCopyFromEnd(ctx context.Context, conn *Conn, data TraceCopyFromEndData)
}

type TraceCopyFromStartData struct {
    TableName   Identifier
    ColumnNames []string
}

type TraceCopyFromEndData struct {
    CommandTag pgconn.CommandTag
    Err        error
}

PrepareTracer

type PrepareTracer interface {
    TracePrepareStart(ctx context.Context, conn *Conn, data TracePrepareStartData) context.Context
    TracePrepareEnd(ctx context.Context, conn *Conn, data TracePrepareEndData)
}

type TracePrepareStartData struct {
    Name string
    SQL  string
}

type TracePrepareEndData struct {
    AlreadyPrepared bool
    Err             error
}

ConnectTracer

type ConnectTracer interface {
    TraceConnectStart(ctx context.Context, data TraceConnectStartData) context.Context
    TraceConnectEnd(ctx context.Context, data TraceConnectEndData)
}

type TraceConnectStartData struct {
    ConnConfig *ConnConfig
}

type TraceConnectEndData struct {
    Conn *Conn
    Err  error
}

Pool Tracer Interfaces (pgxpool package)

// package: github.com/jackc/pgx/v5/pgxpool

type AcquireTracer interface {
    TraceAcquireStart(ctx context.Context, pool *Pool, data TraceAcquireStartData) context.Context
    TraceAcquireEnd(ctx context.Context, pool *Pool, data TraceAcquireEndData)
}

type ReleaseTracer interface {
    TraceRelease(pool *Pool, data TraceReleaseData)
}

type TraceAcquireStartData struct{}

type TraceAcquireEndData struct {
    Conn *pgx.Conn
    Err  error
}

type TraceReleaseData struct {
    Conn *pgx.Conn
}

tracelog Package

import "github.com/jackc/pgx/v5/tracelog"

TraceLog implements all pgx tracer interfaces and delegates to a Logger.

Logger Interface

type Logger interface {
    Log(ctx context.Context, level LogLevel, msg string, data map[string]any)
}

LoggerFunc

type LoggerFunc func(ctx context.Context, level LogLevel, msg string, data map[string]any)

func (f LoggerFunc) Log(ctx context.Context, level LogLevel, msg string, data map[string]any)

Log Levels

type LogLevel int

const (
    LogLevelTrace LogLevel = 6
    LogLevelDebug LogLevel = 5
    LogLevelInfo  LogLevel = 4
    LogLevelWarn  LogLevel = 3
    LogLevelError LogLevel = 2
    LogLevelNone  LogLevel = 1
)

func (ll LogLevel) String() string
func LogLevelFromString(s string) (LogLevel, error)

Valid level strings: "trace", "debug", "info", "warn", "error", "none"

TraceLog

type TraceLog struct {
    Logger   Logger
    LogLevel LogLevel
    Config   *TraceLogConfig // auto-initialized if nil
}

type TraceLogConfig struct {
    TimeKey string
}

func DefaultTraceLogConfig() *TraceLogConfig

TraceLog implements:

pgx.QueryTracer
pgx.BatchTracer
pgx.ConnectTracer
pgx.CopyFromTracer
pgx.PrepareTracer
pgxpool.AcquireTracer
pgxpool.ReleaseTracer

Example: Use TraceLog

// Implement the Logger interface for your logging library
type myLogger struct{}
func (l *myLogger) Log(ctx context.Context, level tracelog.LogLevel, msg string, data map[string]any) {
    // delegate to your logging library
    log.Printf("[%s] %s %v", level, msg, data)
}

config, _ := pgx.ParseConfig(os.Getenv("DATABASE_URL"))
config.Tracer = &tracelog.TraceLog{
    Logger:   &myLogger{},
    LogLevel: tracelog.LogLevelInfo,
}
conn, err := pgx.ConnectConfig(ctx, config)

Example: Use with pgxpool

poolConfig, _ := pgxpool.ParseConfig(os.Getenv("DATABASE_URL"))
poolConfig.ConnConfig.Tracer = &tracelog.TraceLog{
    Logger:   &myLogger{},
    LogLevel: tracelog.LogLevelDebug,
}
pool, err := pgxpool.NewWithConfig(ctx, poolConfig)

multitracer Package

import "github.com/jackc/pgx/v5/multitracer"

Combines multiple tracer implementations into one, automatically splitting by interface.

type Tracer struct {
    QueryTracers       []pgx.QueryTracer
    BatchTracers       []pgx.BatchTracer
    CopyFromTracers    []pgx.CopyFromTracer
    PrepareTracers     []pgx.PrepareTracer
    ConnectTracers     []pgx.ConnectTracer
    PoolAcquireTracers []pgxpool.AcquireTracer
    PoolReleaseTracers []pgxpool.ReleaseTracer
}

func New(tracers ...pgx.QueryTracer) *Tracer

New takes tracers that implement at minimum QueryTracer, then checks each for other interfaces and distributes them.

Tracer implements: QueryTracer, BatchTracer, CopyFromTracer, PrepareTracer, ConnectTracer, pgxpool.AcquireTracer, pgxpool.ReleaseTracer.

Example: Combine multiple tracers

traceLogger := &tracelog.TraceLog{Logger: myLogger, LogLevel: tracelog.LogLevelInfo}
otelTracer := myOtelTracer // implements pgx.QueryTracer

config.Tracer = multitracer.New(traceLogger, otelTracer)

Manual construction

mt := &multitracer.Tracer{
    QueryTracers:   []pgx.QueryTracer{traceLogger, otelTracer},
    ConnectTracers: []pgx.ConnectTracer{traceLogger},
}
config.Tracer = mt

log/testingadapter Package

import "github.com/jackc/pgx/v5/log/testingadapter"

Logger adapter for Go test infrastructure.

type TestingLogger interface {
    Log(args ...any)
}

type Logger struct{ /* unexported */ }

func NewLogger(l TestingLogger) *Logger
func (l *Logger) Log(ctx context.Context, level tracelog.LogLevel, msg string, data map[string]any)

*testing.T and *testing.B implement TestingLogger. Usage:

func TestMyFunction(t *testing.T) {
    logger := testingadapter.NewLogger(t)
    traceLog := &tracelog.TraceLog{
        Logger:   logger,
        LogLevel: tracelog.LogLevelTrace,
    }
    config, _ := pgx.ParseConfig(os.Getenv("DATABASE_URL"))
    config.Tracer = traceLog
    conn, err := pgx.ConnectConfig(ctx, config)
    // ...
}

Install with Tessl CLI

npx tessl i tessl/golang-github-com-jackc-pgx-v5@5.8.0