open source

Author: prashanthpai

.gitignore

@@ -0,0 +1,20 @@
+# ignore vendor directory
+vendor/
+
+# ignore patches
+*.patch
+
+# ctags
+tags
+
+# vim/vi
+*.swp
+*.swo
+*~
+
+# Files generated by JetBrains IDEs, e.g. IntelliJ IDEA
+.idea/
+*.iml
+
+# Binary
+example/example

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Prashanth Pai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,86 @@
+# sqlcache
+
+[![Go.Dev reference](https://img.shields.io/badge/go.dev-reference-blue?logo=go&logoColor=white)](https://pkg.go.dev/prashanthpai/sqlcache?tab=doc)
+[![Go Report Card](https://goreportcard.com/badge/github.com/prashanthpai/sqlcache)](https://goreportcard.com/report/github.com/prashanthpai/sqlcache)
+[![MIT license](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)
+
+sqlcache is an **experimental** caching middleware for `database/sql`. It
+leverages APIs provided by the handy [sqlmw](https://github.com/ngrok/sqlmw)
+project and is inspired from [slonik-interceptor-query-cache](https://github.com/gajus/slonik-interceptor-query-cache).
+This liberates your Go program from maintaining imperative code that
+implements the cache-aside pattern. Your program will perceive the
+database client/driver as a read-through cache.
+
+Tested with PostgreSQL database with [pgx](https://github.com/jackc/pgx/tree/master/stdlib) as the driver.
+
+Cache backends supported:
+
+* [ristretto](https://github.com/dgraph-io/ristretto) (in-memory)
+* [redis](https://github.com/go-redis/redis)
+
+It's easy to add other caching backends by implementing the `cache.Cacher`
+interface.
+
+## Usage
+
+Create a backend cache instance and install the interceptor:
+
+```go
+import (
+	"database/sql"
+
+	redis "github.com/go-redis/redis/v7"
+	"github.com/ngrok/sqlmw"
+	"github.com/prashanthpai/sqlcache"
+)
+
+func main() {
+	...
+	rc := redis.NewUniversalClient(&redis.UniversalOptions{
+		Addrs: []string{"127.0.0.1:6379"},
+	})
+
+	// create a sqlcache.Interceptor instance with the desired backend
+	interceptor, err := sqlcache.NewInterceptor(&sqlcache.Config{
+		Cache: sqlcache.NewRedis(rc, "sqc"),
+	})
+	...
+
+	// wrap pgx driver with the interceptor and register it
+	sql.Register("pgx-with-cache", sqlmw.Driver(stdlib.GetDefaultDriver(), interceptor))
+
+	// open the database using the wrapped driver
+	db, err := sql.Open("pgx-with-cache", dsn)
+	...
+```
+
+Caching is controlled using cache attributes which are SQL comments starting
+with `@cache-` prefix. Only queries with cache attributes are cached.
+
+**Cache attributes:**
+
+|Cache attribute|Description|Required?|Default|
+|---|---|---|---|
+|`@cache-ttl`|Number (in seconds) to cache the query for.|Yes|N/A|
+|`@cache-max-rows`|Don't cache if number of rows in query response exceeds this limit.|Yes|N/A|
+
+Example query:
+
+```go
+rows, err := db.QueryContext(context.TODO(), `
+	-- @cache-ttl 30
+	-- @cache-max-rows 10
+	SELECT name, pages FROM books WHERE pages > $1`, 100)
+```
+
+See [example/main.go](example/main.go) for a full working example.
+
+## TODO
+
+* Test against different postgres data types.
+* Check if deep copy of buffers can be removed.
+
+### References
+
+* A declarative way to cache PostgreSQL queries using Node.js: a [blog post](https://dev.to/gajus/a-declarative-way-to-cache-postgresql-queries-using-node-js-4fbo) by the author of [Slonik](https://github.com/gajus/slonik).
+* Declarative Caching with Postgres and Redis: Kyle Davis's [talk](https://youtu.be/IID2LQVztIM?t=1170) on Slonik + Redis.

attr.go

@@ -0,0 +1,39 @@
+package sqlcache
+
+import (
+	"regexp"
+	"strconv"
+)
+
+var (
+	attrRegexp = regexp.MustCompile(`(@cache-ttl|@cache-max-rows) (\d+)`)
+)
+
+type attributes struct {
+	ttl     int
+	maxRows int
+}
+
+func getAttrs(query string) *attributes {
+	matches := attrRegexp.FindAllStringSubmatch(query, 2)
+	if len(matches) != 2 {
+		return nil
+	}
+
+	var attrs attributes
+	for _, match := range matches {
+		if len(match) != 3 {
+			return nil
+		}
+		switch match[1] {
+		case "@cache-ttl":
+			ttl, _ := strconv.Atoi(match[2])
+			attrs.ttl = ttl
+		case "@cache-max-rows":
+			maxRows, _ := strconv.Atoi(match[2])
+			attrs.maxRows = maxRows
+		}
+	}
+
+	return &attrs
+}

cache/cache.go

@@ -0,0 +1,23 @@
+package cache
+
+import (
+	"database/sql/driver"
+	"time"
+)
+
+// Item represents a single item in cache and will contain the results of a
+// single SQL query.
+type Item struct {
+	Cols []string
+	Rows [][]driver.Value
+}
+
+// Cacher represents a backend cache that can be used by sqlcache package.
+type Cacher interface {
+	// Get must return a pointer to the item, a boolean representing whether
+	// item is present or not, and an error (must be nil when key is not
+	// present).
+	Get(key string) (*Item, bool, error)
+	// Set sets the item into cache with the given TTL.
+	Set(key string, item *Item, ttl time.Duration) error
+}

cache_redis.go

@@ -0,0 +1,55 @@
+package sqlcache
+
+import (
+	"time"
+
+	"github.com/prashanthpai/sqlcache/cache"
+
+	redis "github.com/go-redis/redis/v7"
+	msgpack "github.com/vmihailenco/msgpack/v4"
+)
+
+// Redis implements cache.Cacher interface to use redis as backend with
+// go-redis as the redis client library.
+type Redis struct {
+	c         redis.UniversalClient
+	keyPrefix string
+}
+
+// Get gets a cache item from redis. Returns pointer to the item, a boolean
+// which represents whether key exists or not and an error.
+func (r *Redis) Get(key string) (*cache.Item, bool, error) {
+	b, err := r.c.Get(r.keyPrefix + key).Bytes()
+	switch err {
+	case nil:
+		var item cache.Item
+		if err := msgpack.Unmarshal(b, &item); err != nil {
+			return nil, true, err
+		}
+		return &item, true, nil
+	case redis.Nil:
+		return nil, false, nil
+	default:
+		return nil, false, err
+	}
+}
+
+// Set sets the given item into redis with provided TTL duration.
+func (r *Redis) Set(key string, item *cache.Item, ttl time.Duration) error {
+	b, err := msgpack.Marshal(item)
+	if err != nil {
+		return err
+	}
+
+	_, err = r.c.Set(r.keyPrefix+key, b, ttl).Result()
+	return err
+}
+
+// NewRedis creates a new instance of redis backend using go-redis client.
+// All keys created in redis by sqlcache will have start with prefix.
+func NewRedis(c redis.UniversalClient, keyPrefix string) *Redis {
+	return &Redis{
+		c:         c,
+		keyPrefix: keyPrefix,
+	}
+}

cache_ristretto.go

@@ -0,0 +1,49 @@
+package sqlcache
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/prashanthpai/sqlcache/cache"
+
+	"github.com/dgraph-io/ristretto"
+)
+
+// Ristretto implements cache.Cacher interface to use ristretto as backend with
+// go-redis as the redis client library.
+type Ristretto struct {
+	c *ristretto.Cache
+}
+
+// Get gets a cache item from ristretto. Returns pointer to the item, a boolean
+// which represents whether key exists or not and an error.
+func (r *Ristretto) Get(key string) (*cache.Item, bool, error) {
+	i, ok := r.c.Get(key)
+	if !ok {
+		return nil, false, nil
+	}
+
+	item, ok := i.(*cache.Item)
+	if !ok {
+		return nil, false, fmt.Errorf("Ristretto.Get(): i.(*cache.Item) failed")
+	}
+
+	return item, ok, nil
+}
+
+// Set sets the given item into ristretto with provided TTL duration.
+func (r *Ristretto) Set(key string, item *cache.Item, ttl time.Duration) error {
+	// using # of rows as cost
+	_ = r.c.SetWithTTL(key, item, int64(len(item.Rows)), ttl)
+	return nil
+}
+
+// NewRistretto creates a new instance of ristretto backend wrapping the
+// provided *ristretto.Cache instance. While creating the ristretto
+// instance, please note that number of rows will be used as "cost"
+// (in ristretto's terminology) for each cache item.
+func NewRistretto(c *ristretto.Cache) *Ristretto {
+	return &Ristretto{
+		c: c,
+	}
+}

doc.go

@@ -0,0 +1,47 @@
+/*
+Package sqlcache provides an experimental caching middleware for database/sql
+users. This liberates your Go program from maintaining imperative code that
+implements the cache-aside pattern. Your program will perceive the database
+client/driver as a read-through cache.
+
+Usage:
+
+	import (
+		"database/sql"
+
+		redis "github.com/go-redis/redis/v7"
+		"github.com/prashanthpai/sqlcache"
+		"github.com/ngrok/sqlmw"
+	)
+
+	func main() {
+		...
+		rc := redis.NewUniversalClient(&redis.UniversalOptions{
+			Addrs: []string{"127.0.0.1:6379"},
+		})
+
+		// create a sqlcache.Interceptor instance with the desired backend
+		interceptor, err := sqlcache.NewInterceptor(&sqlcache.Config{
+			Cache: sqlcache.NewRedis(rc, "sqc"),
+		})
+		...
+
+		// wrap pgx driver with the interceptor and register it
+		sql.Register("pgx-with-cache", sqlmw.Driver(stdlib.GetDefaultDriver(), interceptor))
+
+		// open the database using the wrapped driver
+		db, err := sql.Open("pgx-with-cache", dsn)
+		...
+	}
+
+Caching is controlled using cache attributes which are SQL comments starting
+with `@cache-` prefix. Only queries with cache attributes are cached.
+
+Example query:
+
+	rows, err := db.QueryContext(context.TODO(), `
+		-- @cache-ttl 30
+		-- @cache-max-rows 10
+		SELECT name, pages FROM books WHERE pages > $1`, 100)
+*/
+package sqlcache