Documentation
¶
Overview ¶
Package pgtest is test support for apps that test against a real PostgreSQL: it creates a uniquely named database per test run, empties it between tests, drops it at the end, and sweeps the databases left behind by runs that died.
It drops databases on whatever server the config points at, so it only drops a database whose name has the stamp Create appends: Sweep only drops names that match the exact pattern Create uses for the base name, skips databases with an open session, and never forces the drop. Drop is the only forced drop, it drops the one database it is given, and it refuses a name without the stamp, such as the base name itself.
It needs PostgreSQL 13 or later for DROP DATABASE ... WITH (FORCE).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Create ¶
func Create(cfg postgres.ConnectionConfig) (postgres.ConnectionConfig, error)
Create makes a new database for one test run and returns the config that points at it. cfg.Database is the base name, at most 35 bytes; the database is named <base>_<unix seconds>_<16 hex chars>, lowercased, so Sweep can recognise it and tell its age.
synchronous_commit is turned off for it, so no session on it waits for its WAL flush on commit. The database is thrown away after the run, so losing the last commits on a crash costs nothing, while the per-test fixtures and truncates stop paying an fsync each. When that fails the database is dropped before the error is returned.
Create, Drop and Sweep run their own statements with a statement timeout of at least the default of the postgres package, and a read timeout longer than that statement timeout: the timeouts of cfg are for the queries of the tests, and CREATE and DROP DATABASE can outlast short ones on a busy server. A statement or read timeout of cfg that is longer is kept, the dial and write timeouts are used as given, and the config Create returns carries the timeouts of cfg unchanged.
The read timeout also bounds the wait for the server's first answer, so a server that accepts the connection and then says nothing is waited on for that read timeout, 35 seconds with the defaults, and not for the read timeout of cfg. One that does not accept the connection is given up on after the dial timeout of cfg.
func Drop ¶
func Drop(cfg postgres.ConnectionConfig) error
Drop drops the database cfg.Database, ending any session still connected to it. Dropping a database that does not exist is not an error. It is the only forced drop in the package, so it takes the config Create returned and refuses a name that does not end in Create's stamp: passing the base config by mistake must not drop the database of that name. See Create for the timeouts the drop runs with.
func Sweep ¶
Sweep drops the databases Create left behind under the base name cfg.Database that are older than maxAge and have no open session. Such a database was left by a run that died before dropping it: interrupted, killed by -timeout, or failed to drop.
Only names that match the exact pattern Create generates for the base name are considered. A database with an open session still belongs to a live run, such as a test paused in a debugger, so it is skipped, and the drop is not forced: if a session connects after the listing, PostgreSQL refuses the drop instead of terminating it. A failed drop does not stop the others, but the sweep stops once ctx is done and leaves the rest for a later run. The error returned holds what failed, joined with errors.Join.
See Create for the timeouts the sweep runs with. Connecting to the server is not bound by ctx, only by those timeouts. A ctx deadline earlier than the statement timeout cuts the wait for a drop short, and the server may still finish that drop after Sweep has reported it as failed.
func Truncate ¶
func Truncate(ctx context.Context, db *relational.DB) error
Truncate empties every table in the public schema and restarts their sequences. bun's migration ledger (bun_migrations, bun_migration_locks) is kept: an empty bun_migrations lacks the baseline floor row, and the next boot on this database would refuse it. A table that belongs to an extension is kept too, since its rows are the extension's and not test data. The truncate cascades, so a table outside that set with a foreign key to one of the emptied tables is emptied with them.
Types ¶
This section is empty.
Source Files