sqlmw provides an absurdly simple API that allows a caller to wrap a database/sql driver
with middleware.
This provides an abstraction similar to http middleware or GRPC interceptors but for the database/sql package. This allows a caller to implement observability like tracing and logging easily. More importantly, it also enables powerful possible behaviors like transparently modifying arguments, results or query execution strategy. This power allows programmers to implement functionality like automatic sharding, selective tracing, automatic caching, transparent query mirroring, retries, fail-over in a reuseable way, and more.
- Define a new type and embed the
sqlmw.NullInterceptortype. - Add a method you want to intercept from the
sqlmw.Interceptorinterface. - Wrap the driver with your interceptor with
sqlmw.Driverand then install it withsql.Register. - Use
sql.Openon the new driver string that was passed to register.
Here's a complete example:
func run(dsn string) {
// install the wrapped driver
sql.Register("postgres-mw", sqlmw.Driver(pq.Driver{}, new(sqlInterceptor)))
db, err := sql.Open("postgres-mw", dsn)
...
}
type sqlInterceptor struct {
sqlmw.NullInterceptor
}
func (in *sqlInterceptor) StmtQueryContext(ctx context.Context, conn driver.StmtQueryContext, query string, args []driver.NamedValue) (driver.Rows, error) {
startedAt := time.Now()
rows, err := conn.QueryContext(ctx, args)
log.Debug("executed sql query", "duration", time.Since(startedAt), "query", query, "args", args, "err", err)
return rows, err
}You may override any subset of methods to intercept in the Interceptor interface (https://godoc.org/github.com/ngrok/sqlmw#Interceptor):
type Interceptor interface {
// Connection interceptors
ConnBeginTx(context.Context, driver.ConnBeginTx, driver.TxOptions) (driver.Tx, error)
ConnPrepareContext(context.Context, driver.ConnPrepareContext, string) (driver.Stmt, error)
ConnPing(context.Context, driver.Pinger) error
ConnExecContext(context.Context, driver.ExecerContext, string, []driver.NamedValue) (driver.Result, error)
ConnQueryContext(context.Context, driver.QueryerContext, string, []driver.NamedValue) (driver.Rows, error)
// Connector interceptors
ConnectorConnect(context.Context, driver.Connector) (driver.Conn, error)
// Results interceptors
ResultLastInsertId(driver.Result) (int64, error)
ResultRowsAffected(driver.Result) (int64, error)
// Rows interceptors
RowsNext(context.Context, driver.Rows, []driver.Value) error
// Stmt interceptors
StmtExecContext(context.Context, driver.StmtExecContext, string, []driver.NamedValue) (driver.Result, error)
StmtQueryContext(context.Context, driver.StmtQueryContext, string, []driver.NamedValue) (driver.Rows, error)
StmtClose(context.Context, driver.Stmt) error
// Tx interceptors
TxCommit(context.Context, driver.Tx) error
TxRollback(context.Context, driver.Tx) error
}Bear in mind that because you are intercepting the calls entirely, that you are responsible for passing control up to the wrapped driver in any function that you override, like so:
func (in *sqlInterceptor) ConnPing(ctx context.Context, conn driver.Pinger) error {
return conn.Ping(ctx)
}func (in *sqlInterceptor) StmtQueryContext(ctx context.Context, conn driver.StmtQueryContext, query string, args []driver.NamedValue) (driver.Rows, error) {
startedAt := time.Now()
rows, err := conn.QueryContext(ctx, args)
log.Debug("executed sql query", "duration", time.Since(startedAt), "query", query, "args", args, "err", err)
return rows, err
}