From 81e32cec36291685b59102594c714d235726e214 Mon Sep 17 00:00:00 2001 From: Stefan Majewsky Date: Thu, 30 Jul 2026 19:57:29 +0200 Subject: add package pgruntime --- pgruntime/pgruntime.go | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 pgruntime/pgruntime.go (limited to 'pgruntime/pgruntime.go') diff --git a/pgruntime/pgruntime.go b/pgruntime/pgruntime.go new file mode 100644 index 0000000..ed44076 --- /dev/null +++ b/pgruntime/pgruntime.go @@ -0,0 +1,32 @@ +// SPDX-FileCopyrightText: 2026 Stefan Majewsky +// SPDX-License-Identifier: Apache-2.0 + +// Package pgruntime provides connection handling for PostgreSQL databases, +// including optional support for database migrations and self-contained test DB instances. +// It can be used with any PostgreSQL data driver, including [lib/pq] and [pgx]. +// +// # Basic usage +// +// In productive scenarios, build a [ConnectionTarget] instance from configuration values or command-line arguments, and call [Connector.Connect]. +// In test scenarios, call [Connector.ConnectForTest]. +// +// Both situations require a [Connector] instance: +// When using an std-compatible driver like [lib/pq], use [StdConnector]. +// Otherwise, a custom [Connector] implementation must be supplied. +// For [pgx], the connectors from [gg-pgx] may be used. +// +// # Legacy +// +// This is a clean-room reimplementation of one half of [easypg] with several interface improvements and cleanups, most notably: +// - The hard dependency on lib/pq has been removed. +// - Support for creating databases on first use has been removed (except in ConnectForTest). +// - ConnectForTest now recreates databases instead of just wiping their contents. +// +// [easypg]: https://pkg.go.dev/github.com/sapcc/go-bits/easypg +// [lib/pq]: https://pkg.go.dev/github.com/lib/pq +// [pgx]: https://pkg.go.dev/github.com/jackc/pgx/v5 +// [gg-pgx]: https://git.xyrillian.de/go-gg-pgx/ +package pgruntime + +// TODO: before merging this branch, start work on go-gg-pgx to verify that we're not painting ourselves into a corner with the gsql.Handle interfaces +// TODO: test coverage via separate module importing github.com/lib/pq -- cgit v1.3.1