README.md
1# sqlhooks [![Build Status](https://travis-ci.org/gchaincl/sqlhooks.svg)](https://travis-ci.org/gchaincl/sqlhooks) [![Coverage Status](https://coveralls.io/repos/github/gchaincl/sqlhooks/badge.svg?branch=master)](https://coveralls.io/github/gchaincl/sqlhooks?branch=master) [![Go Report Card](https://goreportcard.com/badge/github.com/gchaincl/sqlhooks)](https://goreportcard.com/report/github.com/gchaincl/sqlhooks)
2
3Attach hooks to any database/sql driver.
4
5The purpose of sqlhooks is to provide a way to instrument your sql statements, making really easy to log queries or measure execution time without modifying your actual code.
6
7# Install
8```bash
9go get github.com/gchaincl/sqlhooks
10```
11Requires Go >= 1.8.x
12
13## Breaking changes
14`V1` isn't backward compatible with previous versions, if you want to fetch old versions, you can get them from [gopkg.in](http://gopkg.in/)
15```bash
16go get gopkg.in/gchaincl/sqlhooks.v0
17```
18
19# Usage [![GoDoc](https://godoc.org/github.com/gchaincl/dotsql?status.svg)](https://godoc.org/github.com/gchaincl/sqlhooks)
20
21```go
22// This example shows how to instrument sql queries in order to display the time that they consume
23package main
24
25import (
26 "context"
27 "database/sql"
28 "fmt"
29 "time"
30
31 "github.com/gchaincl/sqlhooks"
32 "github.com/mattn/go-sqlite3"
33)
34
35// Hooks satisfies the sqlhook.Hooks interface
36type Hooks struct {}
37
38// Before hook will print the query with it's args and return the context with the timestamp
39func (h *Hooks) Before(ctx context.Context, query string, args ...interface{}) (context.Context, error) {
40 fmt.Printf("> %s %q", query, args)
41 return context.WithValue(ctx, "begin", time.Now()), nil
42}
43
44// After hook will get the timestamp registered on the Before hook and print the elapsed time
45func (h *Hooks) After(ctx context.Context, query string, args ...interface{}) (context.Context, error) {
46 begin := ctx.Value("begin").(time.Time)
47 fmt.Printf(". took: %s\n", time.Since(begin))
48 return ctx, nil
49}
50
51func main() {
52 // First, register the wrapper
53 sql.Register("sqlite3WithHooks", sqlhooks.Wrap(&sqlite3.SQLiteDriver{}, &Hooks{}))
54
55 // Connect to the registered wrapped driver
56 db, _ := sql.Open("sqlite3WithHooks", ":memory:")
57
58 // Do you're stuff
59 db.Exec("CREATE TABLE t (id INTEGER, text VARCHAR(16))")
60 db.Exec("INSERT into t (text) VALUES(?), (?)", "foo", "bar")
61 db.Query("SELECT id, text FROM t")
62}
63
64/*
65Output should look like:
66> CREATE TABLE t (id INTEGER, text VARCHAR(16)) []. took: 121.238µs
67> INSERT into t (text) VALUES(?), (?) ["foo" "bar"]. took: 36.364µs
68> SELECT id, text FROM t []. took: 4.653µs
69*/
70```
71
72# Benchmarks
73```
74 go test -bench=. -benchmem
75 BenchmarkSQLite3/Without_Hooks-4 200000 8572 ns/op 627 B/op 16 allocs/op
76 BenchmarkSQLite3/With_Hooks-4 200000 10231 ns/op 738 B/op 18 allocs/op
77 BenchmarkMySQL/Without_Hooks-4 10000 108421 ns/op 437 B/op 10 allocs/op
78 BenchmarkMySQL/With_Hooks-4 10000 226085 ns/op 597 B/op 13 allocs/op
79 BenchmarkPostgres/Without_Hooks-4 10000 125718 ns/op 649 B/op 17 allocs/op
80 BenchmarkPostgres/With_Hooks-4 5000 354831 ns/op 1122 B/op 27 allocs/op
81 PASS
82 ok github.com/gchaincl/sqlhooks 11.713s
83 ```
84