sqlapi

package module
v0.30.0 Latest Latest
Warning

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

 Go to latest Published: Jul 2, 2019 License: BSD-2-Clause Imports: 13 Imported by: 2

README

sqlapi

GoDoc Build Status Code Coverage Issues

sqlgen generates SQL statements and database helper functions from your Go structs. It can be used in place of a simple ORM or hand-written SQL. sqlapi (this package) supports the generated code.

See the demo directory for examples. Look in the generated files *_sql.go and the hand-crafted files (hook.go, issue.go, user.go).

Currently, support is included for MySQL, PostgreSQL and SQLite. Other dialects can be added relatively easy - send a Pull Request!

All dialects generated ANSI SQL (in particular, this means that column names and identifiers are surrounded by double-quotes).

Features

package constraint
  • Representations for inter-table constraints.
package require
  • Predicates allowing easier detection of unexpected results from SELECTS, e.g. when the result set size is not exactly one.
package dialect
  • SQL dialects
package where
  • Fluent construction of WHERE and HAVING clauses.

Install

Install with this command:

go get github.com/rickb777/sqlapi

Please continue reading about sqlgen2.

Documentation

Overview

Package sqlapi contains a small API for a tool (sqlgen2) that generates SQL functions for specified struct types.

Lighter than a full-blown ORM and simpler than hand-written code, the output makes it easy to write flexible yet reliable and high-performance database code.

See the README for further details: https://github.com/rickb777/sqlapi/blob/master/README.md

Index

Constants

View Source 
const Version = "v0.29.0"

Variables

This section is empty.

Functions

func Named 

func Named(name string, value interface{}) sql.NamedArg

Named creates NamedArg values; it is synonymous with sql.Named().

func NamedArgString 

func NamedArgString(arg sql.NamedArg) string

NamedArgString converts the argument to a string of the form "name=value".

Types

type CanPostGet 

type CanPostGet interface {
	PostGet() error
}

CanPostGet is implemented by value types that need a hook to run just after their data is fetched from the database.

type CanPreInsert 

type CanPreInsert interface {
	PreInsert() error
}

CanPreInsert is implemented by value types that need a hook to run just before their data is inserted into the database.

type CanPreUpdate 

type CanPreUpdate interface {
	PreUpdate() error
}

CanPreUpdate is implemented by value types that need a hook to run just before their data is updated in the database.

type Database 

type Database interface {
	DB() Execer
	Dialect() dialect.Dialect
	Logger() Logger
	Wrapper() interface{}
	PingContext(ctx context.Context) error
	Ping() error
	Stats() sql.DBStats

	ListTables(re *regexp.Regexp) (util.StringList, error)
}

Database typically wraps a *sql.DB with a dialect and (optionally) a logger. It's safe for concurrent use by multiple goroutines. See NewDatabase.

func NewDatabase 

func NewDatabase(db SqlDB, dialect dialect.Dialect, logger *log.Logger, wrapper interface{}) Database

NewDatabase creates a new database handler, which wraps the core *sql.DB along with the appropriate dialect.

You can supply the logger you need, or else nil. If not nil, all queries will be logged and all database errors will be logged. Once constructed, the logger itself cannot be changed, but its output writer can (via the SetOutput method on Logger). Logging can be enabled and disabled as needed by using the TraceLogging method.

The wrapper holds some associated data your application needs for this database, if any. Otherwise this should be nil. As with the logger, it cannot be changed after construction.

type Execer 

type Execer interface {
	// ExecContext executes a query without returning any rows.
	// The arguments are for any placeholder parameters in the query.
	ExecContext(ctx context.Context, query string, arguments ...interface{}) (int64, error)

	// InsertContext executes a query and returns the insertion ID.
	// The arguments are for any placeholder parameters in the query.
	InsertContext(ctx context.Context, query string, arguments ...interface{}) (int64, error)

	// PrepareContext creates a prepared statement for later queries or executions.
	// Multiple queries or executions may be run concurrently from the
	// returned statement.
	// The caller must call the statement's Close method
	// when the statement is no longer needed.
	//
	// The provided context is used for the preparation of the statement, not for the
	// execution of the statement.
	PrepareContext(ctx context.Context, name, query string) (SqlStmt, error)

	// QueryContext executes a query that returns rows, typically a SELECT.
	// The arguments are for any placeholder parameters in the query.
	QueryContext(ctx context.Context, query string, arguments ...interface{}) (SqlRows, error)

	// QueryRowContext executes a query that is expected to return at most one row.
	// QueryRowContext always returns a non-nil value. Errors are deferred until
	// Row's Scan method is called.
	// If the query selects no rows, the *Row's Scan will return ErrNoRows.
	// Otherwise, the *Row's Scan scans the first selected row and discards
	// the rest.
	QueryRowContext(ctx context.Context, query string, arguments ...interface{}) SqlRow

	IsTx() bool
}

Execer is a precis of *sql.DB and *sql.Tx. See database/sql.

type Logger added in v0.26.0 

type Logger interface {
	Log(format string, v ...interface{})
	LogT(msg string, startTime *time.Time, data ...interface{})
	LogQuery(query string, args ...interface{})
	LogIfError(err error) error
	LogError(err error) error
	TraceLogging(on bool)
}

func NewLogger added in v0.27.0 

func NewLogger(lgr StdLog) Logger

type NamedArgList 

type NamedArgList []sql.NamedArg

NamedArgList holds a slice of NamedArgs

func (NamedArgList) Assignments 

func (list NamedArgList) Assignments(q quote.Quoter, from int) []string

Assignments gets the assignment expressions.

func (NamedArgList) Contains 

func (list NamedArgList) Contains(name string) bool

Contains tests whether anything in the list has a certain name.

func (NamedArgList) Exists 

func (list NamedArgList) Exists(fn func(sql.NamedArg) bool) bool

Exists verifies that one or more elements of NamedArgList return true for the passed func.

func (NamedArgList) Find 

func (list NamedArgList) Find(fn func(sql.NamedArg) bool) (sql.NamedArg, bool)

Find returns the first sql.NamedArg that returns true for some function. False is returned if none match.

func (NamedArgList) FindByName 

func (list NamedArgList) FindByName(name string) (sql.NamedArg, bool)

FindByName finds the first item with a particular name.

func (NamedArgList) MkString 

func (list NamedArgList) MkString(sep string) string

MkString produces a string ontainin all the values separated by sep.

func (NamedArgList) Names 

func (list NamedArgList) Names() []string

Names gets all the names.

func (NamedArgList) String 

func (list NamedArgList) String() string

String produces a string ontainin all the values separated by comma.

func (NamedArgList) Values 

func (list NamedArgList) Values() []interface{}

Values gets all the valules

type RowData 

type RowData struct {
	Columns     []string
	ColumnTypes []*sql.ColumnType
	Data        util.StringAnyMap
}

RowData holds a single row result from the database.

type Rows 

type Rows struct {
	Rows SqlRows
	// contains filtered or unexported fields
}

Rows provides a tool for scanning result *sql.Rows of arbitrary or varying length. The internal *sql.Rows field is exported and is usable as per normal via its Next and Scan methods, or the Next and ScanToMap methods can be used instead.

func WrapRows 

func WrapRows(rows SqlRows) (*Rows, error)

WrapRows wraps a *sql.Rows result so that its data can be scanned into a series of maps, one for each row.

func (*Rows) Close 

func (rams *Rows) Close() error

Close closes the Rows, preventing further enumeration. If Next is called and returns false and there are no further result sets, the Rows are closed automatically and it will suffice to check the result of Err. Close is idempotent and does not affect the result of Err.

func (*Rows) ColumnTypes 

func (rams *Rows) ColumnTypes() ([]*sql.ColumnType, error)

ColumnTypes returns column information such as column type, length, and nullable. Some information may not be available from some drivers.

func (*Rows) Columns 

func (rams *Rows) Columns() ([]string, error)

Columns returns the column names.

func (*Rows) Err 

func (rams *Rows) Err() error

Err returns the error, if any, that was encountered during iteration. Err may be called after an explicit or implicit Close.

func (*Rows) Next 

func (rams *Rows) Next() bool

Next prepares the next result row for reading with the Scan method. It returns true on success, or false if there is no next result row or an error happened while preparing it. Err should be consulted to distinguish between the two cases.

Every call to Scan, even the first one, must be preceded by a call to Next.

func (*Rows) Scan 

func (rams *Rows) Scan(dest ...interface{}) error

Scan copies the columns in the current row into the values pointed at by dest. The number of values in dest must be the same as the number of columns in the wrapped Rows.

func (*Rows) ScanToMap 

func (rams *Rows) ScanToMap() (RowData, error)

ScanToMap copies all the column data of the current row into a map. The map is keyed by column name.

The result describes a single row from the database, consisting of the column names, types and data.

type SqlDB added in v0.17.0 

type SqlDB interface {
	Execer
	BeginTx(ctx context.Context, opts *sql.TxOptions) (SqlTx, error)
	Transact(ctx context.Context, txOptions *sql.TxOptions, fn func(SqlTx) error) error
	PingContext(ctx context.Context) error
	Stats() sql.DBStats
	Close() error
}

SqlDB is able to make queries and begin transactions.

func WrapDB added in v0.26.0 

func WrapDB(ex *sql.DB) SqlDB

type SqlRow added in v0.17.0 

type SqlRow interface {
	Scan(dest ...interface{}) error
}

SqlRow is a precis of *sql.Row.

type SqlRows added in v0.17.0 

type SqlRows interface {
	SqlRow
	Next() bool
	Columns() ([]string, error)
	ColumnTypes() ([]*sql.ColumnType, error)
	Close() error
	Err() error
}

SqlRows is a precis of *sql.Rows.

type SqlStmt added in v0.17.0 

type SqlStmt interface {
	// ExecContext executes a query without returning any rows.
	// The arguments are for any placeholder parameters in the query.
	ExecContext(ctx context.Context, arguments ...interface{}) (sql.Result, error)

	// QueryContext executes a query that returns rows, typically a SELECT.
	// The arguments are for any placeholder parameters in the query.
	QueryContext(ctx context.Context, arguments ...interface{}) (*sql.Rows, error)

	// QueryRowContext executes a query that is expected to return at most one row.
	// QueryRowContext always returns a non-nil value. Errors are deferred until
	// Row's Scan method is called.
	// If the query selects no rows, the *Row's Scan will return ErrNoRows.
	// Otherwise, the *Row's Scan scans the first selected row and discards
	// the rest.
	QueryRowContext(ctx context.Context, arguments ...interface{}) *sql.Row

	Close() error
}

SqlStmt is a precis of *sql.Stmt

type SqlTx added in v0.17.0 

type SqlTx interface {
	Execer
	Commit() error
	Rollback() error
}

SqlTx is a precis of *sql.Tx

type StdLog added in v0.27.0 

type StdLog interface {
	Printf(format string, v ...interface{})
	SetOutput(w io.Writer)
}

type Table 

type Table interface {
	// Name gets the table name. without prefix
	Name() TableName

	// Database gets the shared database information.
	Database() Database

	// Execer gets the wrapped database or transaction handle.
	Execer() Execer

	// DB gets the wrapped database handle, provided this is not within a transaction.
	// Panics if it is in the wrong state - use IsTx() if necessary.
	DB() SqlDB

	// Tx gets the wrapped transaction handle, provided this is within a transaction.
	// Panics if it is in the wrong state - use IsTx() if necessary.
	Tx() SqlTx

	// IsTx tests whether this is within a transaction.
	IsTx() bool

	// Ctx gets the current request context.
	Ctx() context.Context

	// Dialect gets the database dialect.
	Dialect() dialect.Dialect

	// Logger gets the trace logger.
	Logger() Logger
}

Table provides the generic features of each generated table handler.

type TableCreator 

type TableCreator interface {
	Table

	// CreateTable creates the database table.
	CreateTable(ifNotExists bool) (int64, error)

	// DropTable drops the database table.
	DropTable(ifExists bool) (int64, error)

	// Truncate empties the table
	Truncate(force bool) (err error)
}

TableCreator is a table with create/delete/truncate methods.

type TableName 

type TableName struct {
	// Prefix on the table name. It can be used as the schema name, in which case
	// it should include the trailing dot. Or it can be any prefix as needed.
	Prefix string

	// The principal name of the table.
	Name string
}

TableName holds a two-part name. The prefix part is optional.

func (TableName) PrefixWithoutDot 

func (tn TableName) PrefixWithoutDot() string

PrefixWithoutDot return the prefix; if this ends with a dot, the dot is removed.

func (TableName) String 

func (tn TableName) String() string

String gets the full table name.

type TableWithIndexes 

type TableWithIndexes interface {
	TableCreator

	// CreateIndexes creates the indexes for the database table.
	CreateIndexes(ifNotExist bool) (err error)

	// DropIndexes executes a query that drops all the indexes on the database table.
	DropIndexes(ifExist bool) (err error)

	// CreateTableWithIndexes creates the database table and its indexes.
	CreateTableWithIndexes(ifNotExist bool) (err error)
}

TableWithIndexes is a table creator with create/delete methods for the indexes.

Source Files

View all Source files

Directories

Path Synopsis
Package constraint provides types and methods to support foreign-key relationshipd between database tables.
 Package constraint provides types and methods to support foreign-key relationshipd between database tables.
Package sqlapi contains a small API for a tool (sqlgen2) that generates SQL functions for specified struct types.
 Package sqlapi contains a small API for a tool (sqlgen2) that generates SQL functions for specified struct types.
constraint
Package constraint provides types and methods to support foreign-key relationshipd between database tables.
 Package constraint provides types and methods to support foreign-key relationshipd between database tables.
logadapter
Package logadapter provides a logger that writes to a log.Logger log.
 Package logadapter provides a logger that writes to a log.Logger log.
support
vanilla
Package vanilla provides a re-usable table API.
 Package vanilla provides a re-usable table API.
Package require provides simple constraints to assist with detecting errors in database queries that arise from the wrong number of result (for example no result or too many results).
 Package require provides simple constraints to assist with detecting errors in database queries that arise from the wrong number of result (for example no result or too many results).
Package vanilla provides a re-usable table API.
 Package vanilla provides a re-usable table API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.