Sutiles detalles de pgx Batch en Go: gestión de conexiones y manejo de errores en CloseNota · digest del 7 de noviembre
Plano técnico infográfico de patente del pipeline de red pgx Batch en Go con flujo de consultas hacia PostgreSQL y finalización mediante la llamada a Close.
Nota2 secciones≈ 4 min

Sutiles detalles de pgx Batch en Go: gestión de conexiones y manejo de errores en Close

Cuando un backend en Go ejecuta una cadena de operaciones SQL homogéneas, el primer impulso instintivo es agruparlas en un lote y enviarlas en un solo viaje de ida y vuelta por la red. El driver pgx de Jack Christensen ofrece una excelente herramienta para ello: la estructura pgx.Batch. En lugar de llamadas de red secuenciales, las consultas salen hacia PostgreSQL en paquete, ahorrando valiosos milisegundos de latencia de red.

Pero si vienes a pgx desde el paquete estándar database/sql, te espera una sorpresa desagradable: una conexión del pool queda bloqueada de repente con el estado conn busy, y en los logs empiezan a aparecer errores confusos sobre la desasignación de sentencias preparadas. Ya hemos analizado el comportamiento de la cola del pool de conexiones en Go, pero en pgx las consultas por lotes tienen su propia especificidad estricta.

Veamos cómo funciona el ciclo de vida de un lote «bajo el capó» y por qué la llamada habitual defer br.Close() esconde aquí una trampa oculta.

La trampa de la conexión ocupada: por qué defer br.Close() no es tan simple

Tras llamar a pool.SendBatch(ctx, batch), el driver toma una conexión TCP física y la pasa a un estado de ocupación exclusiva. La interfaz BatchResults empieza a recibir los resultados secuencialmente. Y aquí está el detalle clave: aunque ya hayas leído los datos necesarios del primer SELECT mediante br.QueryRow().Scan(...), la conexión no puede utilizarse para ninguna otra operación hasta que se llame al método br.Close().

En Go es costumbre liberar recursos con una llamada diferida defer resource.Close(). Pero BatchResults.Close() tiene una diferencia fundamental: devuelve un error.

// Hacer esto es peligroso: se perderá el error de lectura del socket
br := pool.SendBatch(ctx, batch)
defer br.Close()

El método Close() no se limita a cerrar un descriptor de red. Lee secuencialmente del búfer del socket todos los bytes restantes de las respuestas del servidor PostgreSQL para todas las consultas del lote. Si la tercera consulta de cinco falló por una violación de clave foránea (foreign key violation) o un error de sintaxis, será precisamente Close() quien lea ese mensaje de la base de datos y devuelva el error al exterior.

Si escribes un simple defer br.Close(), tu función dará la operación por exitosa aunque en la base de datos haya ocurrido un fallo y la transacción implícita (implicit transaction) del lote se haya revertido.

Patrón idiomático: retorno con nombre y lectura segura

Para no perder el error de finalización y devolver con total garantía la conexión a pgxpool.Pool, en Go se utiliza un patrón idiomático con valor de retorno de error con nombre:

package repository

import (
    "context"
    "fmt"

    "github.com/jackc/pgx/v5"
    "github.com/jackc/pgx/v5/pgxpool"
)

type AccountCredit struct {
    AccountID int64
    Amount    int64
}

func ProcessCreditsBatch(ctx context.Context, pool *pgxpool.Pool, items []AccountCredit) (err error) {
    batch := &pgx.Batch{}
    for _, item := range items {
        batch.Queue(
            "UPDATE accounts SET balance = balance + $1, updated_at = NOW() WHERE id = $2",
            item.Amount,
            item.AccountID,
        )
    }

    br := pool.SendBatch(ctx, batch)

    // Capturamos el error de cierre del lote mediante la variable con nombre err
    defer func() {
        if closeErr := br.Close(); closeErr != nil && err == nil {
            err = fmt.Errorf("error al cerrar pgx batch: %w", closeErr)
        }
    }()

    for i := 0; i < len(items); i++ {
        cmdTag, execErr := br.Exec()
        if execErr != nil {
            return fmt.Errorf("fallo en la consulta %d del lote: %w", i, execErr)
        }
        if cmdTag.RowsAffected() == 0 {
            return fmt.Errorf("cuenta %d no encontrada", items[i].AccountID)
        }
    }

    return nil
}

Esta construcción ofrece una doble garantía. En primer lugar, la conexión volverá al pool con total seguridad incluso en caso de pánico o salida anticipada. En segundo lugar, si la base de datos falla en la fase de finalización del socket, el error no se esfumará en el aire, sino que subirá correctamente hasta la capa de lógica de negocio.

Quiero un análisis detalladoLos votos ayudan a elegir qué analizar a fondo. Este material tiene 0 votos.
Fuentes · 3