sqlp

README

sqlp - SQL database extras

go get -u "tawesoft.co.uk/go"

import "tawesoft.co.uk/go/sqlp"

Links	License	Stable?
home ∙ docs ∙ src	MIT	candidate

About

Package sqlp ("SQL-plus" or "squelp!") defines helpful interfaces and implements extra features for Go SQL database drivers. Specific driver extras are implemented in the subdirectories.

Features

• Open a SQLite database with foreign keys, UTF8 collation, etc. made easy to avoid copy+pasting the same boilerplate into each project.

• "Missing" essentials like escaping an SQL column name (https://github.com/golang/go/issues/18478) or examining an SQL error for properties such as IsUniqueConstraintError when inserting duplicate items

• Interfaces like Queryable which is implemented by all of sql.DB, sql.Tx and sql.Stmt, for performing queries regardless of if they are in a transaction or not.

Driver extras

• tawesoft.co.uk/go/sqlp/sqlite3 (mattn/go-sqlite3)

Getting Help

This package is part of tawesoft.co.uk/go, a monorepo for small Go modules maintained by Tawesoft®. Check out that URL for more information about other Go modules from Tawesoft plus community and commercial support options.

Documentation

Overview

Package sqlp ("SQL-plus" or "squelp!") defines helpful interfaces and implements extra features for Go SQL database drivers. Specific driver extras are implemented in the subdirectories.

Features

* Open a SQLite database with foreign keys, UTF8 collation, etc. made easy to avoid copy+pasting the same boilerplate into each project.

* "Missing" essentials like escaping an SQL column name (https://github.com/golang/go/issues/18478) or examining an SQL error for properties such as IsUniqueConstraintError when inserting duplicate items

* Interfaces like Queryable which is implemented by all of sql.DB, sql.Tx and sql.Stmt, for performing queries regardless of if they are in a transaction or not.

Driver extras

* tawesoft.co.uk/go/sqlp/sqlite3 (mattn/go-sqlite3)

Package Information

License: MIT (see LICENSE.txt)

Stable: candidate

For more information, documentation, source code, examples, support, links, etc. please see https://www.tawesoft.co.uk/go and https://www.tawesoft.co.uk/go/sqlp

Index

• func EscapeIdentifier(f *Features, s string) (string, error)
• func EscapeString(f *Features, s string) (string, error)
• func IsUniqueConstraintError(f *Features, err error) bool
• func OpenMode(driverName string, dataSource string, mode int, ...) (*sql.DB, error)
• func RepeatString(x string, n int) string
• func RowsAffectedBetween(result sql.Result, min int, max int) (int64, bool)
• type Features
• type Queryable
• type Transactionable

Functions

func EscapeIdentifier

func EscapeIdentifier(f *Features, s string) (string, error)

EscapeIdentifier returns a SQL identifier (such as a column name) for a given database driver.

func EscapeString

func EscapeString(f *Features, s string) (string, error)

EscapeString returns a quoted string literal for a given database driver.

func IsUniqueConstraintError

func IsUniqueConstraintError(f *Features, err error) bool

IsUniqueConstraintError returns true iff the database driver implements a check for unique constraint errors and the error indicates a statement did not execute because it would violate a uniqueness constraint e.g. when attempting to insert a duplicate item.

func OpenMode

func OpenMode(
	driverName string,
	dataSource string,
	mode int,
	Opener func(string, string) (*sql.DB, error),
) (*sql.DB, error)

OpenMode wraps a database opener (e.g. a sqlite3.Opener) with a syscall to set the file permissions to a unix mode when the file is created (e.g. mode 0600 for user read/write only) and, additionally, checks the connection using db.Ping().

Note - NOT safe to be used concurrently with other I/O due to use of syscall

func RepeatString

func RepeatString(x string, n int) string

RepeatString returns a repeating, comma-separted string of `n` instances of `x`, for building queries with multiple arguments.

e.g. RepeatString('?', 3) returns "?, ?, ?"

func RowsAffectedBetween

func RowsAffectedBetween(result sql.Result, min int, max int) (int64, bool)

RowsAffectedBetween returns true iff the result rows affected is not an error and falls between min and max (inclusive). Otherwise, returns false and the first argument is the number of rows actually affected.

Rarely, returns -1 and false if there was an error counting how many rows were affected (which should only ever happen if there is a bug in your code e.g. trying to count rows affected by a DDL command (such as a CREATE TABLE) or not checking a previous error and using an invalid result).

Types

type Features

type Features struct {
	EscapeIdentifier        func(s string) (string, error)
	EscapeString            func(s string) (string, error)
	IsUniqueConstraintError func(err error) bool
}

Features are a common set of features with driver-specific implementations. e.g. `import tawesoft.co.uk/go/sqlp/sqlite3` and use sqlite3.Features

type Queryable

type Queryable interface {
	Exec(query string, args ...interface{}) (sql.Result, error)
	ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)
	Query(query string, args ...interface{}) (*sql.Rows, error)
	QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)
	QueryRow(query string, args ...interface{}) *sql.Row
	QueryRowContext(ctx context.Context, query string, args ...interface{}) *sql.Row
}

Queryable is an interface describing the intersection of the methods implemented by sql.DB, sql.Tx, and sql.Stmt.

type Transactionable

type Transactionable interface {
	Queryable
	Begin() (*sql.Tx, error)
	BeginTx(ctx context.Context, opts *sql.TxOptions) (*sql.Tx, error)
}

Transactionable is an interface describing a Queryable that can start (possibly nested) transactions. A sql.Tx is not transactable, but a sql.DB is.