Documentation
¶
Overview ¶
Package pgsandpit gives each test a PostgreSQL session wrapped in a transaction that is rolled back when the test ends, and hands the test *sql.DB values that run on that session.
var sandpit = pgsandpit.New("postgres://postgres@localhost:5432/postgres")
func TestFoo(t *testing.T) {
t.Parallel()
s := sandpit.Session(t)
db := s.DB()
ro := s.With().ReadOnly().DB()
// db and ro share the session: ro sees what db wrote, and nothing is
// left in the database after the test.
}
Index ¶
- Constants
- Variables
- type DBBuilder
- type Sandpit
- type Session
- type SessionBuilder
- func (b *SessionBuilder) Conn(f func(c *pgx.Conn)) *SessionBuilder
- func (b *SessionBuilder) Connector(f func(driver.Connector) driver.Connector) *SessionBuilder
- func (b *SessionBuilder) ReadOnly() *SessionBuilder
- func (b *SessionBuilder) Session(t *testing.T) *Session
- func (b *SessionBuilder) Timeout(d time.Duration) *SessionBuilder
Constants ¶
const DefaultTimeout = 60 * time.Second
DefaultTimeout is how long a call waits for the session while another transaction holds it, unless the session was built with SessionBuilder.Timeout or the *sql.DB with DBBuilder.Timeout.
Variables ¶
var ( // ErrTimeout is returned, wrapped, when a call waited longer than the // timeout for the session. It usually means a transaction was left open, // or the *sql.DB was used outside a transaction while that transaction was // open in the same goroutine. ErrTimeout = errors.New("pgsandpit: timed out waiting for the session") // ErrSessionClosed is returned when a *sql.DB is used after its session // ended. ErrSessionClosed = errors.New("pgsandpit: session is closed") )
Functions ¶
This section is empty.
Types ¶
type DBBuilder ¶ added in v0.3.0
type DBBuilder struct {
// contains filtered or unexported fields
}
DBBuilder builds a *sql.DB for a Session. Each method returns a new DBBuilder, so a DBBuilder can be shared and branched.
func (*DBBuilder) Conn ¶ added in v0.3.0
Conn sets a function that DB calls once, before it returns, with the session's *pgx.Conn. DB waits for the session as the *sql.DB's calls do, and holds it while f runs.
What f runs, runs in the session's transaction as it is: it is not read-only, and a statement that fails aborts the session's transaction. f must not begin, commit or roll back a transaction, nor use c after it returns.
func (*DBBuilder) Connector ¶ added in v0.3.0
Connector sets a function that is given the connector pgsandpit made for the *sql.DB and returns the connector the *sql.DB is opened with, as by sql.OpenDB. If the session was built with SessionBuilder.Connector, f is given the connector that function returned.
func (*DBBuilder) DB ¶ added in v0.3.0
DB returns the *sql.DB. It is closed when the test ends; closing it earlier does not end the session.
func (*DBBuilder) ReadOnly ¶ added in v0.3.0
ReadOnly makes the *sql.DB reject writes. It still sees what the other *sql.DB values of the session wrote. A rejected write fails only that statement, as in a read-only transaction outside a test, except that inside an application transaction it aborts that transaction. Every *sql.DB of a session built with SessionBuilder.ReadOnly is read-only.
type Sandpit ¶
type Sandpit struct {
// contains filtered or unexported fields
}
Sandpit opens sessions on one database. Create it once per test package.
func New ¶
New returns a Sandpit for the database dsn points to. It does not connect until the first Session call.
func NewWithConfig ¶ added in v0.2.0
func NewWithConfig(cfg *pgx.ConnConfig, opts ...stdlib.OptionOpenDB) *Sandpit
NewWithConfig returns a Sandpit that connects with a copy of cfg and opts, as stdlib.OpenDB does. It does not connect until the first Session call.
pgsandpit replaces cfg.BuildContextWatcherHandler, so that a canceled context cancels the query instead of closing the session's connection.
The connections are pooled across sessions: a hook such as stdlib.OptionAfterConnect runs once per connection, not once per session.
func (*Sandpit) Close ¶
Close closes the connection pool the sessions are taken from. Call it from TestMain after the tests have run, if at all.
func (*Sandpit) Session ¶
Session opens a connection, begins a transaction on it, and returns a Session for it. The transaction is rolled back and the connection closed when t and its subtests finish. Session fails t if it cannot connect. It is the same as sp.With().Session(t).
func (*Sandpit) With ¶ added in v0.3.0
func (sp *Sandpit) With() *SessionBuilder
With starts building a Session with options. The Sandpit itself is not changed.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is one PostgreSQL connection with one transaction open on it. Every *sql.DB made from a Session runs on that connection, so they all see each other's changes. Only one statement, or one application transaction, runs on the session at a time; the others wait.
type SessionBuilder ¶ added in v0.3.0
type SessionBuilder struct {
// contains filtered or unexported fields
}
SessionBuilder builds a Session for a Sandpit. Each method returns a new SessionBuilder, so a SessionBuilder can be shared and branched, and made before the tests run:
var base = sandpit.With().Timeout(5 * time.Second)
func TestFoo(t *testing.T) {
s := base.Session(t)
// ...
}
func (*SessionBuilder) Conn ¶ added in v0.3.0
func (b *SessionBuilder) Conn(f func(c *pgx.Conn)) *SessionBuilder
Conn sets a function that Session calls once, before it returns, with the session's *pgx.Conn, for example to SET a parameter for the session or to insert data the test needs. A parameter SET this way applies to every *sql.DB of the session and is reset when the session's transaction is rolled back.
What f runs, runs in the session's transaction as it is: a statement that fails aborts the session's transaction. f must not begin, commit or roll back a transaction, nor use c after it returns.
func (*SessionBuilder) Connector ¶ added in v0.3.0
func (b *SessionBuilder) Connector(f func(driver.Connector) driver.Connector) *SessionBuilder
Connector sets a function that is given the connector pgsandpit made for each *sql.DB of the session and returns the connector the *sql.DB is opened with. It is called each time a *sql.DB is made. A function set with DBBuilder.Connector is given what f returns.
func (*SessionBuilder) ReadOnly ¶ added in v0.3.0
func (b *SessionBuilder) ReadOnly() *SessionBuilder
ReadOnly makes every *sql.DB of the session reject writes, as DBBuilder.ReadOnly does. A function set with Conn is not affected by it, so it can insert the data the test reads.
func (*SessionBuilder) Session ¶ added in v0.3.0
func (b *SessionBuilder) Session(t *testing.T) *Session
Session opens a connection, begins a transaction on it, and returns a Session for it. The transaction is rolled back and the connection closed when t and its subtests finish. Session fails t if it cannot connect.
func (*SessionBuilder) Timeout ¶ added in v0.3.0
func (b *SessionBuilder) Timeout(d time.Duration) *SessionBuilder
Timeout sets how long a call waits for the session while another transaction holds it. It is the default of DBBuilder.Timeout for the *sql.DB values of the session, and also bounds how long the end of the test waits for the session. The default is DefaultTimeout.