From 8f7312351e7fafd765d95ef9c22f97105ebd7ac4 Mon Sep 17 00:00:00 2001 From: winebarrel Date: Sun, 8 Nov 2026 19:23:04 +0900 Subject: [PATCH] Add SessionBuilder.Interleave Interleave lets statements and transactions run while an application transaction is open, instead of waiting for it: a statement outside the transaction runs inside it in a savepoint of its own, and a transaction begun meanwhile nests inside it. Nested transactions that end out of order fail with ErrTxOrder. Co-Authored-By: Claude Opus 5.5 --- README.md | 17 +++ conn.go | 99 +++++++++++++-- interleave_test.go | 306 +++++++++++++++++++++++++++++++++++++++++++++ session.go | 38 ++++-- session_builder.go | 55 ++++++-- 5 files changed, 484 insertions(+), 31 deletions(-) create mode 100644 interleave_test.go diff --git a/README.md b/README.md index 485d90f..14d0840 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,7 @@ func TestFoo(t *testing.T) { - `Connector` is applied to every `*sql.DB` of the session, each time one is made. A `Connector` set with `s.With().Connector(...)` is given the connector the session's returned. - `Conn` is called once, when `Session` makes the session, with the session's `*pgx.Conn`. A parameter it `SET`s applies to every `*sql.DB` of the session and is reset when the session is rolled back. - `Cache` makes `Session` return the session cached for `t` if there is one, and otherwise open one and cache it, so helpers can get the session from `t` alone. The options of the call that opened the session apply, and those of later calls are ignored. A subtest has its own `t`, so it gets its own session rather than its parent's. +- `Interleave` lets a statement, or a transaction, run while an application transaction is open, instead of waiting for it to end (see Interleave below). ```go var cached = sandpit.With().Cache() @@ -162,6 +163,22 @@ func TestFoo(t *testing.T) { - **Transactions**: `Begin` creates a savepoint, `Commit` releases it, and `Rollback` rolls back to it. `TxOptions` are ignored. Committing a transaction that hit an error rolls it back and returns `pgx.ErrTxCommitRollback`, as PostgreSQL does. - **Statements outside a transaction** each run in their own savepoint, so a failing statement (such as a unique violation) fails alone, as in autocommit mode, instead of aborting the rest of the test. - **Serialization**: one statement, or one transaction, runs on a session at a time; the others wait. A call that waits longer than the timeout (60 seconds by default) returns an error wrapping `pgsandpit.ErrTimeout`, with the stack of the `Begin` that holds the session. This is usually a transaction left open, or a `*sql.DB` used outside a transaction while that transaction is open in the same goroutine. +- **Interleave**: code that begins a transaction on a `*sql.DB` and then, before the transaction ends, uses the `*sql.DB` outside the transaction, or begins another transaction on it, runs on several connections outside a test, but on one session in a test, where the second would wait for the first until it times out. With `sandpit.With().Interleave()`, it does not wait: + - A statement outside the open transaction runs inside it, in a savepoint of its own: it sees what the transaction wrote, a failure fails only that statement, and what it writes is rolled back with the transaction if the transaction rolls back. + - A transaction begun while another is open nests inside it. Nested transactions must end in the reverse order they began. If one ends before a transaction begun after it, PostgreSQL ends the later one with it: a `Commit` of the earlier one rolls both back and returns an error wrapping `pgsandpit.ErrTxOrder`, and so do the later one's statements, `Commit` and `Rollback`. + - Statements still run one at a time. Statements and transactions in other goroutines do not wait for an open transaction either, so transactions that overlap in different goroutines can end out of order. + - A transaction left open at the end of the test fails the test with the stack of its `Begin`. + + ```go + db := sandpit.With().Interleave().Session(t).DB() + + tx, _ := db.Begin() + tx.Exec(`INSERT INTO orders ...`) + db.QueryRow(`SELECT count(*) FROM orders`) // runs inside tx instead of waiting for it + inner, _ := db.Begin() // nests inside tx + inner.Commit() + tx.Commit() + ``` - **Read-only**: a read-only `*sql.DB` runs each statement with `transaction_read_only` on, so PostgreSQL rejects writes, including writes inside functions. - **Rows** are read in full before a query returns, so an open `*sql.Rows` does not hold the session. - **Cancellation**: a canceled context cancels the query on the server and leaves the session usable. A transaction whose context is canceled is rolled back. diff --git a/conn.go b/conn.go index 6937ffd..f195e58 100644 --- a/conn.go +++ b/conn.go @@ -5,6 +5,8 @@ import ( "database/sql" "database/sql/driver" "errors" + "fmt" + "slices" "time" "github.com/jackc/pgx/v5" @@ -36,10 +38,10 @@ var ( _ driver.NamedValueChecker = (*conn)(nil) ) -// acquire makes the session this conn's for one call. A conn that holds the -// session for an application transaction already has it. +// acquire makes the session this conn's for one call. Without interleave, a +// conn that holds the session for an application transaction already has it. func (c *conn) acquire(ctx context.Context) (func(), error) { - if c.tx != nil { + if c.tx != nil && !c.s.interleave { return func() {}, nil } return c.s.acquire(ctx, c.timeout) @@ -62,6 +64,9 @@ func (c *conn) do(ctx context.Context, fn func(context.Context) error) error { defer release() inTx := c.tx != nil + if inTx && c.tx.endedByOuter { + return errEndedByOuter + } if inTx && !c.readOnly { return fn(ctx) } @@ -138,7 +143,9 @@ func (c *conn) QueryContext(ctx context.Context, query string, args []driver.Nam } // BeginTx emulates a transaction with a savepoint. The transaction holds the -// session until it ends. TxOptions are ignored. +// session until it ends. With interleave, it does not: it holds the session +// only while each of its statements runs, and a transaction begun while it is +// open nests inside it. TxOptions are ignored. func (c *conn) BeginTx(ctx context.Context, _ driver.TxOptions) (driver.Tx, error) { if c.tx != nil { return nil, errors.New("pgsandpit: a transaction is already open on this connection") @@ -147,14 +154,25 @@ func (c *conn) BeginTx(ctx context.Context, _ driver.TxOptions) (driver.Tx, erro if err != nil { return nil, err } + if c.s.interleave { + defer release() + release = func() {} + } + name := c.s.savepoint("tx") if _, err := c.s.tx.ExecContext(context.WithoutCancel(ctx), "SAVEPOINT "+name); err != nil { release() return nil, err } - c.s.setHolder(currentStack()) - c.tx = &tx{c: c, name: name, release: release} - return c.tx, nil + stack := currentStack() + t := &tx{c: c, name: name, release: release, begunAt: stack} + if c.s.interleave { + c.s.txs = append(c.s.txs, t) + } else { + c.s.setHolder(stack) + } + c.tx = t + return t, nil } func (c *conn) Begin() (driver.Tx, error) { @@ -205,6 +223,12 @@ type tx struct { c *conn name string release func() + begunAt string // stack of the Begin + + // endedByOuter is set, with interleave, when a transaction that this one + // is nested in ended first and took this one's savepoint with it. Read and + // written only while the session is held. + endedByOuter bool } // Commit releases the savepoint. If the transaction is aborted, it rolls back @@ -215,7 +239,23 @@ func (t *tx) Commit() error { defer func() { t.finish(result) }() ctx := context.Background() - _, err := t.c.s.tx.ExecContext(ctx, "RELEASE SAVEPOINT "+t.name) + release, err := t.acquire(ctx) + if err != nil { + return err + } + defer release() + if t.endedByOuter { + return errEndedByOuter + } + if inner := t.unnest(); len(inner) > 0 { + // Releasing the savepoint would commit what the inner transactions + // wrote, which they have not committed. Roll back instead. + if err := t.c.s.rollbackTo(ctx, t.name); err != nil { + return err + } + return fmt.Errorf("%w: a transaction was committed while %d transaction(s) begun after it were still open, so it was rolled back with them", ErrTxOrder, len(inner)) + } + _, err = t.c.s.tx.ExecContext(ctx, "RELEASE SAVEPOINT "+t.name) var pgErr *pgconn.PgError if errors.As(err, &pgErr) && pgErr.Code == inFailedSQLTransaction { if err := t.c.s.rollbackTo(ctx, t.name); err != nil { @@ -231,7 +271,48 @@ func (t *tx) Commit() error { func (t *tx) Rollback() error { defer t.finish(TxRolledBack) - return t.c.s.rollbackTo(context.Background(), t.name) + ctx := context.Background() + release, err := t.acquire(ctx) + if err != nil { + return err + } + defer release() + if t.endedByOuter { + return errEndedByOuter + } + // Rolling back to the savepoint also rolls back the inner transactions. + t.unnest() + return t.c.s.rollbackTo(ctx, t.name) +} + +// errEndedByOuter is returned when a transaction ends after a transaction it +// is nested in ended and took it with it. +var errEndedByOuter = fmt.Errorf("%w: a transaction begun before this one ended first and rolled this one back", ErrTxOrder) + +// unnest removes the transaction from the open ones, with interleave, and +// returns the transactions nested in it, which end with it. It is called while +// the session is held. +func (t *tx) unnest() []*tx { + s := t.c.s + i := slices.Index(s.txs, t) + if i < 0 { + return nil + } + inner := slices.Clone(s.txs[i+1:]) + s.txs = s.txs[:i] + for _, in := range inner { + in.endedByOuter = true + } + return inner +} + +// acquire takes the session for the statement that ends the transaction. Only +// with interleave does the transaction not hold it already. +func (t *tx) acquire(ctx context.Context) (func(), error) { + if !t.c.s.interleave { + return func() {}, nil + } + return t.c.s.acquire(ctx, t.c.timeout) } func (t *tx) finish(result TxResult) { diff --git a/interleave_test.go b/interleave_test.go new file mode 100644 index 0000000..461c916 --- /dev/null +++ b/interleave_test.go @@ -0,0 +1,306 @@ +package pgsandpit_test + +import ( + "os" + "sync" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "github.com/winebarrel/pgsandpit" +) + +func TestInterleave(t *testing.T) { + t.Parallel() + + t.Run("a statement outside an open transaction does not wait for it", func(t *testing.T) { + t.Parallel() + s := sandpit.With().Interleave().Timeout(time.Second).Session(t) + db := s.DB() + + tx, err := db.Begin() + require.NoError(t, err) + _, err = tx.Exec(`INSERT INTO users (email) VALUES ('interleave-tx@example.com')`) + require.NoError(t, err) + + // Without Interleave, this would wait for tx, which this goroutine holds. + assert.Equal(t, 1, countUsers(t, db, "interleave-tx@example.com")) + _, err = db.Exec(`INSERT INTO users (email) VALUES ('interleave-db@example.com')`) + require.NoError(t, err) + assert.Equal(t, 1, countUsers(t, tx, "interleave-db@example.com")) + + require.NoError(t, tx.Commit()) + assert.Equal(t, 1, countUsers(t, db, "interleave-tx@example.com")) + assert.Equal(t, 1, countUsers(t, db, "interleave-db@example.com")) + assert.Equal(t, []pgsandpit.TxResult{pgsandpit.TxCommitted}, s.TxResults()) + }) + + t.Run("a statement outside a transaction is rolled back with it", func(t *testing.T) { + t.Parallel() + s := sandpit.With().Interleave().Session(t) + db := s.DB() + + tx, err := db.Begin() + require.NoError(t, err) + _, err = db.Exec(`INSERT INTO users (email) VALUES ('interleave-rollback@example.com')`) + require.NoError(t, err) + require.NoError(t, tx.Rollback()) + + assert.Equal(t, 0, countUsers(t, db, "interleave-rollback@example.com")) + assert.Equal(t, []pgsandpit.TxResult{pgsandpit.TxRolledBack}, s.TxResults()) + }) + + t.Run("a failing statement outside a transaction fails alone", func(t *testing.T) { + t.Parallel() + s := sandpit.With().Interleave().Session(t) + db := s.DB() + + tx, err := db.Begin() + require.NoError(t, err) + _, err = tx.Exec(`INSERT INTO users (email) VALUES ('interleave-alone@example.com')`) + require.NoError(t, err) + + _, err = db.Exec(`SELECT * FROM no_such_table`) + require.Error(t, err) + + require.NoError(t, tx.Commit()) + assert.Equal(t, 1, countUsers(t, db, "interleave-alone@example.com")) + assert.Equal(t, []pgsandpit.TxResult{pgsandpit.TxCommitted}, s.TxResults()) + }) + + t.Run("a read-only statement outside a transaction", func(t *testing.T) { + t.Parallel() + s := sandpit.With().Interleave().Session(t) + db := s.DB() + ro := s.With().ReadOnly().DB() + + tx, err := db.Begin() + require.NoError(t, err) + _, err = tx.Exec(`INSERT INTO users (email) VALUES ('interleave-ro@example.com')`) + require.NoError(t, err) + + assert.Equal(t, 1, countUsers(t, ro, "interleave-ro@example.com")) + _, err = ro.Exec(`INSERT INTO users (email) VALUES ('interleave-ro-write@example.com')`) + require.Error(t, err) + + // The transaction is still writable and usable. + _, err = tx.Exec(`INSERT INTO users (email) VALUES ('interleave-ro-after@example.com')`) + require.NoError(t, err) + require.NoError(t, tx.Commit()) + assert.Equal(t, 1, countUsers(t, db, "interleave-ro-after@example.com")) + assert.Equal(t, 0, countUsers(t, db, "interleave-ro-write@example.com")) + }) + + t.Run("a transaction begun while another is open nests inside it", func(t *testing.T) { + t.Parallel() + s := sandpit.With().Interleave().Timeout(time.Second).Session(t) + db := s.DB() + + outer, err := db.Begin() + require.NoError(t, err) + _, err = outer.Exec(`INSERT INTO users (email) VALUES ('interleave-outer@example.com')`) + require.NoError(t, err) + + // Without Interleave, this would wait for outer, which this goroutine holds. + inner, err := db.Begin() + require.NoError(t, err) + assert.Equal(t, 1, countUsers(t, inner, "interleave-outer@example.com")) + _, err = inner.Exec(`INSERT INTO users (email) VALUES ('interleave-inner@example.com')`) + require.NoError(t, err) + require.NoError(t, inner.Commit()) + assert.Equal(t, 1, countUsers(t, outer, "interleave-inner@example.com")) + + rolledBack, err := db.Begin() + require.NoError(t, err) + _, err = rolledBack.Exec(`INSERT INTO users (email) VALUES ('interleave-inner-rollback@example.com')`) + require.NoError(t, err) + require.NoError(t, rolledBack.Rollback()) + assert.Equal(t, 0, countUsers(t, outer, "interleave-inner-rollback@example.com")) + + require.NoError(t, outer.Commit()) + assert.Equal(t, 1, countUsers(t, db, "interleave-outer@example.com")) + assert.Equal(t, 1, countUsers(t, db, "interleave-inner@example.com")) + assert.Equal(t, []pgsandpit.TxResult{ + pgsandpit.TxCommitted, pgsandpit.TxRolledBack, pgsandpit.TxCommitted, + }, s.TxResults()) + }) + + t.Run("a nested transaction is rolled back with the outer one", func(t *testing.T) { + t.Parallel() + db := sandpit.With().Interleave().Session(t).DB() + + outer, err := db.Begin() + require.NoError(t, err) + inner, err := db.Begin() + require.NoError(t, err) + _, err = inner.Exec(`INSERT INTO users (email) VALUES ('interleave-nested-rollback@example.com')`) + require.NoError(t, err) + require.NoError(t, inner.Commit()) + require.NoError(t, outer.Rollback()) + + assert.Equal(t, 0, countUsers(t, db, "interleave-nested-rollback@example.com")) + }) + + t.Run("committing the outer transaction first rolls back both", func(t *testing.T) { + t.Parallel() + s := sandpit.With().Interleave().Session(t) + db := s.DB() + + outer, err := db.Begin() + require.NoError(t, err) + _, err = outer.Exec(`INSERT INTO users (email) VALUES ('interleave-order-outer@example.com')`) + require.NoError(t, err) + inner, err := db.Begin() + require.NoError(t, err) + _, err = inner.Exec(`INSERT INTO users (email) VALUES ('interleave-order-inner@example.com')`) + require.NoError(t, err) + + err = outer.Commit() + require.ErrorIs(t, err, pgsandpit.ErrTxOrder) + require.ErrorIs(t, inner.Commit(), pgsandpit.ErrTxOrder) + + assert.Equal(t, 0, countUsers(t, db, "interleave-order-outer@example.com")) + assert.Equal(t, 0, countUsers(t, db, "interleave-order-inner@example.com")) + assert.Equal(t, []pgsandpit.TxResult{ + pgsandpit.TxCommitFailed, pgsandpit.TxCommitFailed, + }, s.TxResults()) + + // The session is still usable. + tx, err := db.Begin() + require.NoError(t, err) + require.NoError(t, tx.Commit()) + }) + + t.Run("rolling back the outer transaction first ends the inner one", func(t *testing.T) { + t.Parallel() + db := sandpit.With().Interleave().Session(t).DB() + + outer, err := db.Begin() + require.NoError(t, err) + inner, err := db.Begin() + require.NoError(t, err) + _, err = inner.Exec(`INSERT INTO users (email) VALUES ('interleave-order-rollback@example.com')`) + require.NoError(t, err) + + require.NoError(t, outer.Rollback()) + _, err = inner.Exec(`SELECT 1`) + require.ErrorIs(t, err, pgsandpit.ErrTxOrder) + require.ErrorIs(t, inner.Rollback(), pgsandpit.ErrTxOrder) + assert.Equal(t, 0, countUsers(t, db, "interleave-order-rollback@example.com")) + }) + + t.Run("statements run one at a time", func(t *testing.T) { + t.Parallel() + db := sandpit.With().Interleave().Session(t).DB() + + tx, err := db.Begin() + require.NoError(t, err) + + const n = 10 + var wg sync.WaitGroup + for i := range n { + wg.Go(func() { + _, err := db.Exec(`INSERT INTO users (email) VALUES ($1)`, emailN("interleave-concurrent", i)) + assert.NoError(t, err) + }) + wg.Go(func() { + _, err := tx.Exec(`INSERT INTO users (email) VALUES ($1)`, emailN("interleave-concurrent-tx", i)) + assert.NoError(t, err) + }) + } + wg.Wait() + require.NoError(t, tx.Commit()) + + var count int + require.NoError(t, db.QueryRow(`SELECT count(*) FROM users WHERE email LIKE 'interleave-concurrent%'`).Scan(&count)) + assert.Equal(t, 2*n, count) + }) + + t.Run("overlapping transactions in goroutines end in order or fail with ErrTxOrder", func(t *testing.T) { + t.Parallel() + db := sandpit.With().Interleave().Session(t).DB() + + const n = 10 + var wg sync.WaitGroup + for i := range n { + wg.Go(func() { + tx, err := db.Begin() + if !assert.NoError(t, err) { + return + } + if _, err := tx.Exec(`INSERT INTO users (email) VALUES ($1)`, emailN("interleave-overlap", i)); err != nil { + assert.ErrorIs(t, tx.Rollback(), pgsandpit.ErrTxOrder) + return + } + if err := tx.Commit(); err != nil { + assert.ErrorIs(t, err, pgsandpit.ErrTxOrder) + } + }) + } + wg.Wait() + + // The session is still usable. + _, err := db.Exec(`SELECT 1`) + require.NoError(t, err) + }) + + t.Run("without Interleave a statement outside the transaction waits", func(t *testing.T) { + t.Parallel() + db := sandpit.With().Timeout(100 * time.Millisecond).Session(t).DB() + + tx, err := db.Begin() + require.NoError(t, err) + defer tx.Rollback() + + _, err = db.Exec(`SELECT 1`) + require.ErrorIs(t, err, pgsandpit.ErrTimeout) + }) + + t.Run("a wait for a statement does not point at a transaction", func(t *testing.T) { + t.Parallel() + s := sandpit.With().Interleave().Session(t) + slow := s.DB() + db := s.With().Timeout(100 * time.Millisecond).DB() + + tx, err := slow.Begin() + require.NoError(t, err) + + done := make(chan error) + go func() { + _, err := tx.Exec(`SELECT pg_sleep(1)`) + done <- err + }() + time.Sleep(300 * time.Millisecond) // let the slow statement take the session + + _, err = db.Exec(`SELECT 1`) + require.ErrorIs(t, err, pgsandpit.ErrTimeout) + assert.NotContains(t, err.Error(), "begun at") + + require.NoError(t, <-done) + require.NoError(t, tx.Commit()) + }) +} + +func emailN(prefix string, i int) string { + return prefix + "-" + string(rune('a'+i)) + "@example.com" +} + +func TestInterleaveLeakedTxFailsTest(t *testing.T) { + if os.Getenv("PGSANDPIT_CHILD_INTERLEAVE_LEAK") != "" { + db := sandpit.With().Interleave().Session(t).DB() + _, err := db.Begin() // never committed or rolled back + require.NoError(t, err) + return + } + t.Parallel() + + start := time.Now() + out, err := runChild(t, "TestInterleaveLeakedTxFailsTest", "PGSANDPIT_CHILD_INTERLEAVE_LEAK=1") + require.Error(t, err) + // The leaked transaction does not hold the session, so the end of the test + // does not wait for it. + assert.Less(t, time.Since(start), pgsandpit.DefaultTimeout) + assert.Contains(t, out, "pgsandpit: a transaction is still open at the end of the test") + assert.Contains(t, out, "pgsandpit_test.TestInterleaveLeakedTxFailsTest") +} diff --git a/session.go b/session.go index 2981df7..5baa505 100644 --- a/session.go +++ b/session.go @@ -27,28 +27,43 @@ var ( // ErrSessionClosed is returned when a *sql.DB is used after its session // ended. ErrSessionClosed = errors.New("pgsandpit: session is closed") + + // ErrTxOrder is returned, wrapped, with SessionBuilder.Interleave, when + // nested transactions do not end in the reverse order they began, such as + // when transactions in different goroutines overlap. The transactions that + // could not end as asked are rolled back. + ErrTxOrder = errors.New("pgsandpit: transactions ended out of order") ) // 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. +// the session at a time; the others wait. With SessionBuilder.Interleave, +// statements and transactions do not wait for an open application transaction: +// they run, or nest, inside it (see there). type Session struct { t *testing.T conn *sql.Conn tx *sql.Tx // From the SessionBuilder: whether every *sql.DB is read-only, the default - // timeout of the *sql.DB values, and the connector function every *sql.DB - // is opened through. - readOnly bool - timeout time.Duration - connector func(driver.Connector) driver.Connector - - // sem is held while a statement or an application transaction runs. + // timeout of the *sql.DB values, the connector function every *sql.DB is + // opened through, and whether statements interleave with transactions. + readOnly bool + timeout time.Duration + connector func(driver.Connector) driver.Connector + interleave bool + + // sem is held while a statement runs. Without interleave, an application + // transaction holds it until it ends; with interleave, a transaction holds + // it only while each of its statements runs. sem chan struct{} closed bool // read and written only while sem is held + // txs are the open application transactions with interleave, the innermost + // last. Read and written only while sem is held. + txs []*tx + seq atomic.Uint64 mu sync.Mutex @@ -142,7 +157,9 @@ func (s *Session) timeoutError(timeout time.Duration) error { s.mu.Lock() holder := s.holder s.mu.Unlock() - if holder == "" { + // With interleave, transactions do not hold the session, so a wait for it + // is not a wait for a transaction. + if holder == "" || s.interleave { return fmt.Errorf("%w after %s", ErrTimeout, timeout) } return fmt.Errorf("%w after %s: the session is held by a transaction that was begun at:\n%s", ErrTimeout, timeout, holder) @@ -170,6 +187,9 @@ func (s *Session) close() { s.t.Errorf("pgsandpit: the session is still in use at the end of the test: %s", err) } s.closed = true + for _, t := range s.txs { + s.t.Errorf("pgsandpit: a transaction is still open at the end of the test; it was begun at:\n%s", t.begunAt) + } if err := s.tx.Rollback(); err != nil { s.t.Errorf("pgsandpit: failed to roll back the session transaction: %s", err) diff --git a/session_builder.go b/session_builder.go index 59a158c..0a6ffc1 100644 --- a/session_builder.go +++ b/session_builder.go @@ -20,12 +20,13 @@ import ( // // ... // } type SessionBuilder struct { - sp *Sandpit - readOnly bool - timeout time.Duration - connector func(driver.Connector) driver.Connector - conn func(*pgx.Conn) - cache bool + sp *Sandpit + readOnly bool + timeout time.Duration + connector func(driver.Connector) driver.Connector + conn func(*pgx.Conn) + cache bool + interleave bool } // ReadOnly makes every *sql.DB of the session reject writes, as @@ -85,6 +86,33 @@ func (b *SessionBuilder) Cache() *SessionBuilder { return &c } +// Interleave lets a statement run outside an application transaction while +// that transaction is open, instead of waiting for it to end. The statement +// runs at once, inside the open transaction, in a savepoint of its own: it sees +// what the transaction wrote, a failure fails only that statement, and what it +// writes is rolled back with the transaction if the transaction rolls back. +// +// It is for code that begins a transaction on a *sql.DB and then, before the +// transaction ends, uses the *sql.DB outside the transaction, which runs on +// another connection outside a test. Without Interleave, such a statement waits +// for the transaction, which waits for the statement, until ErrTimeout. +// +// A transaction begun while another is open does not wait for it either: it +// nests inside it, in a savepoint inside the open transaction's savepoint. +// Nested transactions must end in the reverse order they began. If one ends +// before a transaction begun after it, PostgreSQL ends the later one with it: +// a Commit of the earlier one rolls both back and returns an error wrapping +// ErrTxOrder, and the later one's Commit or Rollback returns such an error. +// +// Statements still run one at a time. A statement or a transaction in another +// goroutine also runs inside an open transaction instead of waiting for it, so +// transactions that overlap in different goroutines can end out of order. +func (b *SessionBuilder) Interleave() *SessionBuilder { + c := *b + c.interleave = true + return &c +} + // 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. With Cache, @@ -126,13 +154,14 @@ func (b *SessionBuilder) open(t *testing.T) *Session { t.Fatalf("pgsandpit: failed to begin the session transaction: %s", err) } s := &Session{ - t: t, - conn: conn, - tx: tx, - readOnly: b.readOnly, - timeout: b.timeout, - connector: b.connector, - sem: make(chan struct{}, 1), + t: t, + conn: conn, + tx: tx, + readOnly: b.readOnly, + timeout: b.timeout, + connector: b.connector, + interleave: b.interleave, + sem: make(chan struct{}, 1), } // Registered before b.conn runs, so that the session is rolled back even if // b.conn fails the test.