Skip to content
Open
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
14 changes: 14 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,20 @@ See documentation and more usage examples at https://pkg.go.dev/github.com/fireb
Wire compression is disabled by default. Enable it with `wire_compression=true` in the connection string
(`wire_compress` and `wireCompression` are accepted aliases) or with `FBWIRECOMPRESSION=true`.

Set `default_transaction_isolation=read_committed` in a keyword/value connection
string, or `?default_transaction_isolation=read_committed` in a URL, to choose
the default transaction isolation. Supported values are `read_committed`,
`repeatable_read`, and `serializable`. In connection strings, the aliases
`read committed` and `repeatable read` are also accepted and normalized to the
underscore values; an empty value preserves the server default.
The setting also applies to autocommit, `Begin`, and `database/sql` transactions
using `sql.LevelDefault`. An explicit `TxOptions.IsoLevel` or `sql.TxOptions.Isolation`
overrides it. Raw TPBs passed to `BeginTxTPB` or `StartTransactionTPB` are unchanged.
SQL `SET TRANSACTION` statements use the options in the SQL and server defaults
for any omitted options.
The same setting is available as `Config.DefaultTransactionIsolation`, using
`fbconn.TxIsoLevel` and its constants (`fbx.TxIsoLevel` is an alias).

For cursor queries, the driver automatically uses the server's deferred-execute flag from
`Prepare`. When supported, `Exec` buffers `Execute`; the first row read sends
`Execute` and `Fetch` together. A result closed before reading sends `Execute`
Expand Down
85 changes: 85 additions & 0 deletions default_transaction_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
package fbx_test

import (
"context"
"fmt"
"os"
"testing"
"time"

"github.com/firebirdsql/fbx"
"github.com/firebirdsql/fbx/fbproto"
"github.com/stretchr/testify/require"
)

func TestDefaultTransactionIsolation(t *testing.T) {
if os.Getenv("FBX_TEST_DATABASE") == "" {
t.Skip("FBX_TEST_DATABASE is not set")
}
t.Parallel()
ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
defer cancel()
const query = "select mon$isolation_mode, mon$read_only, mon$lock_timeout from mon$transactions where mon$transaction_id = current_transaction"
for _, isolation := range []fbx.TxIsoLevel{fbx.ReadCommitted, fbx.RepeatableRead, fbx.Serializable} {
for _, autocommit := range []bool{true, false} {
t.Run(fmt.Sprintf("%s/autocommit=%t", isolation, autocommit), func(t *testing.T) {
config, err := fbx.ParseConfig(os.Getenv("FBX_TEST_DATABASE"))
require.NoError(t, err)
config.DefaultTransactionIsolation = isolation
config.DefaultTransactionReadOnly = true
config.Autocommit = autocommit
conn := mustConnect(t, config)
defer closeConn(t, conn)
want := map[fbx.TxIsoLevel]int{fbx.ReadCommitted: 4, fbx.RepeatableRead: 1, fbx.Serializable: 0}[isolation]
if isolation == fbx.ReadCommitted && conn.ServerVersion().Major <= 3 {
want = 2
}

var iso, readOnly, lockTimeout int
for _, mode := range []fbx.QueryExecMode{fbx.QueryExecModeCacheStatement, fbx.QueryExecModeExec} {
require.NoError(t, conn.QueryRow(ctx, query, mode).Scan(&iso, &readOnly, &lockTimeout))
require.Equal(t, want, iso)
require.Equal(t, 1, readOnly)
}
if !autocommit {
require.NoError(t, conn.Commit(ctx))
}

for _, opts := range []fbx.TxOptions{
{},
{AccessMode: fbx.ReadOnly, LockTimeout: 7 * time.Second},
{IsoLevel: fbx.RepeatableRead},
} {
tx, err := conn.BeginTx(ctx, opts)
require.NoError(t, err)
func() {
defer func() { require.NoError(t, tx.Rollback(ctx)) }()
require.NoError(t, tx.QueryRow(ctx, query).Scan(&iso, &readOnly, &lockTimeout))
if opts.IsoLevel != "" {
require.Equal(t, 1, iso)
} else {
require.Equal(t, want, iso)
}
if opts.AccessMode == fbx.ReadOnly {
require.Equal(t, 1, readOnly)
require.Equal(t, 7, lockTimeout)
} else {
require.Zero(t, readOnly, "implicit read-only setting must not change explicit transactions")
}
}()
}

for _, raw := range [][]byte{nil, {}, {fbproto.Isc_tpb_version3, fbproto.Isc_tpb_concurrency}} {
tx, err := conn.BeginTxTPB(ctx, raw)
require.NoError(t, err)
func() {
defer func() { require.NoError(t, tx.Rollback(ctx)) }()
require.NoError(t, tx.QueryRow(ctx, query).Scan(&iso, &readOnly, &lockTimeout))
require.Equal(t, 1, iso, "raw TPB must preserve server defaults")
require.Zero(t, readOnly)
}()
}
})
}
}
}
28 changes: 22 additions & 6 deletions fbconn/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -49,12 +49,20 @@ type Config struct {
DPB []byte
ClientVersion string
DefaultTransactionReadOnly bool
Autocommit bool
BlobBufferSize int
UseStreamBlobs bool
MaxInlineBlobSize int
MaxBlobCacheSize int
FetchBatchSize int
// DefaultTransactionIsolation is [Serializable], [RepeatableRead], or
// [ReadCommitted]. Connection strings also accept "repeatable read" and
// "read committed", normalized to the corresponding constants.
// Empty preserves the server default. It applies to
// implicit transactions (including autocommit) and transaction APIs called
// without an explicit isolation level. Raw TPBs and SQL transaction commands
// are passed through unchanged.
DefaultTransactionIsolation TxIsoLevel
Autocommit bool
BlobBufferSize int
UseStreamBlobs bool
MaxInlineBlobSize int
MaxBlobCacheSize int
FetchBatchSize int

// ConstructorOptions allows to pass callbacks for setting parameters to authentication plugins.
ConstructorOptions map[string][]auth.ConstructorOption
Expand Down Expand Up @@ -349,6 +357,13 @@ func ParseConfigWithOptions(connString string, options ParseConfigOptions) (*Con
UseStreamBlobs: convertToBool(settings["use_stream_blobs"], true),
FetchBatchSize: DefaultFetchBatchSize,
}
if s, ok := settings["default_transaction_isolation"]; ok {
isolation := TxIsoLevel(strings.ReplaceAll(strings.ToLower(strings.TrimSpace(s)), " ", "_"))
if _, err := defaultTransactionTPB(isolation, false); err != nil {
return nil, &ParseConfigError{ConnString: connString, msg: "invalid default_transaction_isolation", err: err}
}
config.DefaultTransactionIsolation = isolation
}
if s, ok := settings["max_inline_blob_size"]; ok {
value, err := parsePositiveIntSetting(s)
if err != nil {
Expand Down Expand Up @@ -415,6 +430,7 @@ func ParseConfigWithOptions(connString string, options ParseConfigOptions) (*Con
"client_version": {},
"encoding": {},
"default_transaction_read_only": {},
"default_transaction_isolation": {},
"autocommit": {},
"blob_buffer_size": {},
"use_stream_blobs": {},
Expand Down
1 change: 1 addition & 0 deletions fbconn/config_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -674,6 +674,7 @@ func assertConfigsEqual(t *testing.T, expected, actual *fbconn.Config, testName
assert.Equalf(t, expected.Password, actual.Password, "%s - Password", testName)
assert.Equalf(t, expected.ConnectTimeout, actual.ConnectTimeout, "%s - ConnectTimeout", testName)
assert.Equalf(t, expected.WireCompression, actual.WireCompression, "%s - WireCompression", testName)
assert.Equalf(t, expected.DefaultTransactionIsolation, actual.DefaultTransactionIsolation, "%s - DefaultTransactionIsolation", testName)
assert.Equalf(t, expected.RuntimeParams, actual.RuntimeParams, "%s - RuntimeParams", testName)
expectedFetchBatchSize := expected.FetchBatchSize
if expectedFetchBatchSize == 0 {
Expand Down
31 changes: 19 additions & 12 deletions fbconn/fbconn.go
Original file line number Diff line number Diff line change
Expand Up @@ -247,6 +247,9 @@ func connectConfig(ctx context.Context, config *Config, target connectTarget) (*
if !config.createdByParseConfig {
panic("config must be created by ParseConfig")
}
if _, err := defaultTransactionTPB(config.DefaultTransactionIsolation, false); err != nil {
return nil, &ConnectError{Config: config, err: err}
}

var allErrors []error

Expand Down Expand Up @@ -3269,17 +3272,14 @@ func Construct(hc *HijackedConn) (*FbConn, error) {
func (fbConn *FbConn) ensureInternalTransaction(ctx context.Context, tpb []byte, locked bool) (*FBTransaction, error) {
if fbConn.internalTransaction == nil || fbConn.internalTransaction.Closed {

var txTpb []byte
if tpb != nil {
txTpb = tpb
} else {
if fbConn.config.DefaultTransactionReadOnly {
w := fbproto.NewTPBWriterV3()
w.PutTag(fbproto.Isc_tpb_read)
txTpb = w.Bytes()
if tpb == nil {
var err error
tpb, err = defaultTransactionTPB(fbConn.config.DefaultTransactionIsolation, fbConn.config.DefaultTransactionReadOnly)
if err != nil {
return nil, err
}
}
tx, err := fbConn.startTransactionTPB(ctx, txTpb, locked)
tx, err := fbConn.startTransactionTPB(ctx, tpb, locked)
if err != nil {
return nil, err
}
Expand All @@ -3289,12 +3289,19 @@ func (fbConn *FbConn) ensureInternalTransaction(ctx context.Context, tpb []byte,
return fbConn.internalTransaction, nil
}

// StartTransaction starts new transaction not bound to connection
// StartTransaction starts a transaction not bound to the connection, using
// DefaultTransactionIsolation, or the server's default isolation if the setting
// is empty.
func (fbConn *FbConn) StartTransaction(ctx context.Context) (*FBTransaction, error) {
return fbConn.StartTransactionTPB(ctx, nil)
tpb, err := defaultTransactionTPB(fbConn.config.DefaultTransactionIsolation, false)
if err != nil {
return nil, err
}
return fbConn.StartTransactionTPB(ctx, tpb)
}

// StartTransactionTPB starts new transaction not bound to connection with TPB block
// StartTransactionTPB starts a transaction not bound to the connection. The TPB
// is passed to the server as-is, including nil or empty TPBs.
func (fbConn *FbConn) StartTransactionTPB(ctx context.Context, tpb []byte) (*FBTransaction, error) {
return fbConn.startTransactionTPB(ctx, tpb, false)
}
Expand Down
40 changes: 40 additions & 0 deletions fbconn/transaction_options.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
package fbconn

import (
"fmt"

"github.com/firebirdsql/fbx/fbproto"
)

// TxIsoLevel is the transaction isolation level ([Serializable], [RepeatableRead], [ReadCommitted]).
type TxIsoLevel string

// Transaction isolation levels.
const (
Serializable TxIsoLevel = "serializable"
RepeatableRead TxIsoLevel = "repeatable_read"
ReadCommitted TxIsoLevel = "read_committed"
)

func defaultTransactionTPB(isolation TxIsoLevel, readOnly bool) ([]byte, error) {
if isolation == "" && !readOnly {
return nil, nil
}
tpb := fbproto.NewTPBWriterV3()
if readOnly {
tpb.PutTag(fbproto.Isc_tpb_read)
}
switch isolation {
case "":
case Serializable:
tpb.PutTag(fbproto.Isc_tpb_consistency)
case RepeatableRead:
tpb.PutTag(fbproto.Isc_tpb_concurrency)
case ReadCommitted:
tpb.PutTag(fbproto.Isc_tpb_read_committed)
tpb.PutTag(fbproto.Isc_tpb_rec_version)
default:
return nil, fmt.Errorf("unknown default transaction isolation: %q", isolation)
}
return tpb.Bytes(), nil
}
96 changes: 96 additions & 0 deletions fbconn/transaction_options_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
package fbconn

import (
"context"
"net"
"testing"

"github.com/firebirdsql/fbx/fbproto"
"github.com/stretchr/testify/require"
)

func TestDefaultTransactionTPB(t *testing.T) {
for _, tt := range []struct {
isolation TxIsoLevel
tags []byte
}{
{"", nil},
{"serializable", []byte{fbproto.Isc_tpb_consistency}},
{"repeatable_read", []byte{fbproto.Isc_tpb_concurrency}},
{"read_committed", []byte{fbproto.Isc_tpb_read_committed, fbproto.Isc_tpb_rec_version}},
} {
for _, readOnly := range []bool{false, true} {
tpb, err := defaultTransactionTPB(tt.isolation, readOnly)
require.NoError(t, err)
var expected []byte
if readOnly || tt.isolation != "" {
expected = []byte{fbproto.Isc_tpb_version3}
if readOnly {
expected = append(expected, fbproto.Isc_tpb_read)
}
expected = append(expected, tt.tags...)
}
require.Equal(t, expected, tpb, "isolation=%q readOnly=%t", tt.isolation, readOnly)
}
}
for _, isolation := range []TxIsoLevel{"invalid", "read committed", "repeatable read"} {
_, err := defaultTransactionTPB(isolation, false)
require.Error(t, err, "isolation=%q", isolation)
}
}

func TestParseConfigDefaultTransactionIsolation(t *testing.T) {
for _, tt := range []struct {
connString string
isolation TxIsoLevel
}{
{"", ""},
{"default_transaction_isolation=''", ""},
{"default_transaction_isolation=' '", ""},
{"default_transaction_isolation=' REPEATABLE_READ '", "repeatable_read"},
{"default_transaction_isolation=' REPEATABLE READ '", "repeatable_read"},
{"default_transaction_isolation='read committed'", "read_committed"},
{"default_transaction_isolation=serializable", "serializable"},
{"default_transaction_isolation=read_committed", "read_committed"},
{"default_transaction_isolation=repeatable_read", "repeatable_read"},
{"default_transaction_isolation=' READ_COMMITTED '", "read_committed"},
{"firebird://localhost/test?default_transaction_isolation=read_committed", "read_committed"},
{"firebird://localhost/test?default_transaction_isolation=repeatable_read", "repeatable_read"},
{"firebird://localhost/test?default_transaction_isolation=read%20committed", "read_committed"},
{"firebird://localhost/test?default_transaction_isolation=repeatable%20read", "repeatable_read"},
} {
t.Run(tt.connString, func(t *testing.T) {
config, err := ParseConfig(tt.connString)
require.NoError(t, err)
require.Equal(t, tt.isolation, config.DefaultTransactionIsolation)
require.Equal(t, tt.isolation, config.Copy().DefaultTransactionIsolation)
require.NotContains(t, config.RuntimeParams, "default_transaction_isolation")
})
}
for _, value := range []string{"read uncommitted", "read_uncommitted", "read__committed", "read committed", "snapshot", "invalid"} {
config, err := ParseConfig("default_transaction_isolation='" + value + "'")
require.Nil(t, config)
var parseErr *ParseConfigError
require.ErrorAs(t, err, &parseErr)
require.Contains(t, err.Error(), "default_transaction_isolation")
}
}

func TestConnectRejectsInvalidDefaultTransactionIsolation(t *testing.T) {
for _, isolation := range []TxIsoLevel{"invalid", "read committed", "repeatable read"} {
t.Run(string(isolation), func(t *testing.T) {
config, err := ParseConfig("")
require.NoError(t, err)
config.DefaultTransactionIsolation = isolation
config.DialFunc = func(context.Context, string, string) (net.Conn, error) {
t.Fatal("invalid isolation must be rejected before dialing")
return nil, nil
}
conn, err := ConnectConfig(context.Background(), config)
require.Nil(t, conn)
var connectErr *ConnectError
require.ErrorAs(t, err, &connectErr)
require.ErrorContains(t, err, "unknown default transaction isolation")
})
}
}
2 changes: 2 additions & 0 deletions fbservice/backup_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -254,6 +254,7 @@ func TestManagerClearsDatabaseOnlyConnectionSettings(t *testing.T) {
"host=localhost user=sysdba password=masterkey database=employee " +
"create_database=true target_session_attrs=read-write " +
"default_transaction_read_only=true application_name=fbservice-test " +
"default_transaction_isolation=read_committed " +
"autocommit=true blob_buffer_size=1 use_stream_blobs=true " +
"max_inline_blob_size=1 max_blob_cache_size=1 fetch_batch_size=1",
)
Expand Down Expand Up @@ -375,6 +376,7 @@ func requireDatabaseConnectionSettingsCleared(t *testing.T, config *fbconn.Confi
require.Empty(t, config.Database)
require.False(t, config.CreateDatabase)
require.False(t, config.DefaultTransactionReadOnly)
require.Empty(t, config.DefaultTransactionIsolation)
require.False(t, config.Autocommit)
require.Zero(t, config.BlobBufferSize)
require.False(t, config.UseStreamBlobs)
Expand Down
1 change: 1 addition & 0 deletions fbservice/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,7 @@ func scrubDatabaseConnectionSettings(config *fbconn.Config) {
config.Database = ""
config.CreateDatabase = false
config.DefaultTransactionReadOnly = false
config.DefaultTransactionIsolation = ""
config.Autocommit = false
config.BlobBufferSize = 0
config.UseStreamBlobs = false
Expand Down
Loading
Loading