README
¶
postgres
PostgreSQL driver module for rio, the zero-surprise Go ORM, built on pgx's database/sql adapter.
The module is deliberately thin — that is the design, not a first draft. It
provides the constructors, eager DSN validation, and a precise error
translator that maps *pgconn.PgError onto rio's sentinels: SQLSTATE 23505
becomes rio.ErrDuplicateKey and 23503 becomes rio.ErrForeignKeyViolated,
with the original pgx error kept in the chain for errors.As. Everything
that shapes SQL lives in the rio core.
Install
go get github.com/go-rio/postgres
Usage
db, err := postgres.Open("postgres://user:pass@localhost:5432/app")
if err != nil {
log.Fatal(err)
}
defer db.Close()
err = rio.Insert(ctx, db, &user) // RETURNING fills the whole row back
if errors.Is(err, rio.ErrDuplicateKey) {
var pgErr *pgconn.PgError
errors.As(err, &pgErr) // constraint name, table, detail — all still there
}
The DSN is handed to pgx untouched: URL form, keyword/value form, and every
pgx runtime parameter all work. Open validates the DSN but does not
connect; ping db.Unwrap() to check connectivity eagerly.
Bring your own pool
New wraps any *sql.DB you already manage — including one derived from a
pgxpool.Pool:
pool, err := pgxpool.New(ctx, dsn)
if err != nil {
log.Fatal(err)
}
db := postgres.New(stdlib.OpenDBFromPool(pool))
Pool tuning (SetMaxOpenConns and friends) happens on the *sql.DB; rio
never replaces or configures the connection pool.
PgBouncer
Behind PgBouncer in transaction or statement pooling mode, keep
rio.WithStmtCache off (it already is by default) and add
default_query_exec_mode=exec to the DSN, because server-side prepared
statements do not survive connection multiplexing.
The rio family
rio — the ORM · migrate — schema migrations as Go code · sqlite / mysql — the sibling drivers
License
The MIT License (MIT). Please see License File for more information.
Documentation
¶
Overview ¶
Package postgres connects github.com/go-rio/rio to PostgreSQL through the pgx driver's database/sql adapter.
The package is deliberately thin: it constructs a *rio.DB with the built-in rio.Postgres dialect and installs a precise error translator that maps *pgconn.PgError values onto rio's sentinel errors. All SQL grammar lives in the rio core; this module never shapes a query.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func New ¶
New wraps an existing *sql.DB in a *rio.DB with the Postgres dialect and this package's error translator. Use it when you bring your own pool: a *sql.DB you tuned yourself, or one derived from a pgxpool.Pool via stdlib.OpenDBFromPool.
Options are applied after the translator, so rio.WithErrorTranslator in opts replaces this package's translation if you need to.
func Open ¶
Open opens a PostgreSQL database via pgx's database/sql adapter and wraps it in a *rio.DB. The DSN is handed to pgx untouched, so both URL form (postgres://user:pass@host:5432/app) and keyword/value form (host=... user=... dbname=...) work, along with every pgx runtime parameter.
Open validates the DSN eagerly — pgx's database/sql adapter would otherwise surface a malformed DSN on the first query — but it does not connect; ping the underlying pool (db.Unwrap().PingContext) to verify connectivity. Pool tuning also happens on the *sql.DB returned by Unwrap — rio never replaces or configures the connection pool.
Types ¶
This section is empty.
Source Files