README
¶
go-db
A tiny module for lazy me, to connect database.
This module uses a predefined set of environment variables to connect databases using database/sql.
Usage
Just call Connect() or ConnectX() to establish database connections.
import (
"database/sql"
"os"
"github.com/eidng8/go-db"
"<your-package>/ent"
)
func getEntClient() *ent.Client {
return ent.NewClient(ent.Driver(entsql.OpenDB(db.ConnectX())))
}
Environment Variables
DB_DRIVER
REQUIRED and cannot be empty. Determines what kind of database to connect. Can be any driver supported by database/sql, such as mysql, sqlite3, pgx, etc. Remember to import proper driver module to your package.
DB_DSN
REQUIRED for connections other than MySQL. A complete DSN string to be used to establish connection to database. When set, this variable is passed directly to sql.Open(). For MySQL, if this variable is not set, variables below will be used to configure the connection.
Variables specific to MySQL
These variables are used to configure the connection to MySQL, if DB_DSN is not set.
REQUIRED and cannot be empty. Determines the username to connect to database.
REQUIRED and cannot be empty. Determines the password to connect to database.
REQUIRED and cannot be empty. Determines the host to connect to.
REQUIRED and cannot be empty. Determines the database name to connect to.
OPTIONAL and defaults to tcp.
OPTIONAL and defaults to utf8mb4_unicode_ci.
OPTIONAL and defaults to UTC.
When using Connect() or ConnectX() with environment variables, some configurations are also set:
mysql.Config{
// .....
AllowCleartextPasswords: false,
AllowFallbackToPlaintext: false,
AllowNativePasswords: true,
AllowOldPasswords: false,
MultiStatements: true,
ParseTime: true,
// .....
}
Besides using Connect() or ConnectX(), ConnectMysql() can also be called with mysql.Config pointer:
cfg := mysql.Config{
// You detailed configuration .....
}
ConnectMysql(cfg)
No matter which function is used to establish the connection, the following 3 settings are also called:
db.SetMaxIdleConns(10)
db.SetMaxOpenConns(100)
db.SetConnMaxLifetime(time.Hour)
Documentation
¶
Index ¶
- func Connect() (string, *sql.DB, error)
- func ConnectMysql(cfg *mysql.Config) (*sql.DB, error)
- func ConnectMysqlWithOptions(cfg *mysql.Config, opts MysqlOptions) (*sql.DB, error)
- func ConnectX() (string, *sql.DB)
- func Transaction[T any](db *sql.DB, fn func(*sql.Tx) (T, error)) (T, error)
- type CachedWriter
- type DelegateCachedWriter
- type LoggedWriter
- type MemCachedWriter
- func (w *MemCachedWriter) Pause()
- func (w *MemCachedWriter) Push(data any)
- func (w *MemCachedWriter) Resume()
- func (w *MemCachedWriter) SetDB(db *sql.DB)
- func (w *MemCachedWriter) SetFailedLog(log io.Writer)
- func (w *MemCachedWriter) SetInterval(duration time.Duration)
- func (w *MemCachedWriter) SetLogger(log utils.TaggedLogger)
- func (w *MemCachedWriter) SetQueryBuilder(fn func([]any) (string, []any))
- func (w *MemCachedWriter) SetRetries(numRetries int)
- func (w *MemCachedWriter) Start(stopChan <-chan struct{})
- func (w *MemCachedWriter) Write()
- type MysqlOptions
- type SplitLoggedWriter
- type SqlBuilderFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Connect ¶
Connect to the database using predefined environment variables. Returns the driver name, the database connection, and an error if any.
func ConnectMysql ¶
ConnectMysql to the MySQL database using the given configuration `cfg`. If nil is passed, it reads configuration from predefined environment variables.
func ConnectMysqlWithOptions ¶
ConnectMysqlWithOptions to the MySQL database using predefined environment variables and options.
Types ¶
type CachedWriter ¶ added in v0.0.5
type CachedWriter interface {
// Push adds a record to the cache
Push(any)
// Write sends all cached data to the DB in a multi-value insert
Write()
// Start begins the writer and run until the given channel is signaled.
// The writer will attempt to write data to the DB at the interval set by
// SetInterval.
Start(<-chan struct{})
// Pause temporarily stops the writer from writing to the DB. Data can still
// be added to the cache while the writer is paused.
Pause()
// Resume restarts the writer after a pause.
Resume()
// SetDB sets the database connection for the writer.
SetDB(*sql.DB)
// SetRetries sets the number of times the writer will attempt to write data
// to the DB before giving up. Defaults to 3.
SetRetries(int)
// SetInterval sets the interval (second) at which the writer will attempt
// to write data to the DB. Defaults to 1 second.
SetInterval(time.Duration)
}
CachedWriter is an interface for writing data to a database in a batched manner. This allows for better performance when writing a large number of records to the database, or write operation is too frequent.
type DelegateCachedWriter ¶ added in v0.0.5
type DelegateCachedWriter interface {
// SetQueryBuilder sets the function that will be used to build the query
// and arguments for writing data to the DB.
SetQueryBuilder(func([]any) (string, []any))
}
DelegateCachedWriter is an interface for a CachedWriter that allows the user to set the query builder function that will be used to build the query and arguments for writing data to the DB.
type LoggedWriter ¶ added in v0.0.5
type LoggedWriter interface {
// SetLogger sets the log to write console logs.
SetLogger(log utils.TaggedLogger)
}
LoggedWriter is an interface for a CachedWriter that allows the user to set the log to write console logs.
type MemCachedWriter ¶ added in v0.0.5
type MemCachedWriter struct {
// contains filtered or unexported fields
}
MemCachedWriter is a DelegateCachedWriter and SplitLoggedWriter that writes string data to a database in a batched manner. It uses a query builder function to build the query and arguments for writing data to the DB.
func NewMemCachedWriter ¶ added in v0.0.5
func NewMemCachedWriter( db *sql.DB, sqlBuilder SqlBuilderFunc, logger utils.TaggedLogger, ) *MemCachedWriter
NewMemCachedWriter creates a new MemCachedWriter with the given database connection and query builder function. It sets the default values of retries to 3, and interval to 1.
func (*MemCachedWriter) Pause ¶ added in v0.0.5
func (w *MemCachedWriter) Pause()
Pause temporarily stops the writer from writing to the DB. Data can still be added to the cache while the writer is paused.
func (*MemCachedWriter) Push ¶ added in v0.0.5
func (w *MemCachedWriter) Push(data any)
Push adds a record to the cache
func (*MemCachedWriter) Resume ¶ added in v0.0.5
func (w *MemCachedWriter) Resume()
Resume restarts the writer after a pause.
func (*MemCachedWriter) SetDB ¶ added in v0.0.5
func (w *MemCachedWriter) SetDB(db *sql.DB)
SetDB sets the database connection for the writer.
func (*MemCachedWriter) SetFailedLog ¶ added in v0.0.5
func (w *MemCachedWriter) SetFailedLog(log io.Writer)
SetFailedLog sets the log to write records with db failure.
func (*MemCachedWriter) SetInterval ¶ added in v0.0.5
func (w *MemCachedWriter) SetInterval(duration time.Duration)
SetInterval sets the interval (second) at which the writer will attempt to write data to the DB. Defaults to 1 second.
func (*MemCachedWriter) SetLogger ¶ added in v0.0.5
func (w *MemCachedWriter) SetLogger(log utils.TaggedLogger)
SetLogger sets the log to write console logs.
func (*MemCachedWriter) SetQueryBuilder ¶ added in v0.0.5
func (w *MemCachedWriter) SetQueryBuilder( fn func([]any) (string, []any), )
SetQueryBuilder sets the function that will be used to build the query and arguments for writing data to the DB.
func (*MemCachedWriter) SetRetries ¶ added in v0.0.5
func (w *MemCachedWriter) SetRetries(numRetries int)
SetRetries sets the number of times the writer will attempt to write data to the DB before giving up. Defaults to 3.
func (*MemCachedWriter) Start ¶ added in v0.0.5
func (w *MemCachedWriter) Start(stopChan <-chan struct{})
Start begins the writer and run until the given channel is signaled. The writer will attempt to write data to the DB at the interval set by SetInterval.
func (*MemCachedWriter) Write ¶ added in v0.0.5
func (w *MemCachedWriter) Write()
Write sends all cached data to the DB in a multi-value insert
type MysqlOptions ¶
MysqlOptions for the MySQL database connection.
type SplitLoggedWriter ¶ added in v0.0.6
type SplitLoggedWriter interface {
LoggedWriter
// SetFailedLog sets the log to write records with db failure.
SetFailedLog(log io.Writer)
}
SplitLoggedWriter is an interface for a CachedWriter that allows the user to use separate logs for writing console and db logs.
Source Files