cuttle

README

cuttle

Opinionated database toolkit for Go.

Work in progress: This is incomplete and does not fully function yet!

Features:

• TODO
• Transactions
• Batches
• Repository code generator

Codegen

Cuttle optionally includes a repository pattern code generator:

-- :cuttle version=1
-- :repository name=UsersRepository dialects=sqlite,postgres

-- :query name=InsertUser mode=exec
-- :arg name=username type=string
-- :arg name=password type=string
-- :arg name=role type=string
-- :dialect name=sqlite
INSERT INTO users (username, password, role)
VALUES (?1, ?2, ?3);
-- :dialect name=postgres
INSERT INTO users (username, password, role)
VALUES ($1, $2, $3);

Produces:

package main

import (
	"context"
	"github.com/csnewman/cuttle"
)

type UsersRepository interface {
	InsertUser(
		ctx context.Context,
		tx cuttle.WTx,
		username string,
		password string,
		role string,
	) (int64, error)

	InsertUserAsync(
		tx cuttle.AsyncWTx,
		username string,
		password string,
		role string,
		callback cuttle.AsyncHandler[int64],
	)
}

// [...]
func NewUsersRepository(dialect cuttle.Dialect) (UsersRepository, error) {
// [...]

Why not use database/sql

TODO

Drivers

Behind the scenes, cuttle uses the following libraries:

Database	Library
Postgres	github.com/jackc/pgx
SQLite	github.com/tailscale/sqlite
Other	TODO (wrapper around database/sql)

Documentation

Index

• Variables
• type AsyncHandler
• type AsyncRTx
• type AsyncWTx
• type BatchEntry
• type BatchR
  • func NewBatchR() *BatchR
  • func (b *BatchR) Query(handler AsyncHandler[Rows], stmt string, args ...any)
  • func (b *BatchR) QueryRow(handler AsyncHandler[Row], stmt string, args ...any)
• type BatchRW
  • func NewBatchRW() *BatchRW
  • func (b *BatchRW) Exec(handler AsyncHandler[Exec], stmt string, args ...any)
  • func (b *BatchRW) Query(handler AsyncHandler[Rows], stmt string, args ...any)
  • func (b *BatchRW) QueryRow(handler AsyncHandler[Row], stmt string, args ...any)
• type DB
• type Dialect
  • func (d Dialect) CompatibleWith(other Dialect) bool
  • func (d Dialect) Is(other Dialect) bool
  • func (d Dialect) Select(dialects []Dialect) (int, error)
• type DialectCompatFunc
• type Exec
• type RTx
• type RTxFunc
• type RTxFuncer
• type Row
• type Rows
• type TxFunc
• type WTx
• type WTxFunc
• type WTxFuncer

Variables

var (
	DialectGeneric = Dialect{
		Name: "generic",
		Compat: func(Dialect) uint {
			return 0
		},
	}
	DialectSQLite = Dialect{
		Name: "sqlite",
		Compat: func(dialect Dialect) uint {
			if dialect.Is(DialectGeneric) {
				return 100
			}

			return 0
		},
	}
	DialectPostgres = Dialect{
		Name: "postgres",
		Compat: func(dialect Dialect) uint {
			if dialect.Is(DialectGeneric) {
				return 100
			}

			return 0
		},
	}
)

var ErrNoCompatibleDialects = errors.New("no compatible dialects")

var ErrNoRows = errors.New("no rows")

Types

type AsyncHandler

type AsyncHandler[T any] func(ctx context.Context, result T, err error) error

type AsyncRTx

type AsyncRTx interface {
	Query(handler AsyncHandler[Rows], stmt string, args ...any)

	QueryRow(handler AsyncHandler[Row], stmt string, args ...any)
}

type AsyncWTx

type AsyncWTx interface {
	AsyncRTx

	Exec(handler AsyncHandler[Exec], stmt string, args ...any)
}

type BatchEntry

type BatchEntry struct {
	Stmt            string
	Args            []any
	ExecHandler     AsyncHandler[Exec]
	QueryHandler    AsyncHandler[Rows]
	QueryRowHandler AsyncHandler[Row]
}

type BatchR

type BatchR struct {
	Entries []*BatchEntry
}

func NewBatchR

func NewBatchR() *BatchR

func (*BatchR) Query

func (b *BatchR) Query(handler AsyncHandler[Rows], stmt string, args ...any)

func (*BatchR) QueryRow

func (b *BatchR) QueryRow(handler AsyncHandler[Row], stmt string, args ...any)

type BatchRW

type BatchRW struct {
	Entries []*BatchEntry
}

func NewBatchRW

func NewBatchRW() *BatchRW

func (*BatchRW) Exec

func (b *BatchRW) Exec(handler AsyncHandler[Exec], stmt string, args ...any)

func (*BatchRW) Query

func (b *BatchRW) Query(handler AsyncHandler[Rows], stmt string, args ...any)

func (*BatchRW) QueryRow

func (b *BatchRW) QueryRow(handler AsyncHandler[Row], stmt string, args ...any)

type DB

type DB interface {
	WTxFuncer

	RTx(ctx context.Context, f RTxFunc) error

	WTx(ctx context.Context, f WTxFunc) error

	Dialect() Dialect
}

type Dialect

type Dialect struct {
	Name   string
	Compat DialectCompatFunc
}

func (Dialect) CompatibleWith

func (d Dialect) CompatibleWith(other Dialect) bool

func (Dialect) Is

func (d Dialect) Is(other Dialect) bool

func (Dialect) Select

func (d Dialect) Select(dialects []Dialect) (int, error)

type DialectCompatFunc

type DialectCompatFunc func(dialect Dialect) uint

type Exec

type Exec interface {
	RowsAffected() int64
}

type RTx

type RTx interface {
	RTxFuncer

	Query(ctx context.Context, stmt string, args ...any) (Rows, error)

	QueryRow(ctx context.Context, stmt string, args ...any) (Row, error)
}

type RTxFunc

type RTxFunc = func(ctx context.Context, tx RTx) error

type RTxFuncer

type RTxFuncer interface {
	QueryFunc(ctx context.Context, handler TxFunc[Rows], stmt string, args ...any) error

	QueryRowFunc(ctx context.Context, handler TxFunc[Row], stmt string, args ...any) error

	DispatchBatchR(ctx context.Context, b *BatchR) error
}

type Row

type Row interface {
	Scan(dest ...any) error
}

type Rows

type Rows interface {
	Close() error

	Next(dest ...any) (bool, error)
}

type TxFunc

type TxFunc[T any] func(ctx context.Context, result T) error

type WTx

type WTx interface {
	RTx
	WTxFuncer

	Exec(ctx context.Context, stmt string, args ...any) (Exec, error)
}

type WTxFunc

type WTxFunc = func(ctx context.Context, tx WTx) error

type WTxFuncer

type WTxFuncer interface {
	RTxFuncer

	ExecFunc(ctx context.Context, handler TxFunc[Exec], stmt string, args ...any) error

	DispatchBatchRW(ctx context.Context, b *BatchRW) error
}