README
¶
Transaction
Overview
The Transaction package provides utilities for managing transactions in distributed systems. It offers tools and patterns for ensuring data consistency across multiple services and databases in a distributed environment, focusing on maintaining the ACID properties (Atomicity, Consistency, Isolation, Durability) as much as possible in distributed scenarios where traditional database transactions are not feasible.
Features
- Saga Pattern: Implementation of the Saga pattern for distributed transactions
- Automatic Rollback: Automatic rollback of operations when a transaction fails
- Error Handling: Detailed error information when transactions fail
- Context Support: Support for context cancellation and timeouts
- Logging: Comprehensive logging of transaction events
Installation
go get github.com/abitofhelp/servicelib/transaction
Quick Start
See the Basic Usage example for a complete, runnable example of how to use the transaction package.
Configuration
The transaction package does not require specific configuration. It is designed to be used with your existing logging and context infrastructure.
API Documentation
Core Types
The transaction package provides several core types for managing distributed transactions.
Transaction
The Transaction type is the main struct in the saga subpackage that manages a sequence of operations and their rollbacks. It provides methods for adding operations and executing the transaction.
See the Basic Saga example for a complete, runnable example of how to use the Transaction type.
Operation
The Operation type is a function type that represents a local transaction. It takes a context.Context parameter and returns an error.
RollbackOperation
The RollbackOperation type is a function type that represents a compensating transaction. It takes a context.Context parameter and returns an error.
Key Methods
The transaction package provides several key methods for managing distributed transactions.
WithTransaction
The WithTransaction function is a helper function for executing a function within a transaction. It creates a new transaction, executes the provided function, and then executes the transaction.
See the Basic Usage example for a complete, runnable example of how to use the WithTransaction function.
AddOperation
The AddOperation method adds an operation and its corresponding rollback operation to a transaction.
Execute
The Execute method executes all operations in a transaction. If any operation fails, it rolls back all previously executed operations in reverse order.
Examples
For complete, runnable examples, see the following directories in the EXAMPLES directory:
- Basic Usage - Shows basic usage of the transaction package
- Basic Saga - Shows how to use the Saga pattern for distributed transactions
- Error Handling - Shows how to handle errors in transactions
- Context Timeout - Shows how to handle context timeouts
- Custom Transaction - Shows how to create custom transaction types
- Idempotent Operations - Shows how to create idempotent operations
Best Practices
- Define Clear Boundaries: Clearly define the boundaries of your transactions to minimize the scope and duration.
- Keep Operations Idempotent: Design operations to be idempotent so they can be safely retried.
- Design Effective Rollbacks: Ensure rollback operations effectively undo the effects of their corresponding operations.
- Handle Rollback Failures: Be prepared to handle failures in rollback operations, possibly requiring manual intervention.
- Use Timeouts: Set appropriate timeouts for operations to prevent transactions from hanging indefinitely.
Troubleshooting
Common Issues
Rollback Failures
If a rollback operation fails, the transaction will continue to execute the remaining rollback operations but will include information about the failed rollbacks in the returned error. You may need to implement additional error handling or manual intervention for these cases.
Context Cancellation
If the context is canceled during a transaction, the transaction will be aborted and any completed operations will be rolled back. Ensure your context management is appropriate for the transaction's expected duration.
Related Components
- Errors - The transaction package uses the errors package for error handling and reporting.
- Logging - The transaction package uses the logging package for logging transaction events.
- Context - The transaction package uses the context package for context management.
Contributing
Contributions to this component are welcome! Please see the Contributing Guide for more information.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Documentation
¶
Overview ¶
Package transaction provides utilities for managing transactions in distributed systems.
This package offers tools and patterns for ensuring data consistency across multiple services and databases in a distributed environment. It focuses on maintaining the ACID properties (Atomicity, Consistency, Isolation, Durability) as much as possible in distributed scenarios where traditional database transactions are not feasible.
The package is organized into several subpackages:
- saga: Implementation of the Saga pattern for distributed transactions
The Saga pattern, implemented in the saga subpackage, is particularly useful for maintaining data consistency across multiple services without using two-phase commit. It works by defining a sequence of local transactions, each with a corresponding compensating transaction that can undo its effects if a failure occurs.
Example usage of the saga pattern:
err := saga.WithTransaction(ctx, logger, func(tx *saga.Transaction) error {
// Add operations and their rollbacks to the transaction
tx.AddOperation(
// Operation to create a user
func(ctx context.Context) error {
return userRepo.Create(ctx, user)
},
// Rollback operation to delete the user if a later operation fails
func(ctx context.Context) error {
return userRepo.Delete(ctx, user.ID)
},
)
// Add more operations as needed
return nil
})
Future additions to this package may include:
- Two-phase commit implementation
- Outbox pattern for reliable message publishing
- Distributed locking mechanisms
- Transaction coordination services
When working with distributed transactions, it's important to consider:
- The CAP theorem (Consistency, Availability, Partition tolerance)
- The trade-offs between strong consistency and eventual consistency
- The impact of network failures and service unavailability
- The performance implications of distributed transaction patterns
This package aims to provide tools that help developers make informed decisions about these trade-offs and implement reliable transaction management in their distributed systems.
Source Files
Directories