orm

README

ORM Module

ORM module based on GORM.

• Installation
• Documentation
  • Usage
  • Add-ons
    • Logger
    • Tracer
    • Healthcheck

Installation

go get github.com/ankorstore/yokai/orm

Documentation

Usage

This module provides a OrmFactory, allowing to build an gorm.DB instance.

The following database drivers are supported:

• SQLite
• MySQL
• PostgreSQL
• SQL Server

package main

import (
	"github.com/ankorstore/yokai/orm"
)

// with MySQL driver
var db, _ = orm.NewDefaultOrmFactory().Create(
	orm.WithDriver(orm.Mysql),
	orm.WithDsn("user:pass@tcp(127.0.0.1:3306)/dbname?parseTime=True"),
)

// or with SQLite driver
var db, _ = orm.NewDefaultOrmFactory().Create(
	orm.WithDriver(orm.Sqlite),
	orm.WithDsn("file::memory:?cache=shared"),
)

See GORM documentation for more details.

Add-ons

This module provides several add-ons ready to use to enrich your ORM.

Logger

This module provides an CtxOrmLogger, compatible with the log module:

package main

import (
	"github.com/ankorstore/yokai/orm"
	"gorm.io/gorm"
	"gorm.io/gorm/logger"
)

func main() {
	ormLogger := orm.NewCtxOrmLogger(logger.Info, false)

	db, _ := orm.NewDefaultOrmFactory().Create(
		orm.WithConfig(gorm.Config{
			Logger: ormLogger,
		}),
	)
}

If needed, you can set the parameter withValues to true to append SQL query parameter values in the log records:

ormLogger := orm.NewCtxOrmLogger(logger.Info, true)

Tracer

This module provides an OrmTracerPlugin, compatible with the trace module:

package main

import (
	"github.com/ankorstore/yokai/orm"
	"github.com/ankorstore/yokai/orm/plugin"
	"github.com/ankorstore/yokai/trace"
)

func main() {
	tracerProvider, _ := trace.NewDefaultTracerProviderFactory().Create()

	db, _ := orm.NewDefaultOrmFactory().Create()

	db.Use(plugin.NewOrmTracerPlugin(tracerProvider, false))
}

If needed, you can set the parameter withValues to true to append SQL query parameter values in the trace spans:

db.Use(plugin.NewOrmTracerPlugin(tracerProvider, true))

Healthcheck

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

package main

import (
	"context"

	hc "github.com/ankorstore/yokai/healthcheck"
	"github.com/ankorstore/yokai/orm"
	"github.com/ankorstore/yokai/orm/healthcheck"
)

func main() {
	db, _ := orm.NewDefaultOrmFactory().Create()

	checker, _ := hc.NewDefaultCheckerFactory().Create(
		hc.WithProbe(healthcheck.NewOrmProbe(db)),
	)

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

This probe performs a ping to the configured database connection.

Documentation

Index

• func FetchLogLevel(level string) logger.LogLevel
• type CtxOrmLogger
  • func NewCtxOrmLogger(level logger.LogLevel, withValues bool) *CtxOrmLogger
  • func (l *CtxOrmLogger) Error(ctx context.Context, msg string, opts ...interface{})
  • func (l *CtxOrmLogger) Info(ctx context.Context, msg string, opts ...interface{})
  • func (l *CtxOrmLogger) LogMode(level logger.LogLevel) logger.Interface
  • func (l *CtxOrmLogger) ParamsFilter(ctx context.Context, sql string, params ...interface{}) (string, []interface{})
  • func (l *CtxOrmLogger) Trace(ctx context.Context, begin time.Time, f func() (string, int64), err error)
  • func (l *CtxOrmLogger) Warn(ctx context.Context, msg string, opts ...interface{})
• type DefaultOrmFactory
  • func (f *DefaultOrmFactory) Create(options ...OrmOption) (*gorm.DB, error)
• type Driver
  • func FetchDriver(driver string) Driver
  • func (d Driver) String() string
• type Options
  • func DefaultOrmOptions() Options
• type OrmFactory
  • func NewDefaultOrmFactory() OrmFactory
• type OrmOption
  • func WithConfig(c gorm.Config) OrmOption
  • func WithDriver(d Driver) OrmOption
  • func WithDsn(d string) OrmOption

Functions

func FetchLogLevel

func FetchLogLevel(level string) logger.LogLevel

FetchLogLevel returns a logger.LogLevel for a given value.

Types

type CtxOrmLogger

type CtxOrmLogger struct {
	// contains filtered or unexported fields
}

CtxOrmLogger is a logger compatible with the Gorm logger.

func NewCtxOrmLogger

func NewCtxOrmLogger(level logger.LogLevel, withValues bool) *CtxOrmLogger

NewCtxOrmLogger returns a new CtxOrmLogger.

func (*CtxOrmLogger) Error

func (l *CtxOrmLogger) Error(ctx context.Context, msg string, opts ...interface{})

Error logs with error level.

func (*CtxOrmLogger) Info

func (l *CtxOrmLogger) Info(ctx context.Context, msg string, opts ...interface{})

Info logs with info level.

func (*CtxOrmLogger) LogMode

func (l *CtxOrmLogger) LogMode(level logger.LogLevel) logger.Interface

LogMode sets the logger log level.

func (*CtxOrmLogger) ParamsFilter

func (l *CtxOrmLogger) ParamsFilter(ctx context.Context, sql string, params ...interface{}) (string, []interface{})

ParamsFilter is used to filter SQL queries params from logging (replace with ?).

func (*CtxOrmLogger) Trace

func (l *CtxOrmLogger) Trace(ctx context.Context, begin time.Time, f func() (string, int64), err error)

Trace logs with trace level.

func (*CtxOrmLogger) Warn

func (l *CtxOrmLogger) Warn(ctx context.Context, msg string, opts ...interface{})

Warn logs with warn level.

type DefaultOrmFactory

type DefaultOrmFactory struct{}

DefaultOrmFactory is the default OrmFactory implementation.

func (*DefaultOrmFactory) Create

func (f *DefaultOrmFactory) Create(options ...OrmOption) (*gorm.DB, error)

Create returns a new gorm.DB, and accepts a list of OrmOption. For example with MySQL driver:

var db, _ = orm.NewDefaultOrmFactory().Create(
	orm.WithDriver(orm.Mysql),
	orm.WithDsn("user:pass@tcp(127.0.0.1:3306)/dbname?parseTime=True"),
)

or with SQLite driver:

var db, _ = orm.NewDefaultOrmFactory().Create(
	orm.WithDriver(orm.Sqlite),
	orm.WithDsn("file::memory:?cache=shared"),
)

type Driver

type Driver int

Driver is an enum for the supported database drivers.

const (
	Unknown Driver = iota
	Sqlite
	Mysql
	Postgres
	SqlServer
)

func FetchDriver

func FetchDriver(driver string) Driver

FetchDriver returns a Driver for a given value.

func (Driver) String

func (d Driver) String() string

String returns a string representation of the Driver.

type Options

type Options struct {
	Dsn    string
	Driver Driver
	Config gorm.Config
}

Options are options for the OrmFactory implementations.

func DefaultOrmOptions

func DefaultOrmOptions() Options

DefaultOrmOptions are the default options used in the DefaultOrmFactory.

type OrmFactory

type OrmFactory interface {
	Create(options ...OrmOption) (*gorm.DB, error)
}

OrmFactory is the interface for gorm.DB factories.

func NewDefaultOrmFactory

func NewDefaultOrmFactory() OrmFactory

NewDefaultOrmFactory returns a DefaultOrmFactory, implementing OrmFactory.

type OrmOption

type OrmOption func(o *Options)

OrmOption are functional options for the OrmFactory implementations.

func WithConfig

func WithConfig(c gorm.Config) OrmOption

WithConfig is used to specify the gorm.Config to use.

func WithDriver

func WithDriver(d Driver) OrmOption

WithDriver is used to specify the database driver to use.

func WithDsn

func WithDsn(d string) OrmOption

WithDsn is used to specify the database DSN to use.