Back to godoc.org
gopkg.in/reform.v1

Package reform

v1.4.0
Latest Go to latest
Published: 5 days ago | License: MIT | Module: gopkg.in/reform.v1

Overview

Package reform is a better ORM for Go, based on non-empty interfaces and code generation.

See README (https://github.com/go-reform/reform/blob/main/README.md) for quickstart information.

Context

Querier object, embedded into DB and TX types, contains context which is used by all its methods. It defaults to context.Background() and can be changed with WithContext method:

// for a single call
projects, err := DB.WithContext(ctx).SelectAllFrom(ProjectTable, "")

// for several calls
q := DB.WithContext(ctx)
projects, err := q.SelectAllFrom(ProjectTable, "")
persons, err := q.SelectAllFrom(PersonTable, "")

Methods Exec, Query, and QueryRow use the same context. Methods ExecContext, QueryContext, and QueryRowContext are just compatibility wrappers for Querier.WithContext(ctx).Exec/Query/QuyeryRow to satisfy various standard interfaces.

DB object methods Begin and InTransaction start transaction with the same context. Methods BeginTx and InTransactionContext start transaction with a given context without changing DB's context:

var projects, persons []Struct
err := DB.InTransactionContext(ctx, nil, func(tx *reform.TX) error {
    var e error

    // uses ctx
    if projects, e = tx.SelectAllFrom(ProjectTable, ""); e != nil {
        return e
    }

    // uses ctx too
    if persons, e = tx.SelectAllFrom(PersonTable, ""); e != nil {
        return e
    }

    return nil
}

Note that several different contexts can be used:

DB.InTransactionContext(ctx1, nil, func(tx *reform.TX) error {
    _, _ = tx.SelectAllFrom(PersonTable, "")                    // uses ctx1
    _, _ = tx.WithContext(ctx2).SelectAllFrom(PersonTable, "")  // uses ctx2
    ...
})

In theory, ctx1 and ctx2 can be entirely unrelated. Although that construct is occasionally useful, the behavior on context cancelation is entirely driver-defined; some drivers may just close the whole connection, effectively canceling unrelated ctx2 on ctx1 cancelation. For that reason mixing several contexts is not recommended.

Tagging

reform allows one to add tags (comments) to generated queries with WithTag Querier method. They can be used to track queries from RDBMS logs and tools back to application code. For example, this code:

id := "baron"
project, err := DB.WithTag("GetProject:%v", id).FindByPrimaryKeyFrom(ProjectTable, id)

will generate the following query:

SELECT /* GetProject:baron */ "projects"."name", "projects"."id", "projects"."start", "projects"."end" FROM "projects" WHERE "projects"."id" = ? LIMIT 1

Please keep in mind that dynamic tags can affect RDBMS query cache. Consult your RDBMS documentation for details. Some known links:

MySQL / Percona Server: https://www.percona.com/doc/percona-server/5.7/performance/query_cache_enhance.html#ignoring-comments
Microsoft SQL Server: https://msdn.microsoft.com/en-us/library/cc293623.aspx

Short example

This example shows some reform features. It uses https://github.com/AlekSi/pointer to get pointers to values of build-in types.

Example

Code:

person := &Person{
	Name:  "Alexey Palazhchenko",
	Email: pointer.ToString("alexey.palazhchenko@gmail.com"),
}
if err := DB.Save(person); err != nil {
	log.Fatal(err)
}

person2, err := DB.FindByPrimaryKeyFrom(PersonTable, person.ID)
if err != nil {
	log.Fatal(err)
}
fmt.Println(person2.(*Person).Name)

if err = DB.Delete(person); err != nil {
	log.Fatal(err)
}

persons, err := DB.FindAllFrom(PersonTable, "id", 1, 2)
if err != nil {
	log.Fatal(err)
}
for _, p := range persons {
	fmt.Println(p)
}
Alexey Palazhchenko
ID: 1 (int32), GroupID: 65534 (*int32), Name: `Denis Mills` (string), Email: <nil> (*string), CreatedAt: 2009-11-10 23:00:00 +0000 UTC (time.Time), UpdatedAt: <nil> (*time.Time)
ID: 2 (int32), GroupID: 65534 (*int32), Name: `Garrick Muller` (string), Email: `muller_garrick@example.com` (*string), CreatedAt: 2009-12-12 12:34:56 +0000 UTC (time.Time), UpdatedAt: <nil> (*time.Time)

Index

Examples

Package Files

Constants

const Version = "v1.4.0"

Version defines reform version.

Variables

var (
	// ErrNoRows is returned from various methods when query produced no rows.
	ErrNoRows = sql.ErrNoRows

	// ErrTxDone is returned from Commit() and Rollback() TX methods when transaction is already
	// committed or rolled back.
	ErrTxDone = sql.ErrTxDone

	// ErrNoPK is returned from various methods when primary key is required and not set.
	ErrNoPK = errors.New("reform: no primary key")
)

func Inspect

func Inspect(arg interface{}, addType bool) string

Inspect returns suitable for logging representation of a query argument.

type AfterFinder

type AfterFinder interface {
	AfterFind() error
}

AfterFinder is an optional interface for Record which is used by Querier's finders and selectors. It can be used to convert timezones, change data precision, etc. Returning error aborts operation.

type BeforeInserter

type BeforeInserter interface {
	BeforeInsert() error
}

BeforeInserter is an optional interface for Record which is used by Querier.Insert. It can be used to set record's timestamp fields, convert timezones, change data precision, etc. Returning error aborts operation.

type BeforeUpdater

type BeforeUpdater interface {
	BeforeUpdate() error
}

BeforeUpdater is an optional interface for Record which is used by Querier.Update and Querier.UpdateColumns. It can be used to set record's timestamp fields, convert timezones, change data precision, etc. Returning error aborts operation.

type DB

type DB struct {
	*Querier
	// contains filtered or unexported fields
}

DB represents a connection to SQL database.

func NewDB

func NewDB(db *sql.DB, dialect Dialect, logger Logger) *DB

NewDB creates new DB object for given SQL database connection. Logger can be nil.

Example

Code:

sqlDB, err := sql.Open("postgres", "postgres://127.0.0.1:5432/database")
if err != nil {
	log.Fatal(err)
}
defer sqlDB.Close()

logger := log.New(os.Stderr, "SQL: ", log.Flags())

_ = reform.NewDB(sqlDB, postgresql.Dialect, reform.NewPrintfLogger(logger.Printf))

func NewDBFromInterface

func NewDBFromInterface(db DBInterface, dialect Dialect, logger Logger) *DB

NewDBFromInterface creates new DB object for given DBInterface. Can be used for easier integration with existing code or for passing test doubles. Logger can be nil.

func (*DB) Begin

func (db *DB) Begin() (*TX, error)

Begin starts transaction with Querier's context and default options.

func (*DB) BeginTx

func (db *DB) BeginTx(ctx context.Context, opts *sql.TxOptions) (*TX, error)

BeginTx starts transaction with given context and options (can be nil).

func (*DB) DBInterface

func (db *DB) DBInterface() DBInterface

DBInterface returns DBInterface associated with a given DB object.

func (*DB) InTransaction

func (db *DB) InTransaction(f func(t *TX) error) error

InTransaction wraps function execution in transaction with Querier's context and default options, rolling back it in case of error or panic, committing otherwise.

func (*DB) InTransactionContext

func (db *DB) InTransactionContext(ctx context.Context, opts *sql.TxOptions, f func(t *TX) error) error

InTransactionContext wraps function execution in transaction with given context and options (can be nil), rolling back it in case of error or panic, committing otherwise.

type DBInterface

type DBInterface interface {
	DBTXContext
	BeginTx(ctx context.Context, opts *sql.TxOptions) (*sql.Tx, error)

	// Deprecated: do not use, it will be removed in v1.5.
	DBTX
	// Deprecated: do not use, it will be removed in v1.5.
	Begin() (*sql.Tx, error)
}

DBInterface is a subset of *sql.DB used by reform. Can be used together with NewDBFromInterface for easier integration with existing code or for passing test doubles.

It may grow and shrink over time to include only needed *sql.DB methods, and is excluded from SemVer compatibility guarantees.

type DBTX

type DBTX interface {
	// Exec executes a query without returning any rows.
	// The args are for any placeholder parameters in the query.
	Exec(query string, args ...interface{}) (sql.Result, error)

	// Query executes a query that returns rows, typically a SELECT.
	// The args are for any placeholder parameters in the query.
	Query(query string, args ...interface{}) (*sql.Rows, error)

	// QueryRow executes a query that is expected to return at most one row.
	// QueryRow 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.
	QueryRow(query string, args ...interface{}) *sql.Row
}

DBTX is an interface for database connection or transaction. It's implemented by *sql.DB, *sql.Tx, *DB, *TX, and *Querier.

type DBTXContext

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

	// QueryContext executes a query that returns rows, typically a SELECT.
	// The args are for any placeholder parameters in the query.
	QueryContext(ctx context.Context, query string, args ...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, query string, args ...interface{}) *sql.Row
}

DBTXContext is an interface for database connection or transaction with context support. It's implemented by *sql.DB, *sql.Tx, *sql.Conn, *DB, *TX, and *Querier.

type DefaultValuesMethod

type DefaultValuesMethod int

DefaultValuesMethod is a method of inserting of row with all default values.

const (
	// DefaultValues is a method using "DEFAULT VALUES"
	DefaultValues DefaultValuesMethod = iota

	// EmptyLists is a method using "() VALUES ()"
	EmptyLists
)

type Dialect

type Dialect interface {
	// String returns dialect name.
	String() string

	// Placeholder returns representation of placeholder parameter for given index,
	// typically "?" or "$1".
	Placeholder(index int) string

	// Placeholders returns representation of placeholder parameters for given start index and count,
	// typically []{"?", "?"} or []{"$1", "$2"}.
	Placeholders(start, count int) []string

	// QuoteIdentifier returns quoted database identifier,
	// typically "identifier" or `identifier`.
	QuoteIdentifier(identifier string) string

	// LastInsertIdMethod returns a method of receiving primary key of last inserted row.
	LastInsertIdMethod() LastInsertIdMethod

	// SelectLimitMethod returns a method of limiting the number of rows in a query result.
	SelectLimitMethod() SelectLimitMethod

	// DefaultValuesMethod returns a method of inserting of row with all default values.
	DefaultValuesMethod() DefaultValuesMethod
}

Dialect represents differences in various SQL dialects.

type LastInsertIdMethod

type LastInsertIdMethod int

LastInsertIdMethod is a method of receiving primary key of last inserted row.

const (
	// LastInsertId is method using sql.Result.LastInsertId().
	LastInsertId LastInsertIdMethod = iota

	// Returning is method using "RETURNING id" SQL syntax.
	Returning

	// OutputInserted is method using "OUTPUT INSERTED.id" SQL syntax.
	OutputInserted
)

type Logger

type Logger interface {
	// Before logs query before execution.
	Before(query string, args []interface{})

	// After logs query after execution.
	After(query string, args []interface{}, d time.Duration, err error)
}

Logger is responsible to log queries before and after their execution.

type Printf

type Printf func(format string, args ...interface{})

Printf is a (fmt.Printf|log.Printf|testing.T.Logf)-like function.

type PrintfLogger

type PrintfLogger struct {
	LogTypes bool
	// contains filtered or unexported fields
}

PrintfLogger is a simple query logger.

func NewPrintfLogger

func NewPrintfLogger(printf Printf) *PrintfLogger

NewPrintfLogger creates a new simple query logger for any Printf-like function.

func (*PrintfLogger) After

func (pl *PrintfLogger) After(query string, args []interface{}, d time.Duration, err error)

After logs query after execution.

func (*PrintfLogger) Before

func (pl *PrintfLogger) Before(query string, args []interface{})

Before logs query before execution.

type Querier

type Querier struct {
	Dialect
	Logger Logger
	// contains filtered or unexported fields
}

Querier performs queries and commands.

func (*Querier) Context

func (q *Querier) Context() context.Context

Context returns Querier's context. Default context is context.Background().

func (*Querier) Count

func (q *Querier) Count(view View, tail string, args ...interface{}) (int, error)

Count queries view with tail and args and returns a number (COUNT(*)) of matching rows.

func (*Querier) Delete

func (q *Querier) Delete(record Record) error

Delete deletes record from SQL database table by primary key.

Method returns ErrNoRows if no rows were deleted. Method returns ErrNoPK if primary key is not set.

func (*Querier) DeleteFrom

func (q *Querier) DeleteFrom(view View, tail string, args ...interface{}) (uint, error)

DeleteFrom deletes rows from view with tail and args and returns a number of deleted rows.

Method never returns ErrNoRows.

func (*Querier) Exec

func (q *Querier) Exec(query string, args ...interface{}) (sql.Result, error)

Exec executes a query without returning any rows. The args are for any placeholder parameters in the query.

func (*Querier) ExecContext

func (q *Querier) ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)

ExecContext just calls q.WithContext(ctx).Exec(query, args...), and that form should be used instead. This method exists to satisfy various standard interfaces for advanced use-cases.

func (*Querier) FindAllFrom

func (q *Querier) FindAllFrom(view View, column string, args ...interface{}) ([]Struct, error)

FindAllFrom queries view with column and args and returns a slice of new Structs. If view's Struct implements AfterFinder, it also calls AfterFind().

In case of query error slice will be nil. If error is encountered during iteration, partial result and error will be returned. Error is never ErrNoRows.

func (*Querier) FindByPrimaryKeyFrom

func (q *Querier) FindByPrimaryKeyFrom(table Table, pk interface{}) (Record, error)

FindByPrimaryKeyFrom queries table with primary key and scans first result to new Record. If record implements AfterFinder, it also calls AfterFind().

If there are no rows in result, it returns nil, ErrNoRows. It also may return QueryRow(), Scan() and AfterFinder errors.

func (*Querier) FindByPrimaryKeyTo

func (q *Querier) FindByPrimaryKeyTo(record Record, pk interface{}) error

FindByPrimaryKeyTo queries record's Table with primary key and scans first result to record. If record implements AfterFinder, it also calls AfterFind().

If there are no rows in result, it returns ErrNoRows. It also may return QueryRow(), Scan() and AfterFinder errors.

func (*Querier) FindOneFrom

func (q *Querier) FindOneFrom(view View, column string, arg interface{}) (Struct, error)

FindOneFrom queries view with column and arg and scans first result to new Struct str. If str implements AfterFinder, it also calls AfterFind().

If there are no rows in result, it returns nil, ErrNoRows. It also may return QueryRow(), Scan() and AfterFinder errors.

func (*Querier) FindOneTo

func (q *Querier) FindOneTo(str Struct, column string, arg interface{}) error

FindOneTo queries str's View with column and arg and scans first result to str. If str implements AfterFinder, it also calls AfterFind().

If there are no rows in result, it returns ErrNoRows. It also may return QueryRow(), Scan() and AfterFinder errors.

func (*Querier) FindRows

func (q *Querier) FindRows(view View, column string, arg interface{}) (*sql.Rows, error)

FindRows queries view with column and arg and returns rows. They can then be iterated with NextRow(). It is caller's responsibility to call rows.Close().

In case of error rows will be nil. Error is never ErrNoRows.

See SelectRows example for idiomatic usage.

func (*Querier) Insert

func (q *Querier) Insert(str Struct) error

Insert inserts a struct into SQL database table. If str implements BeforeInserter, it calls BeforeInsert() before doing so.

It fills record's primary key field.

func (*Querier) InsertColumns

func (q *Querier) InsertColumns(str Struct, columns ...string) error

InsertColumns inserts a struct into SQL database table with specified columns. Other columns are omitted from generated INSERT statement. If str implements BeforeInserter, it calls BeforeInsert() before doing so.

It fills record's primary key field.

func (*Querier) InsertMulti

func (q *Querier) InsertMulti(structs ...Struct) error

InsertMulti inserts several structs into SQL database table with single query. If they implement BeforeInserter, it calls BeforeInsert() before doing so.

All structs should belong to the same view/table. All records should either have or not have primary key set. It doesn't fill primary key fields. Given all these limitations, most users should use Querier.Insert in a loop, not this method.

Example

Code:

// insert up to 3 structs at once
const batchSize = 3
for i := 0; i < len(persons)/batchSize+1; i++ {
	low := i * batchSize
	high := (i + 1) * batchSize
	if high > len(persons) {
		high = len(persons)
	}
	batch := persons[low:high]

	if err := DB.InsertMulti(batch...); err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Inserted %d persons\n", len(batch))
}

fmt.Println(persons[0].(*Person).ID, persons[0].(*Person).Name)
Inserted 3 persons
Inserted 2 persons
0 Alexey Palazhchenko

func (*Querier) NextRow

func (q *Querier) NextRow(str Struct, rows *sql.Rows) error

NextRow scans next result row from rows to str. If str implements AfterFinder, it also calls AfterFind(). It is caller's responsibility to call rows.Close().

If there is no next result row, it returns ErrNoRows. It also may return rows.Err(), rows.Scan() and AfterFinder errors.

See SelectRows example for idiomatic usage.

func (*Querier) QualifiedColumns

func (q *Querier) QualifiedColumns(view View) []string

QualifiedColumns returns a slice of quoted qualified column names for given view.

func (*Querier) QualifiedView

func (q *Querier) QualifiedView(view View) string

QualifiedView returns quoted qualified view name.

func (*Querier) Query

func (q *Querier) Query(query string, args ...interface{}) (*sql.Rows, error)

Query executes a query that returns rows, typically a SELECT. The args are for any placeholder parameters in the query.

Example

Code:

columns := DB.QualifiedColumns(PersonTable)
columns = append(columns, DB.QualifiedColumns(PersonProjectView)...)
columns = append(columns, DB.QualifiedColumns(ProjectTable)...)
query := fmt.Sprintf(`
		SELECT %s
			FROM people
			INNER JOIN person_project ON people.id = person_project.person_id
			INNER JOIN projects ON person_project.project_id = projects.id
			ORDER BY person_id, project_id;
	`, strings.Join(columns, ", "))
rows, err := DB.Query(query)
if err != nil {
	log.Fatal(err)
}
defer rows.Close()

for rows.Next() {
	var person Person
	var personProject PersonProject
	var project Project
	pointers := person.Pointers()
	pointers = append(pointers, personProject.Pointers()...)
	pointers = append(pointers, project.Pointers()...)
	if err = rows.Scan(pointers...); err != nil {
		log.Print(err)
	}
	if err = person.AfterFind(); err != nil {
		log.Fatal(err)
	}
	if err = project.AfterFind(); err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s - %s\n", person.Name, project.Name)
}
if err = rows.Err(); err != nil {
	log.Fatal(err)
}
Noble Schumm - Vicious Baron
Elfrieda Abbott - Vicious Baron
Elfrieda Abbott - Thirsty Queen
Elfrieda Abbott - Vicious Baron
Elfrieda Abbott - Thirsty Queen
Elfrieda Abbott - Kosher Traveler

func (*Querier) QueryContext

func (q *Querier) QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)

QueryContext just calls q.WithContext(ctx).Query(query, args...), and that form should be used instead. This method exists to satisfy various standard interfaces for advanced use-cases.

func (*Querier) QueryRow

func (q *Querier) QueryRow(query string, args ...interface{}) *sql.Row

QueryRow executes a query that is expected to return at most one row. QueryRow always returns a non-nil value. Errors are deferred until Row's Scan method is called.

func (*Querier) QueryRowContext

func (q *Querier) QueryRowContext(ctx context.Context, query string, args ...interface{}) *sql.Row

QueryRowContext just calls q.WithContext(ctx).QueryRow(query, args...), and that form should be used instead. This method exists to satisfy various standard interfaces for advanced use-cases.

func (*Querier) Reload

func (q *Querier) Reload(record Record) error

Reload is a shortcut for FindByPrimaryKeyTo for given record.

func (*Querier) Save

func (q *Querier) Save(record Record) error

Save saves record in SQL database table. If primary key is set, it first calls Update and checks if row was affected (matched). If primary key is absent or no row was affected, it calls Insert. This allows to call Save with Record with primary key set.

func (*Querier) SelectAllFrom

func (q *Querier) SelectAllFrom(view View, tail string, args ...interface{}) (structs []Struct, err error)

SelectAllFrom queries view with tail and args and returns a slice of new Structs. If view's Struct implements AfterFinder, it also calls AfterFind().

In case of query error slice will be nil. If error is encountered during iteration, partial result and error will be returned. Error is never ErrNoRows.

func (*Querier) SelectOneFrom

func (q *Querier) SelectOneFrom(view View, tail string, args ...interface{}) (Struct, error)

SelectOneFrom queries view with tail and args and scans first result to new Struct str. If str implements AfterFinder, it also calls AfterFind().

If there are no rows in result, it returns nil, ErrNoRows. It also may return QueryRow(), Scan() and AfterFinder errors.

func (*Querier) SelectOneTo

func (q *Querier) SelectOneTo(str Struct, tail string, args ...interface{}) error

SelectOneTo queries str's View with tail and args and scans first result to str. If str implements AfterFinder, it also calls AfterFind().

If there are no rows in result, it returns ErrNoRows. It also may return QueryRow(), Scan() and AfterFinder errors.

Example

Code:

var person Person
tail := fmt.Sprintf("WHERE created_at < %s ORDER BY id", DB.Placeholder(1))
y2010 := time.Date(2010, 1, 1, 0, 0, 0, 0, time.UTC)
if err := DB.SelectOneTo(&person, tail, y2010); err != nil {
	log.Fatal(err)
}
fmt.Println(person)
ID: 1 (int32), GroupID: 65534 (*int32), Name: `Denis Mills` (string), Email: <nil> (*string), CreatedAt: 2009-11-10 23:00:00 +0000 UTC (time.Time), UpdatedAt: <nil> (*time.Time)

func (*Querier) SelectRows

func (q *Querier) SelectRows(view View, tail string, args ...interface{}) (*sql.Rows, error)

SelectRows queries view with tail and args and returns rows. They can then be iterated with NextRow(). It is caller's responsibility to call rows.Close().

In case of error rows will be nil. Error is never ErrNoRows.

See example for idiomatic usage.

Example

Code:

tail := fmt.Sprintf("WHERE created_at < %s ORDER BY id", DB.Placeholder(1))
y2010 := time.Date(2010, 1, 1, 0, 0, 0, 0, time.UTC)
rows, err := DB.SelectRows(PersonTable, tail, y2010)
if err != nil {
	log.Fatal(err)
}
defer rows.Close()

for {
	var person Person
	if err = DB.NextRow(&person, rows); err != nil {
		break
	}
	fmt.Println(person)
}
if err != reform.ErrNoRows {
	log.Fatal(err)
}
ID: 1 (int32), GroupID: 65534 (*int32), Name: `Denis Mills` (string), Email: <nil> (*string), CreatedAt: 2009-11-10 23:00:00 +0000 UTC (time.Time), UpdatedAt: <nil> (*time.Time)
ID: 2 (int32), GroupID: 65534 (*int32), Name: `Garrick Muller` (string), Email: `muller_garrick@example.com` (*string), CreatedAt: 2009-12-12 12:34:56 +0000 UTC (time.Time), UpdatedAt: <nil> (*time.Time)

func (*Querier) Tag

func (q *Querier) Tag() string

Tag returns Querier's tag. Default tag is empty.

func (*Querier) Update

func (q *Querier) Update(record Record) error

Update updates all columns of row specified by primary key in SQL database table with given record. If record implements BeforeUpdater, it calls BeforeUpdate() before doing so.

Method returns ErrNoRows if no rows were updated. Method returns ErrNoPK if primary key is not set.

func (*Querier) UpdateColumns

func (q *Querier) UpdateColumns(record Record, columns ...string) error

UpdateColumns updates specified columns of row specified by primary key in SQL database table with given record. Other columns are omitted from generated UPDATE statement. If record implements BeforeUpdater, it calls BeforeUpdate() before doing so.

Method returns ErrNoRows if no rows were updated. Method returns ErrNoPK if primary key is not set.

func (*Querier) UpdateView

func (q *Querier) UpdateView(str Struct, columns []string, tail string, args ...interface{}) (uint, error)

UpdateView updates specified columns of rows specified by tail and args in SQL database table with given struct, and returns a number of updated rows. Other columns are omitted from generated UPDATE statement. If struct implements BeforeUpdater, it calls BeforeUpdate() before doing so.

Method never returns ErrNoRows.

func (*Querier) WithContext

func (q *Querier) WithContext(ctx context.Context) *Querier

WithContext returns a copy of Querier with set context. Returned Querier is tied to the same DB or TX. See Context section in documentation for details.

Example

Code:

ctx, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()
_, _ = DB.WithContext(ctx).SelectAllFrom(ProjectTable, "")

func (*Querier) WithTag

func (q *Querier) WithTag(format string, args ...interface{}) *Querier

WithTag returns a copy of Querier with set tag. Returned Querier is tied to the same DB or TX. See Tagging section in documentation for details.

Example

Code:

id := "baron"
_, _ = DB.WithTag("GetProject:%v", id).FindByPrimaryKeyFrom(ProjectTable, id)

type Record

type Record interface {
	Struct

	// Table returns Table object for that record.
	Table() Table

	// PKValue returns a value of primary key for that record.
	// Returned interface{} value is never untyped nil.
	PKValue() interface{}

	// PKPointer returns a pointer to primary key field for that record.
	// Returned interface{} value is never untyped nil.
	PKPointer() interface{}

	// HasPK returns true if record has non-zero primary key set, false otherwise.
	HasPK() bool

	// SetPK sets record primary key.
	SetPK(pk interface{})
}

Record represents a row in SQL database table with single-column primary key.

type SelectLimitMethod

type SelectLimitMethod int

SelectLimitMethod is a method of limiting the number of rows in a query result.

const (
	// Limit is a method using "LIMIT N" SQL syntax.
	Limit SelectLimitMethod = iota

	// SelectTop is a method using "SELECT TOP N" SQL syntax.
	SelectTop
)

type Struct

type Struct interface {
	// String returns a string representation of this struct or record.
	String() string

	// Values returns a slice of struct or record field values.
	// Returned interface{} values are never untyped nils.
	Values() []interface{}

	// Pointers returns a slice of pointers to struct or record fields.
	// Returned interface{} values are never untyped nils.
	Pointers() []interface{}

	// View returns View object for that struct.
	View() View
}

Struct represents a row in SQL database view or table.

type TX

type TX struct {
	*Querier
	// contains filtered or unexported fields
}

TX represents a SQL database transaction.

func NewTX

func NewTX(tx *sql.Tx, dialect Dialect, logger Logger) *TX

NewTX creates new TX object for given SQL database transaction. Logger can be nil.

func NewTXFromInterface

func NewTXFromInterface(tx TXInterface, dialect Dialect, logger Logger) *TX

NewTXFromInterface creates new TX object for given TXInterface. Can be used for easier integration with existing code or for passing test doubles. Logger can be nil.

func (*TX) Commit

func (tx *TX) Commit() error

Commit commits the transaction.

func (*TX) Rollback

func (tx *TX) Rollback() error

Rollback aborts the transaction.

type TXInterface

type TXInterface interface {
	DBTXContext
	Commit() error
	Rollback() error

	// Deprecated: do not use, it will be removed in v1.5.
	DBTX
}

TXInterface is a subset of *sql.Tx used by reform. Can be used together with NewTXFromInterface for easier integration with existing code or for passing test doubles.

It may grow and shrink over time to include only needed *sql.Tx methods, and is excluded from SemVer compatibility guarantees.

type Table

type Table interface {
	View

	// NewRecord makes a new record for that table.
	NewRecord() Record

	// PKColumnIndex returns an index of primary key column for that table in SQL database.
	PKColumnIndex() uint
}

Table represents SQL database table with single-column primary key. It extends View.

type View

type View interface {
	// Schema returns a schema name in SQL database.
	Schema() string

	// Name returns a view or table name in SQL database.
	Name() string

	// Columns returns a new slice of column names for that view or table in SQL database.
	Columns() []string

	// NewStruct makes a new struct for that view or table.
	NewStruct() Struct
}

View represents SQL database view or table.

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier