README
¶
driver-pgx
Opens Postgres for github.com/ubgo/sqlb through github.com/jackc/pgx/v5's database/sql adapter, and is where the pg package is executed rather than asserted.
This module exists for the tests more than for the driver. pg holds five hundred exported constructs, and until this module every one of them was checked as rendered text: a comparison with another Go builder found a table declared without an alias rendering a quoted empty identifier, which SQLite accepts and Postgres rejects, so the entire suite stayed green while the SQL was invalid on the engine the package is named after. The conformance suite and the construct catalogue here run against a real server, which is the only thing that turns an asserted construct into a proven one.
Contents
Setup
import (
driverpgx "github.com/ubgo/sqlb/contrib/driver-pgx"
)
Opening a database
db, err := driverpgx.Open("postgres://localhost:5432/app?sslmode=disable")
Open registers nothing you have to name — the adapter registers itself under DriverName, "pgx" — and pings, so a bad DSN fails here rather than at the first query. Two defaults are applied and each has an Option: DefaultMaxOpenConns (WithMaxOpenConns) caps the pool, because a Postgres connection is a server process and an uncapped pool exhausts max_connections before anything on the client; DefaultConnMaxLifetime (WithConnMaxLifetime) recycles connections so a restart or a pooler does not leave dead sockets in the pool. The *sql.DB satisfies exec.DBTX exactly as SQLite's does.
Running the proof
The tests read the connection string from EnvDSN, which is SQLB_PG_DSN; DSNFromEnv is exported so a consumer's own integration tests can share the convention.
SQLB_PG_DSN="postgres://localhost:5432/sqlb_conformance?sslmode=disable" go test ./contrib/driver-pgx/ -v
Absence is a loud skip, never a silent pass: without the variable every test in this package skips with a message naming it, so a green gate with the proof skipped is visible in the skip count rather than mistaken for the proof having run. The tests create and drop their own tables and extensions and touch nothing else in the database they are given.
What is proven
- The shared conformance suite in
sqlbtest, all cases plusRunReturning, on a second engine. - The
pgconstruct catalogue, one file per area —pg_constructs_test.gofor clauses and the empty-alias class,pg_arrays_json_test.go,pg_scalar_test.gofor text, time, ranges, full-text search and math,pg_statements_test.gofor aggregates, windows, writes,LOCK TABLE,MERGE,TRUNCATEand recursive options, andpg_extensions_test.gofor the eight extension packages, which it creates in the database it is given. 408 ofpg's 411 exports and all 89 extension exports are executed, 555 cases;Isis a Go-side check,TerminateBackendwould end the connection, andArrayReverse,ArraySortandArraySortDescskip below Postgres 18 with a message that says so. - What executing found, each with a passing rendering test: bare parameters that Postgres cannot type in
ARRAY[],jsonb_build_object,JSON_OBJECT,generate_series,substringand range@>;->with a text parameter taking the key form;LOCK TABLEandTRUNCATErendered with the table's alias; and two functions documented as Postgres 17 that are 18. Every fix is a cast or a spelling inpg, and every one is pinned here. - The empty-alias class specifically — tables declared without an alias, as a CTE reference is — because that is the mistake SQLite tolerates and Postgres does not.
Documentation
¶
Overview ¶
Package driverpgx opens Postgres databases for github.com/ubgo/sqlb.
It is a separate Go module inside the sqlb repository for the reason every contrib module is: the core depends on nothing but the standard library, so a library that embeds it inherits no driver. A driver is a dependency, so it lives out here, and an application pays for it only by importing this module.
The module's real work is its tests. The pg package holds five hundred exported constructs and, until this module existed, not one of them had run against a Postgres server: rendered text was checked and nothing else. A comparison with another Go builder showed exactly what that hides — a table declared without an alias rendered a quoted empty identifier, which SQLite accepts and Postgres rejects, so every test stayed green while the SQL was invalid on the engine the package is named after. This module runs the shared conformance suite and executes the pg constructs against a real server, which is the only thing that turns an asserted construct into a proven one.
The driver is github.com/jackc/pgx/v5 through its database/sql adapter, so exec.DBTX is satisfied by *sql.DB and *sql.Tx exactly as it is for SQLite.
Index ¶
Constants ¶
const ( // DefaultMaxOpenConns caps the pool. Postgres connections are processes // on the server, so an uncapped pool under load exhausts the server's // max_connections before it exhausts anything on the client. DefaultMaxOpenConns = 8 // DefaultConnMaxLifetime recycles connections so a server restart or a // pooler in front of it does not leave the pool holding dead sockets. DefaultConnMaxLifetime = 30 * time.Minute )
Defaults applied to every pool Open creates. They are the settings a process whose libraries own tables wants, and each is overridable.
const DriverName = "pgx"
DriverName is the database/sql name the pgx stdlib adapter registers.
const EnvDSN = "SQLB_PG_DSN"
EnvDSN is the environment variable the tests read the connection string from. Absence is a loud skip, never a silent pass: a test that needs a server and has none says so in its output rather than reporting success for work it did not do.
Variables ¶
This section is empty.
Functions ¶
func DSNFromEnv ¶
DSNFromEnv returns the connection string the tests use, and false when it is not set. It is exported so a consumer's own integration tests can share the convention.
Types ¶
type Option ¶
type Option func(*config)
Option adjusts what Open does.
func WithConnMaxLifetime ¶
WithConnMaxLifetime sets how long a connection may be reused.
func WithMaxOpenConns ¶
WithMaxOpenConns caps the pool at n connections.
Source Files