Documentation
¶
Index ¶
- func DeriveColumnNamesFromTags[T any](entity T, tagKey string) ([]string, error)
- func GenerateRandomInt64Id() int64
- func StructsToRows[T any](entities []T, tagKey string) ([][]interface{}, error)
- type Batch
- type ConnConfig
- type DbShard
- type InstanceManager
- type MasterReplicaManager
- type PreparedStatement
- type PreparedStatementsMap
- type RowConvertibleEntity
- type ShardManager
- type Transaction
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DeriveColumnNamesFromTags ¶
DeriveColumnNamesFromTags extracts column names from a struct's tags. It uses reflection over the fields of a struct and retrieves the tag values specified by `tagKey` (e.g., "db"). Only exported fields (those with an uppercase first letter) that contain a non-empty tag and are not marked with `"-"` will be included in the returned slice.
The purpose of this function is to automatically map struct fields to database column names ¶
Arguments:
- entity: The struct from which to derive the column names. Can be a pointer or a value.
- tagKey: The key of the tag to extract values from (e.g., "db" for database column mapping).
Returns:
- []string: A slice of column names derived from the specified tag on the struct fields.
- error: Any error encountered
Example:
type Example struct {
ID int `db:"id"`
Name string `db:"name"`
Age int `db:"age"`
}
columns, _ := DeriveColumnNamesFromTags(Example{}, "db")
// columns would be: []string{"id", "name", "age"}
func GenerateRandomInt64Id ¶
func GenerateRandomInt64Id() int64
GenerateRandomInt64Id generates a random 64-bit ID.
This function generates a random, non-zero 64-bit integer that can be used as a unique identifier for transactions or other purposes requiring a unique ID. It uses the crypto/rand package to ensure cryptographic randomness, which is important for scenarios where predictable IDs could lead to security vulnerabilities.
The function ensures that the generated ID is non-zero by continuously generating a new ID if the result is zero. This prevents issues that could arise from using zero as a special case or invalid ID.
Returns:
- int64: A random, non-zero 64-bit integer, which can be used as a unique transaction ID.
Example Usage:
txID := GenerateRandomInt64Id()
log.Printf("Generated transaction ID: %d", txID)
func StructsToRows ¶
StructsToRows converts a slice of structs to a [][]interface{} for use with pgx.CopyFromRows. This uses reflection to extract the values of each struct field.
Types ¶
type Batch ¶
Batch defines the interface for managing a batch of SQL statements to be executed within a transaction.
A Batch allows multiple SQL statements to be queued together and executed in a single batch operation, which can improve performance by reducing the number of round trips to the database. This interface abstracts the batch management
Methods:
- GetBatch: Returns the underlying batch object, allowing for direct interaction with the batch if needed.
- Len: Returns the number of SQL statements currently queued in the batch.
- Queue: Adds a SQL statement to the batch with the provided query and arguments.
Example Usage:
var batch dbx.Batch = NewEmptyBatch()
batch.Queue("INSERT INTO users (name, email) VALUES ($1, $2)", "John Doe", "john@example.com")
batch.Queue("UPDATE users SET last_login = now() WHERE id = $1", userID)
rowsAffected, err := ExecuteBatch(ctx, batch)
if err != nil {
log.Fatal("Failed to execute batch:", err)
}
log.Printf("Batch executed successfully, rows affected: %d", rowsAffected)
type ConnConfig ¶
type ConnConfig struct {
VpcDirectConnection bool
Host string
Port int32
DBName string
User string
Password string
MaxConn int32
IsLocalEnv bool
}
ConnConfig represents the configuration required for database connection.
type DbShard ¶
type DbShard string
DbShard represents the shard instance key.
It represents a specific shard of the database and the DbShard type is used as a key to uniquely identify and manage these shards.
type InstanceManager ¶
type InstanceManager interface {
GetDbConnPool() (any, error)
GetConnFromPool(ctx context.Context) (any, error)
CloseDbConnPool()
GetConnectionConfig() ConnConfig
TxBegin(ctx context.Context) (Transaction, error)
Query(ctx context.Context, distLockId int64, query string, args ...interface{}) (conn any, rows any, err error)
Exec(ctx context.Context, distLockId int64, execQuery string, args ...any) (int64, error)
}
InstanceManager defines a contract for managing database connections and executing queries within a database instance.
This interface abstracts the operations related to managing a database connection pool, initiating transactions, and executing SQL queries. It provides an API for interacting with a database instance, regardless of the specific database implementation being used.
Responsibilities of InstanceManager include:
- Managing the lifecycle of the database connection pool, including acquiring and releasing connections.
- Initiating transactions and returning a Transaction interface for executing queries within that transaction context.
- Executing SQL queries and commands directly, outside of a transaction context, with support for handling distributed locks if needed.
- Providing access to the connection configuration.
The methods within this interface are designed to be flexible and allow for different database drivers or implementations to be used under a common API, making it easier to switch or extend database functionality without altering application logic.
Example Implementation:
A concrete implementation of InstanceManager might use a specific database driver like pgx for PostgreSQL, managing connections, transactions, and queries in a PostgreSQL-compatible manner while adhering to the interface contract.
type MasterReplicaManager ¶
type MasterReplicaManager struct {
DbMaster InstanceManager
DbReplica InstanceManager
}
MasterReplicaManager manages master and read replica instances.
The MasterReplicaManager is responsible for managing the master database instance and its read replicas for a particular shard. It provides a structure for routing read and write operations to the appropriate database instances based on the operation type.
Fields:
- DbMaster: An InstanceManager responsible for managing the master database instance, which handles all write operations.
- DbReplica: An InstanceManager responsible for managing the read replica database instance, which handles read operations.
type PreparedStatement ¶
PreparedStatement represents a prepared statement query.
A PreparedStatement encapsulates a SQL query that can be prepared and executed multiple times with different arguments. Are typically used to improve performance by reducing the overhead of parsing and planning the SQL query each time it is executed.
Fields:
- Name: A unique name identifying the prepared statement. This name is used to reference the statement when executing it.
- Query: The SQL query string associated with the prepared statement. The query can include placeholders for arguments.
func NewPreparedStatement ¶
func NewPreparedStatement(name, query string) PreparedStatement
NewPreparedStatement creates a new prepared statement.
This function is a constructor for the PreparedStatement struct. It takes a name and a query string as arguments and returns a new PreparedStatement instance. This is useful for creating and registering prepared statements before they are executed.
Arguments:
- name: The name of the prepared statement.
- query: The SQL query string for the prepared statement.
Returns:
- PreparedStatement: A new instance of the PreparedStatement struct.
func (PreparedStatement) GetName ¶
func (p PreparedStatement) GetName() string
GetName returns the name of the prepared statement.
This method returns the unique name associated with the prepared statement. The name is typically used to reference the prepared statement when executing it in the context of a database operation.
Returns:
- string: The name of the prepared statement.
func (PreparedStatement) GetQuery ¶
func (p PreparedStatement) GetQuery() string
GetQuery returns the query of the prepared statement.
This method returns the SQL query string associated with the prepared statement. The query can include placeholders for arguments that will be provided at execution time.
Returns:
- string: The SQL query string of the prepared statement.
type PreparedStatementsMap ¶
type PreparedStatementsMap struct {
DbPrepStmMap map[DbShard][]PreparedStatement
}
PreparedStatementsMap represents a map of DbShard and their respective prepared statements.
This struct is used to associate multiple prepared statements with different database shards. It allows for the organization and management of prepared statements across various database shards, which is particularly useful in sharded database architectures.
Fields:
- DbPrepStmMap: A map where the key is a DbShard and the value is a slice of PreparedStatements associated with that shard.
type RowConvertibleEntity ¶
type RowConvertibleEntity interface {
ToRow() []interface{} // Converts the struct to a row of values.
}
RowConvertibleEntity defines an interface for converting a struct into a row of values for database insertion.
This interface is intended for structs that need to be bulk-inserted into a database. Each struct implementing this interface must provide the `ToRow()` method, which converts the struct into a slice of values (`[]interface{}`) that can be used for bulk operations like `pgx.CopyFrom`.
The values returned by `ToRow()` should correspond to the struct's fields in the order they map to the database columns. Struct fields marked with a `db` tag (or other relevant tags) should be included in the returned slice, while fields with `db:"-"` or without a tag should be omitted.
Example:
type MyStruct struct {
ID int `db:"id"`
Name string `db:"name"`
Age int `db:"age"`
}
func (m MyStruct) ToRow() []interface{} {
return []interface{}{m.ID, m.Name, m.Age}
}
Usage of this interface allows for efficient bulk inserts by converting structs into row data that aligns with PostgreSQL's `pgx.CopyFrom` or other similar methods for inserting rows in bulk.
type ShardManager ¶
type ShardManager struct {
DbShardMap map[DbShard]MasterReplicaManager
}
ShardManager manages a pool of database shards, keeping them in a map.
The ShardManager is responsible for organizing and managing multiple database shards. Each shard is associated with a MasterReplicaManager, which manages the master and replica instances for that shard. This allows the ShardManager to efficiently route database operations to the appropriate shard and instance.
Fields:
- DbShardMap: A map where the key is a DbShard, and the value is a MasterReplicaManager responsible for managing the master and replica instances of that shard.
func NewDbShardManager ¶
func NewDbShardManager() *ShardManager
NewDbShardManager is a constructor that ensures the inner map is always initialized.
This function creates a new ShardManager instance with an initialized map. This ensures that the ShardManager is ready to manage shards immediately upon creation, avoiding potential nil pointer errors when adding shards.
Returns:
- *ShardManager: A new instance of the ShardManager struct.
func (*ShardManager) AddInstanceManager ¶
func (dsm *ShardManager) AddInstanceManager(dbShard DbShard, manager MasterReplicaManager)
AddInstanceManager adds a new MasterReplicaManager to the given DbShard.
This method adds a MasterReplicaManager to the ShardManager's internal map, associating it with a specific DbShard. If the map is uninitialized (which should not happen if the ShardManager is created using NewDbShardManager), it initializes the map before adding the entry.
Arguments:
- dbShard: The DbShard key to which the MasterReplicaManager will be associated.
- manager: The MasterReplicaManager that manages the master and replica instances for the shard.
Example Usage:
shardManager := NewDbShardManager()
shardManager.AddInstanceManager("shard1", masterReplicaManager)
type Transaction ¶
type Transaction interface {
GetTx() any
TxCommit(ctx context.Context) error
TxRollback(ctx context.Context)
TxQuery(ctx context.Context, query string, args ...interface{}) (any, error)
TxExec(ctx context.Context, query string, args ...any) (int64, error)
}
Transaction defines the interface for managing database transactions.
This interface abstracts the operations required to manage a database transaction, providing methods for committing, rolling back, and executing queries within the transaction context. It allows for consistent transaction management across different database implementations, ensuring that operations can be performed atomically and reliably.
Responsibilities of the Transaction interface include:
- Providing access to the underlying transaction object, allowing for direct interaction if necessary.
- Committing the transaction to persist all changes made within the transaction.
- Rolling back the transaction to discard all changes made within the transaction.
- Executing SQL queries and commands within the transaction context, ensuring that they are part of the atomic operation.
The methods in this interface are designed to be flexible and support different database drivers or implementations, allowing for consistent transaction management across various database systems.
Example Implementation:
A concrete implementation of Transaction might use a specific database driver like pgx for PostgreSQL, managing transaction operations in a PostgreSQL-compatible manner while adhering to the interface contract.
Source Files
Directories