add package pgruntime

1 files changed, 32 insertions, 0 deletions

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 <majewsky@gmx.net>
+// 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