db

func Tx ¶

func Tx(ctx context.Context, db *Replica, fn func(context.Context, DBTX) error) error

Tx executes fn within a database transaction without returning a result. It is a convenience wrapper around TxWithResult for operations that only need error handling.

Tx begins a transaction on db, executes fn with the transaction context, and commits on success or rolls back on failure. All database errors are wrapped with ServiceUnavailable fault codes.

The ctx parameter provides cancellation and timeout control. The db parameter must be a valid Replica instance. The fn parameter receives the transaction context and a DBTX interface for database operations.

Tx returns nil on successful commit, or an error if any step fails. Error handling follows the same patterns as TxWithResult.

Use Tx for operations that don't need to return values, such as:

• Deleting records with audit logging
• Updating configuration settings
• Batch cleanup operations
• State changes that only need success/failure indication

See TxWithResult for detailed transaction behavior and DBTX for available database operations.

func TxWithResult ¶

func TxWithResult[T any](ctx context.Context, db *Replica, fn func(context.Context, DBTX) (T, error)) (T, error)

TxWithResult executes fn within a database transaction and returns the result. It begins a transaction on db, executes fn with the transaction context, and commits on success or rolls back on failure.

The function automatically handles the complete transaction lifecycle: begin, execute, and commit/rollback.

TxWithResult is generic and preserves type safety for return values. The ctx parameter provides cancellation and timeout control for the entire transaction. The db parameter must be a valid Replica instance, typically from [Database.Primary] for write operations.

The fn parameter receives the transaction context and a DBTX interface for database operations. It should perform all required operations and return the result with any error.

TxWithResult returns the function result on successful commit, or an error if any step fails. Transaction begin errors return ServiceUnavailable. Rollback errors during error handling also return ServiceUnavailable, except for sql.ErrTxDone which indicates the transaction was already completed. Commit errors return ServiceUnavailable.

Context cancellation triggers automatic rollback. The function is safe for concurrent use but callers must avoid operations that could deadlock with other concurrent transactions.

Common usage scenarios include:

• Creating tenants with associated information atomically
• Batch operations that must succeed or fail as a unit
• Complex queries requiring consistency guarantees

Edge cases and limitations:

• If fn returns an error, rollback is attempted even if the transaction is already in a failed state, which may produce additional errors
• Database connection issues during commit may leave the transaction in an undefined state on the server side
• Context cancellation after fn execution causes rollback instead of commit

Anti-patterns to avoid:

• Long-running operations within fn that could timeout
• Nesting calls to TxWithResult (creates nested transactions)
• Ignoring the returned error from fn
• Accessing the DBTX parameter outside of the fn callback

Use context.WithTimeout to prevent indefinite blocking. For operations that may conflict, implement retry logic with exponential backoff at the caller level.

See Replica.Begin for transaction initiation and DBTX for available operations within transactions. For read-only operations that don't require transactions, use query methods directly on Database.RO.

func UnmarshalNullableJSONTo ¶

func UnmarshalNullableJSONTo[T any](data any) (T, error)

UnmarshalNullableJSONTo unmarshals JSON data from database columns into Go types. It handles the common pattern where database queries return JSON as []byte that needs to be deserialized into structs, slices, or maps.

The function accepts 'any' type because database drivers return interface{} for JSON columns, even though the underlying value is typically []byte.

Returns:

• (T, nil) on successful unmarshal
• (zero, nil) if data is nil or empty []byte (these are valid null/empty states)
• (zero, error) if type assertion fails or JSON unmarshal fails

Example usage:

settings, err := UnmarshalNullableJSONTo[Type](row.Type)
if err != nil {
    logger.Error("failed to unmarshal type", "error", err)
    return err
}