reform

package module
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Jul 1, 2016 License: MIT Imports: 5 Imported by: 0

README

reform GoDoc Build Status Coverage Status Go Report Card

A better ORM for Go and database/sql.

It uses non-empty interfaces, code generation (go generate), and initialization-time reflection as opposed to interface{}, type system sidestepping, and runtime reflection. It will be kept simple.

Quickstart

  1. Make sure you are using Go 1.6+.

  2. Install it: go get gopkg.in/reform.v1/reform (see about versioning below)

  3. Define your first model in file person.go:

    //go:generate reform

//reform:people
Person struct {
	ID        int32      `reform:"id,pk"`
	Name      string     `reform:"name"`
	Email     *string    `reform:"email"`
	CreatedAt time.Time  `reform:"created_at"`
	UpdatedAt *time.Time `reform:"updated_at"`
}

    Magic comment //reform:people links this model to people table or view in SQL database. First value in reform tag is a column name. pk marks primary key. Use pointers for nullable fields.

  4. Run reform [package or directory] or go generate [package or file]. This will create person_reform.go in the same package with type PersonTable and methods on Person.

  5. See documentation how to use it. Simple example:

    // Use reform.NewDB to create DB.

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

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

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

// Find records by IDs.
persons, err := DB.FindAllFrom(PersonTable, "id", 1, 2)
if err != nil {
	log.Fatal(err)
}
for _, p := range persons {
	fmt.Println(p)
}

Background

reform was born during summer 2014 out of frustrations with existing Go ORMs. All of them have a method Save(record interface{}) which can be used like this:

orm.Save(User{Name: "gopher"})
orm.Save(&User{Name: "gopher"})
orm.Save(nil)
orm.Save("Batman!!")

Now you can say that last invocation is obviously invalid, and that it's not hard to make an ORM to accept both first and second versions. But there are two problems:

  1. Compiler can't check it. Method's signature in godoc will not tell us how to use it. We are essentially working against those tools by sidestepping type system.
  2. First version is still invalid, since one would expect Save() method to set record's primary key after INSERT, but this change will be lost due to passing by value.

First proprietary version of reform was used in production even before go generate announcement. This free and open-source version is the fourth milestone on the road to better and idiomatic API.

Versioning policy

We are following Semantic Versioning, using gopkg.in and filling a changelog.

We use branch v1-stable (default on Github) for v1 development and tags v1.Y.Z for releases. All v1 releases are SemVer-compatible, breaking changes will not be applied. Canonical import path is gopkg.in/reform.v1. go get -u gopkg.in/reform.v1 will install latest released version. To install not yet released v1 version one can do checkout manually while preserving import path:

go get -u gopkg.in/reform.v1
cd $GOPATH/gopkg.in/reform.v1
git checkout origin/v1-stable

Branch v2-unstable is used for v2 development. It doesn't have any releases yet, and no compatibility is guaranteed. Canonical import path is gopkg.in/reform.v2-unstable.

Additional packages

Caveats

  • There should be zero pk fields for Struct and exactly one pk field for Record.
  • pk field can't be a pointer (== nil doesn't work).
  • Database row can't have a Go's zero value (0, empty string, etc.) in primary key column.

Documentation

Overview

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

Example 
// Use reform.NewDB to create DB.

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

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

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

// Find records by IDs.
persons, err := DB.FindAllFrom(PersonTable, "id", 1, 2)
if err != nil {
	log.Fatal(err)
}
for _, p := range persons {
	fmt.Println(p)
}

Output:

Alexey Palazhchenko
ID: 1 (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), 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

Constants

This section is empty.

Variables

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

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

Functions

func Inspect 

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

Inspect returns suitable for logging representation of a query argument.

Types

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.

Example 
// Get *sql.DB as usual. PostgreSQL example:
conn, err := sql.Open("postgres", "postgres://localhost:5432/reform-test?sslmode=disable")
if err != nil {
	log.Fatal(err)
}

// Use new *log.Logger for logging.
logger := log.New(os.Stderr, "SQL: ", log.Flags())

// Create *reform.DB instance with simple logger.
// Any Printf-like function (fmt.Printf, log.Printf, testing.T.Logf, etc) can be used with NewPrintfLogger.
// Change dialect for other databases.
_ = reform.NewDB(conn, postgresql.Dialect, reform.NewPrintfLogger(logger.Printf))

Output:

func NewDBFromInterface added in v1.1.0 

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.

func (*DB) Begin 

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

Begin starts a transaction.

func (*DB) InTransaction 

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

InTransaction wraps function execution in transaction, rolling back it in case of error or panic, committing otherwise.

type DBInterface added in v1.1.0 

type DBInterface interface {
	DBTX
	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.

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.
	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 Dialect 

type Dialect interface {
	// 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
}

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
)

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, a ...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) 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) 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 ideomatic 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) InsertMulti added in v1.1.0 

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 
// 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]

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

// note that ID is not filled
fmt.Println(persons[0].(*Person).ID, persons[0].(*Person).Name)

Output:

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.Next(), rows.Scan() and AfterFinder errors.

See SelectRows example for ideomatic 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.

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) 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 updated. If primary key is absent or no row was updated, it calls Insert.

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 
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)
err := DB.SelectOneTo(&person, tail, y2010)
if err != nil {
	log.Fatal(err)
}
fmt.Println(person)

Output:

ID: 1 (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 ideomatic usage.

Example 
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
	err = DB.NextRow(&person, rows)
	if err != nil {
		break
	}
	fmt.Println(person)
}
if err != reform.ErrNoRows {
	log.Fatal(err)
}

Output:

ID: 1 (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), 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) 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. 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.

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 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.

func NewTXFromInterface added in v1.1.0 

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.

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 added in v1.1.0 

type TXInterface interface {
	DBTX
	Commit() error
	Rollback() error
}

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.

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.

Source Files

View all Source files

Directories

Path Synopsis
dialects
mysql
Package mysql implements reform.Dialect for MySQL.
 Package mysql implements reform.Dialect for MySQL.
postgresql
Package postgresql implements reform.Dialect for PostgreSQL.
 Package postgresql implements reform.Dialect for PostgreSQL.
sqlite3
Package sqlite3 implements reform.Dialect for SQLite3.
 Package sqlite3 implements reform.Dialect for SQLite3.
internal
test
test/models
test/models/bogus
Package parse implements parsing of Go structs in files and runtime.
 Package parse implements parsing of Go structs in files and runtime.

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.