Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down Expand Up @@ -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.
Expand Down
99 changes: 90 additions & 9 deletions conn.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ import (
"database/sql"
"database/sql/driver"
"errors"
"fmt"
"slices"
"time"

"github.com/jackc/pgx/v5"
Expand Down Expand Up @@ -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)
Expand All @@ -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)
}
Expand Down Expand Up @@ -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")
Expand All @@ -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) {
Expand Down Expand Up @@ -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
Expand All @@ -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 {
Expand All @@ -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) {
Expand Down
Loading
Loading