Rename BeginEx to BeginTx and update docs

doc.go

@@ -146,10 +146,9 @@ Raw Bytes Mapping
 
 Transactions
 
-Transactions are started by calling Begin. The second argument can create a transaction with a specified isolation
+Transactions are started by calling Begin.
-level.
 
-    tx, err := conn.Begin(context.Background(), nil)
+    tx, err := conn.Begin(context.Background())
     if err != nil {
         return err
     }
@@ -167,6 +166,11 @@ level.
         return err
     }
 
+The Tx returned from Begin also implements the Begin method. This can be used to implement pseudo nested transactions.
+These are internally implemented with savepoints.
+
+Use BeginTx to control the transaction mode.
+
 Prepared Statements
 
 Prepared statements can be manually created with the Prepare method. However, this is rarely necessary because pgx

pgxpool/conn.go

@@ -70,8 +70,8 @@ func (c *Conn) Begin(ctx context.Context) (pgx.Tx, error) {
 	return c.Conn().Begin(ctx)
 }
 
-func (c *Conn) BeginEx(ctx context.Context, txOptions pgx.TxOptions) (pgx.Tx, error) {
+func (c *Conn) BeginTx(ctx context.Context, txOptions pgx.TxOptions) (pgx.Tx, error) {
-	return c.Conn().BeginEx(ctx, txOptions)
+	return c.Conn().BeginTx(ctx, txOptions)
 }
 
 func (c *Conn) Conn() *pgx.Conn {

pgxpool/pool.go

@@ -364,15 +364,15 @@ func (p *Pool) SendBatch(ctx context.Context, b *pgx.Batch) pgx.BatchResults {
 }
 
 func (p *Pool) Begin(ctx context.Context) (pgx.Tx, error) {
-	return p.BeginEx(ctx, pgx.TxOptions{})
+	return p.BeginTx(ctx, pgx.TxOptions{})
 }
-func (p *Pool) BeginEx(ctx context.Context, txOptions pgx.TxOptions) (pgx.Tx, error) {
+func (p *Pool) BeginTx(ctx context.Context, txOptions pgx.TxOptions) (pgx.Tx, error) {
 	c, err := p.Acquire(ctx)
 	if err != nil {
 		return nil, err
 	}
 
-	t, err := c.BeginEx(ctx, txOptions)
+	t, err := c.BeginTx(ctx, txOptions)
 	if err != nil {
 		return nil, err
 	}

stdlib/sql.go

@@ -209,7 +209,7 @@ func (c *Conn) BeginTx(ctx context.Context, opts driver.TxOptions) (driver.Tx, e
 		pgxOpts.AccessMode = pgx.ReadOnly
 	}
 
-	tx, err := c.conn.BeginEx(ctx, pgxOpts)
+	tx, err := c.conn.BeginTx(ctx, pgxOpts)
 	if err != nil {
 		return nil, err
 	}

tx.go

@@ -68,12 +68,12 @@ var ErrTxCommitRollback = errors.New("commit unexpectedly resulted in rollback")
 // Begin starts a transaction. Unlike database/sql, the context only affects the begin command. i.e. there is no
 // auto-rollback on context cancelation.
 func (c *Conn) Begin(ctx context.Context) (*dbTx, error) {
-	return c.BeginEx(ctx, TxOptions{})
+	return c.BeginTx(ctx, TxOptions{})
 }
 
-// BeginEx starts a transaction with txOptions determining the transaction mode. Unlike database/sql, the context only
+// BeginTx starts a transaction with txOptions determining the transaction mode. Unlike database/sql, the context only
 // affects the begin command. i.e. there is no auto-rollback on context cancelation.
-func (c *Conn) BeginEx(ctx context.Context, txOptions TxOptions) (*dbTx, error) {
+func (c *Conn) BeginTx(ctx context.Context, txOptions TxOptions) (*dbTx, error) {
 	_, err := c.Exec(ctx, txOptions.beginSQL())
 	if err != nil {
 		// begin should never fail unless there is an underlying connection issue or

tx_test.go

@@ -113,13 +113,13 @@ func TestTxCommitSerializationFailure(t *testing.T) {
 	}
 	defer c1.Exec(context.Background(), `drop table tx_serializable_sums`)
 
-	tx1, err := c1.BeginEx(context.Background(), pgx.TxOptions{IsoLevel: pgx.Serializable})
+	tx1, err := c1.BeginTx(context.Background(), pgx.TxOptions{IsoLevel: pgx.Serializable})
 	if err != nil {
 		t.Fatalf("Begin failed: %v", err)
 	}
 	defer tx1.Rollback(context.Background())
 
-	tx2, err := c2.BeginEx(context.Background(), pgx.TxOptions{IsoLevel: pgx.Serializable})
+	tx2, err := c2.BeginTx(context.Background(), pgx.TxOptions{IsoLevel: pgx.Serializable})
 	if err != nil {
 		t.Fatalf("Begin failed: %v", err)
 	}
@@ -196,7 +196,7 @@ func TestBeginIsoLevels(t *testing.T) {
 
 	isoLevels := []pgx.TxIsoLevel{pgx.Serializable, pgx.RepeatableRead, pgx.ReadCommitted, pgx.ReadUncommitted}
 	for _, iso := range isoLevels {
-		tx, err := conn.BeginEx(context.Background(), pgx.TxOptions{IsoLevel: iso})
+		tx, err := conn.BeginTx(context.Background(), pgx.TxOptions{IsoLevel: iso})
 		if err != nil {
 			t.Fatalf("conn.Begin failed: %v", err)
 		}
@@ -220,7 +220,7 @@ func TestBeginReadOnly(t *testing.T) {
 	conn := mustConnectString(t, os.Getenv("PGX_TEST_DATABASE"))
 	defer closeConn(t, conn)
 
-	tx, err := conn.BeginEx(context.Background(), pgx.TxOptions{AccessMode: pgx.ReadOnly})
+	tx, err := conn.BeginTx(context.Background(), pgx.TxOptions{AccessMode: pgx.ReadOnly})
 	if err != nil {
 		t.Fatalf("conn.Begin failed: %v", err)
 	}