SQL Module

SQL module based on database/sql.

• Installation
• Documentation
  • Usage
  • Hooks
    • Log hook
    • Trace hook
    • Custom hook
  • Healthcheck

Installation

go get github.com/ankorstore/yokai/sql

Documentation

This module provides a Driver, decorating database/sql compatible drivers, with a hooking mechanism.

Usage

The following database systems are supported:

• mysql with go-sql-driver/mysql
• postgres with lib/pq
• sqlite with mattn/go-sqlite3

To create a *sql.DB with the tracing and logging hooks:

package main

import (
	"database/sql"
	
	yokaisql "github.com/ankorstore/yokai/sql"
	"github.com/ankorstore/yokai/sql/hook/log"
	"github.com/ankorstore/yokai/sql/hook/trace"
)

func main() {
	// MySQL
	driver, _ := yokaisql.Register("mysql", trace.NewTraceHook(), log.NewLogHook())
	db, _ := sql.Open(driver, "user:password@tcp(localhost:3306)/db?parseTime=true")

	// Postgres
	driver, _ := yokaisql.Register("postgres", trace.NewTraceHook(), log.NewLogHook())
	db, _ := sql.Open(driver, "host=host port=5432 user=user password=password dbname=db sslmode=disable")

	// SQLite
	driver, _ := yokaisql.Register("sqlite", trace.NewTraceHook(), log.NewLogHook())
	db, _ := sql.Open(driver, ":memory:")
}

See database/sql documentation for more details.

Hooks

This module provides a hooking mechanism to add logic around the SQL operations.

Log hook

This module provides an LogHook, that you can use to automatically log the SQL operations:

package main

import (
	"database/sql"

	yokaisql "github.com/ankorstore/yokai/sql"
	"github.com/ankorstore/yokai/sql/hook/log"
	"github.com/rs/zerolog"
)

func main() {

	logHook := log.NewLogHook(
		log.WithLevel(zerolog.DebugLevel),        // SQL logs level, debug by default
		log.WithArguments(true),                  // SQL logs with SQL arguments, false by default
		log.WithExcludedOperations(               // SQL operations to exclude from logging, empty by default
			yokaisql.ConnectionPingOperation,
			yokaisql.ConnectionResetSessionOperation,
		),
	)

	driver, _ := yokaisql.Register("sqlite", logHook)
	db, _ := sql.Open(driver, ":memory:")
}

Trace hook

This module provides an TraceHook, that you can use to automatically trace the SQL operations:

package main

import (
	"database/sql"

	yokaisql "github.com/ankorstore/yokai/sql"
	"github.com/ankorstore/yokai/sql/hook/log"
	"github.com/ankorstore/yokai/sql/hook/trace"
	"github.com/rs/zerolog"
)

func main() {

	traceHook := trace.NewTraceHook(
		trace.WithArguments(true),                  // SQL traces with SQL arguments, false by default
		trace.WithExcludedOperations(               // SQL operations to exclude from tracing, empty by default
			yokaisql.ConnectionPingOperation,
			yokaisql.ConnectionResetSessionOperation,
		),
	)

	driver, _ := yokaisql.Register("sqlite", traceHook)
	db, _ := sql.Open(driver, ":memory:")
}

Custom hook

This module provides a Hook interface, that you can implement to extend the logic around SQL operations:

package main

import (
	"context"
	"database/sql"

	yokaisql "github.com/ankorstore/yokai/sql"
	"github.com/ankorstore/yokai/sql/hook/log"
	"github.com/ankorstore/yokai/sql/hook/trace"
	"github.com/rs/zerolog"
)

type CustomHook struct{}

func (h *CustomHook) Before(ctx context.Context, event *yokaisql.HookEvent) context.Context {
	// your custom logic before SQL operation
	
	return ctx
}

func (h *CustomHook) After(ctx context.Context, event *yokaisql.HookEvent) {
	// your custom logic after SQL operation
}

func main() {
	driver, _ := yokaisql.Register("sqlite", &CustomHook{})
	db, _ := sql.Open(driver, ":memory:")
}

Healthcheck

This module provides an SQLProbe, compatible with the healthcheck module:

package main

import (
	"context"

	yokaihc "github.com/ankorstore/yokai/healthcheck"
	yokaisql "github.com/ankorstore/yokai/sql"
	"github.com/ankorstore/yokai/sql/healthcheck"
)

func main() {
	driver, _ := yokaisql.Register("sqlite")
	db, _ := sql.Open(driver, ":memory:")

	checker, _ := yokaihc.NewDefaultCheckerFactory().Create(
		yokaihc.WithProbe(healthcheck.NewSQLProbe(db)),
	)

	checker.Check(context.Background(), yokaihc.Readiness)
}

This probe performs a ping to the configured database connection.