Documentation
¶
Overview ¶
Package testpg is a throwaway Postgres for one test, or for one package's tests through its TestMain.
StartServer runs initdb and pg_ctl from the binaries on PATH (or the well-known install directories, or NOVA_PG_BIN). What a test can rely on:
WHAT IT LISTENS ON. One TCP listener on 127.0.0.1, the IPv4 loopback, on a port the kernel chose, and no Unix socket (unix_socket_directories is empty: a macOS t.TempDir path is longer than a socket's name may be). Trust authentication, no password anywhere.
IT IS THE CALLER'S ALONE. The port is taken from the kernel, closed and handed to postgres, so another process can bind it in between. pg_ctl reports a start only when the server of THIS data directory is up, so a server that lost its port is a failed start, and another port is taken. Every Database is a fresh, empty database: parallel tests share the server and nothing else.
NOTHING IS KEPT. The data directory and the log are under the directory the caller gave, which for Start is the test's own t.TempDir(), with fsync off.
IT STOPS WITH THE TEST. Start's cleanup stops the server (immediate mode) and the testing package removes the directory: after a pass, a failure or a panic in the test. StartServer's caller stops it with Stop. pg_ctl detaches the server from the test binary, so a test binary that dies without its cleanups (a timeout, os.Exit, a kill) leaves the server running: internal/testredis has a sentry for that, this package has none.
A runner without the binaries FAILS the test with one line naming the binary: no evidence is not negative evidence, and a skip here would let a green run be a run that never executed the store.
Index ¶
Constants ¶
const BinEnv = "NOVA_PG_BIN"
BinEnv names a directory holding initdb, pg_ctl and postgres, for a machine whose install is somewhere the search below does not look.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Server ¶
type Server struct {
Dir string
Bin string
Port string
// User is the superuser initdb made; trust authentication, no password.
User string
// contains filtered or unexported fields
}
Server is one running throwaway Postgres.
func Start ¶
Start is the per-test form: a server under t.TempDir(), stopped by the cleanup, its DSN returned. A missing binary fails the test with the line Binaries returns.
func StartServer ¶
StartServer runs initdb and pg_ctl start under dir on a free loopback port. The caller stops it with Stop. It is the TestMain form: one server for a package, one database per test through Database.
A start that lost its port to another process is made again on a fresh one, five times at most; any other failure is returned with what pg_ctl and the server's log said. A start pg_ctl does not see finish within thirty seconds is an error, and the server it left starting is stopped; so is a server that started and does not answer within thirty seconds.
func (*Server) DSN ¶
DSN is the connection string of one database on the server, for pgx: a loopback address, trust authentication, no password anywhere.
func (*Server) Database ¶
Database creates a fresh, empty database on the server and returns its DSN. Each call is its own database, so parallel tests share the server and nothing else.
Source Files