sqldb

package module
v3.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 24, 2025 License: MIT Imports: 8 Imported by: 0

README

SMARTY DISCLAIMER: Subject to the terms of the associated license agreement, this software is freely available for your use. This software is FREE, AS IN PUPPIES, and is a gift. Enjoy your new responsibility. This means that while we may consider enhancement requests, we may or may not choose to entertain requests at our sole and absolute discretion.

Build Status Code Coverage Go Report Card GoDoc

Purpose

This module allows database operations to be expressed the high-level terms of a few key interfaces (Script and Query).

By default, when the text of scripts and queries is seen multiple times we automatically transition to the use of prepared statements.

See the test suite in the integration/ folder for an example of the API.

Upgrading from v2 to v3

Those upgrading from v2 to v3 may be interested in the following code, which can be used to adapt write operations ('Scripts') to v3 while still using a v2-style interface:

package mysql

import (
	"context"

	"github.com/smarty/sqldb/v3"
)

// Deprecated
type LegacyExecutor interface {
	Execute(context.Context, string, ...any) (uint64, error)
}

// Deprecated
func newLegacyExecutor(handle sqldb.Handle) LegacyExecutor {
	return &legacyExecutor{handle: handle}
}

// Deprecated
type legacyExecutor struct {
	handle sqldb.Handle
}

// Deprecated
func (this *legacyExecutor) Execute(ctx context.Context, statement string, args ...any) (uint64, error) {
	script := &rowCountScript{
		BaseScript: sqldb.BaseScript{
			Text: statement,
			Args: args,
		},
	}
	err := this.handle.Execute(ctx, script)
	return script.rowsAffectedCount, err
}

// Deprecated
type rowCountScript struct {
	sqldb.BaseScript
	rowsAffectedCount uint64
}

// Deprecated
func (this *rowCountScript) RowsAffected(rowCount uint64) {
	this.rowsAffectedCount += rowCount
}

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrParameterCountMismatch           = errors.New("the number of parameters supplied does not match the statement")
	ErrOptimisticConcurrencyCheckFailed = errors.New("optimistic concurrency check failed")
)
View Source
var Options singleton

Functions

This section is empty.

Types

type BaseQuery

type BaseQuery struct {
	Text string
	Args []any
}

BaseQuery is a bare-minium, partial implementation of Query. Users are invited to embed it on types that define a Scan method, thus completing the Query implementation.

func (BaseQuery) Parameters

func (this BaseQuery) Parameters() []any

func (BaseQuery) Statement

func (this BaseQuery) Statement() string

type BaseScript

type BaseScript struct {
	Text string
	Args []any
}

BaseScript is a bare-minimum implementation of Script.

func (BaseScript) Parameters

func (this BaseScript) Parameters() []any

func (BaseScript) Statements

func (this BaseScript) Statements() string

type Handle

type Handle interface {
	Execute(context.Context, ...Script) error
	Populate(context.Context, ...Query) error
	PopulateRow(context.Context, ...Query) error
}

Handle is a high level approach to common database operations, where each operation implements either the Query or Script interface.

func New

func New(handle Pool, options ...option) Handle

type OptimisticConcurrencyCheck

type OptimisticConcurrencyCheck interface {
	ExpectedRowsAffected() uint64
}

OptimisticConcurrencyCheck provides an (optional) hook for a type implementing Script to verify whether the total count of all rows affected matches the returned value. If not, an error wrapped with ErrOptimisticConcurrencyCheckFailed will be returned by Handle.Execute().

type Pool

type Pool interface {
	PrepareContext(ctx context.Context, query string) (*sql.Stmt, error)
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}

Pool is a common subset of methods implemented by *sql.DB and *sql.Tx. The name is a nod to that fact that a *sql.DB implements a Pool of connections.

type Query

type Query interface {
	// Statement returns a string containing a single SQL query.
	Statement() string

	// Parameters returns a slice of the parameters to be used in the query.
	Parameters() []any

	// Scan specifies a callback to be provided the *sql.Rows for each retrieved record.
	Scan(Scanner) error
}

Query represents a SQL statement that is expected to provide rows as a result. Rows are provided to the Scan method.

type RowsAffected

type RowsAffected interface {
	RowsAffected(uint64)
}

RowsAffected provides an (optional) hook for a type implementing Script to receive the number of rows affected by executing a statement provided by a Script. It is called for each statement that doesn't result in an error.

type Scanner

type Scanner interface {
	Scan(...any) error
}

Scanner is implemented by *sql.Row and *sql.Rows.

type Script

type Script interface {
	// Statements returns a string containing 1 or more SQL statements, separated by `;`.
	// This means that the ';' character should NOT be used within any of the statements.
	Statements() string

	// Parameters returns a slice of the parameters to be interleaved across all SQL
	// returned from Statements().
	Parameters() []any
}

Script represents SQL statements that aren't expected to provide rows as a result.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL