README
PostgreSQL client and ORM for Golang
❤️ Uptrace.dev - distributed traces, logs, and errors in one place
- Join Discord to ask questions.
- Documentation
- Reference
- Examples
- Example projects:
- GraphQL Tutorial on YouTube.
Ecosystem
- Migrations by vmihailenco and robinjoseph08.
- Genna - cli tool for generating go-pg models.
- urlstruct to decode
url.Values
into structs. - Sharding.
- go-pg-monitor - Prometheus metrics based on go-pg client stats.
Features
- Basic types: integers, floats, string, bool, time.Time, net.IP, net.IPNet.
- sql.NullBool, sql.NullString, sql.NullInt64, sql.NullFloat64 and pg.NullTime.
- sql.Scanner and sql/driver.Valuer interfaces.
- Structs, maps and arrays are marshalled as JSON by default.
- PostgreSQL multidimensional Arrays using array tag and Array wrapper.
- Hstore using hstore tag and Hstore wrapper.
- Composite types.
- All struct fields are nullable by default and zero values (empty string, 0, zero time, empty map
or slice, nil ptr) are marshalled as SQL
NULL
.pg:",notnull"
is used to add SQLNOT NULL
constraint andpg:",use_zero"
to allow Go zero values. - Transactions.
- Prepared statements.
- Notifications using
LISTEN
andNOTIFY
. - Copying data using
COPY FROM
andCOPY TO
. - Timeouts and canceling queries using context.Context.
- Automatic connection pooling with circuit breaker support.
- Queries retry on network errors.
- Working with models using ORM and SQL.
- Scanning variables using ORM and SQL.
- SelectOrInsert using on-conflict.
- INSERT ... ON CONFLICT DO UPDATE using ORM.
- Bulk/batch inserts, updates, and deletes.
- Common table expressions using WITH and WrapWith.
- CountEstimate
using
EXPLAIN
to get estimated number of matching rows. - ORM supports has one, belongs to, has many, and many to many with composite/multi-column primary keys.
- Soft deletes.
- Creating tables from structs.
- ForEach that calls a function for each row returned by the query without loading all rows into the memory.
- Works with PgBouncer in transaction pooling mode.
Installation
go-pg supports 2 last Go versions and requires a Go version with modules support. So make sure to initialize a Go module:
go mod init github.com/my/repo
And then install go-pg (note v10 in the import; omitting it is a popular mistake):
go get github.com/go-pg/pg/v10
Quickstart
package pg_test
import (
"fmt"
"github.com/go-pg/pg/v10"
"github.com/go-pg/pg/v10/orm"
)
type User struct {
Id int64
Name string
Emails []string
}
func (u User) String() string {
return fmt.Sprintf("User<%d %s %v>", u.Id, u.Name, u.Emails)
}
type Story struct {
Id int64
Title string
AuthorId int64
Author *User `pg:"rel:has-one"`
}
func (s Story) String() string {
return fmt.Sprintf("Story<%d %s %s>", s.Id, s.Title, s.Author)
}
func ExampleDB_Model() {
db := pg.Connect(&pg.Options{
User: "postgres",
})
defer db.Close()
err := createSchema(db)
if err != nil {
panic(err)
}
user1 := &User{
Name: "admin",
Emails: []string{"admin1@admin", "admin2@admin"},
}
_, err = db.Model(user1).Insert()
if err != nil {
panic(err)
}
_, err = db.Model(&User{
Name: "root",
Emails: []string{"root1@root", "root2@root"},
}).Insert()
if err != nil {
panic(err)
}
story1 := &Story{
Title: "Cool story",
AuthorId: user1.Id,
}
_, err = db.Model(story1).Insert()
if err != nil {
panic(err)
}
// Select user by primary key.
user := &User{Id: user1.Id}
err = db.Model(user).WherePK().Select()
if err != nil {
panic(err)
}
// Select all users.
var users []User
err = db.Model(&users).Select()
if err != nil {
panic(err)
}
// Select story and associated author in one query.
story := new(Story)
err = db.Model(story).
Relation("Author").
Where("story.id = ?", story1.Id).
Select()
if err != nil {
panic(err)
}
fmt.Println(user)
fmt.Println(users)
fmt.Println(story)
// Output: User<1 admin [admin1@admin admin2@admin]>
// [User<1 admin [admin1@admin admin2@admin]> User<2 root [root1@root root2@root]>]
// Story<1 Cool story User<1 admin [admin1@admin admin2@admin]>>
}
// createSchema creates database schema for User and Story models.
func createSchema(db *pg.DB) error {
models := []interface{}{
(*User)(nil),
(*Story)(nil),
}
for _, model := range models {
err := db.Model(model).CreateTable(&orm.CreateTableOptions{
Temp: true,
})
if err != nil {
return err
}
}
return nil
}
See also
Documentation
Overview ¶
pg provides PostgreSQL client.
Example (Placeholders) ¶
go-pg recognizes `?` in queries as placeholders and replaces them with parameters when queries are executed. `?` can be escaped with backslash. Parameters are escaped before replacing according to PostgreSQL rules. Specifically:
- all parameters are properly quoted against SQL injections; - null byte is removed; - JSON/JSONB gets `\u0000` escaped as `\\u0000`.
Output: simple: 42 indexed: 2 named: 4 global: 3 table name: "params" table alias: "params" table columns: "params"."x", "params"."y" columns: "x", "y"
Index ¶
- Variables
- func Array(v interface{}) *types.Array
- func Hstore(v interface{}) *types.Hstore
- func In(slice interface{}) types.ValueAppender
- func InMulti(values ...interface{}) types.ValueAppender
- func Model(model ...interface{}) *orm.Query
- func ModelContext(c context.Context, model ...interface{}) *orm.Query
- func SafeQuery(query string, params ...interface{}) *orm.SafeQueryAppender
- func Scan(values ...interface{}) orm.ColumnScanner
- func SetLogger(logger internal.Logging)
- type AfterDeleteHook
- type AfterInsertHook
- type AfterScanHook
- type AfterSelectHook
- type AfterUpdateHook
- type BeforeDeleteHook
- type BeforeInsertHook
- type BeforeScanHook
- type BeforeUpdateHook
- type Conn
- func (db Conn) AddQueryHook(hook QueryHook)
- func (db Conn) Begin() (*Tx, error)
- func (db Conn) BeginContext(ctx context.Context) (*Tx, error)
- func (db Conn) Close() error
- func (db *Conn) Context() context.Context
- func (db Conn) CopyFrom(r io.Reader, query interface{}, params ...interface{}) (res Result, err error)
- func (db Conn) CopyTo(w io.Writer, query interface{}, params ...interface{}) (res Result, err error)
- func (db Conn) Exec(query interface{}, params ...interface{}) (res Result, err error)
- func (db Conn) ExecContext(c context.Context, query interface{}, params ...interface{}) (Result, error)
- func (db Conn) ExecOne(query interface{}, params ...interface{}) (Result, error)
- func (db Conn) ExecOneContext(ctx context.Context, query interface{}, params ...interface{}) (Result, error)
- func (db Conn) Formatter() orm.QueryFormatter
- func (db Conn) Model(model ...interface{}) *orm.Query
- func (db Conn) ModelContext(c context.Context, model ...interface{}) *orm.Query
- func (db Conn) Param(param string) interface{}
- func (db Conn) Ping(ctx context.Context) error
- func (db Conn) PoolStats() *PoolStats
- func (db Conn) Prepare(q string) (*Stmt, error)
- func (db Conn) Query(model, query interface{}, params ...interface{}) (res Result, err error)
- func (db Conn) QueryContext(c context.Context, model, query interface{}, params ...interface{}) (Result, error)
- func (db Conn) QueryOne(model, query interface{}, params ...interface{}) (Result, error)
- func (db Conn) QueryOneContext(ctx context.Context, model, query interface{}, params ...interface{}) (Result, error)
- func (db Conn) RunInTransaction(ctx context.Context, fn func(*Tx) error) error
- func (db *Conn) WithContext(ctx context.Context) *Conn
- func (db *Conn) WithParam(param string, value interface{}) *Conn
- func (db *Conn) WithTimeout(d time.Duration) *Conn
- type DB
- func (db DB) AddQueryHook(hook QueryHook)
- func (db DB) Begin() (*Tx, error)
- func (db DB) BeginContext(ctx context.Context) (*Tx, error)
- func (db DB) Close() error
- func (db *DB) Conn() *Conn
- func (db *DB) Context() context.Context
- func (db DB) CopyFrom(r io.Reader, query interface{}, params ...interface{}) (res Result, err error)
- func (db DB) CopyTo(w io.Writer, query interface{}, params ...interface{}) (res Result, err error)
- func (db DB) Exec(query interface{}, params ...interface{}) (res Result, err error)
- func (db DB) ExecContext(c context.Context, query interface{}, params ...interface{}) (Result, error)
- func (db DB) ExecOne(query interface{}, params ...interface{}) (Result, error)
- func (db DB) ExecOneContext(ctx context.Context, query interface{}, params ...interface{}) (Result, error)
- func (db DB) Formatter() orm.QueryFormatter
- func (db *DB) Listen(ctx context.Context, channels ...string) *Listener
- func (db DB) Model(model ...interface{}) *orm.Query
- func (db DB) ModelContext(c context.Context, model ...interface{}) *orm.Query
- func (db *DB) Options() *Options
- func (db DB) Param(param string) interface{}
- func (db DB) Ping(ctx context.Context) error
- func (db DB) PoolStats() *PoolStats
- func (db DB) Prepare(q string) (*Stmt, error)
- func (db DB) Query(model, query interface{}, params ...interface{}) (res Result, err error)
- func (db DB) QueryContext(c context.Context, model, query interface{}, params ...interface{}) (Result, error)
- func (db DB) QueryOne(model, query interface{}, params ...interface{}) (Result, error)
- func (db DB) QueryOneContext(ctx context.Context, model, query interface{}, params ...interface{}) (Result, error)
- func (db DB) RunInTransaction(ctx context.Context, fn func(*Tx) error) error
- func (db *DB) String() string
- func (db *DB) WithContext(ctx context.Context) *DB
- func (db *DB) WithParam(param string, value interface{}) *DB
- func (db *DB) WithTimeout(d time.Duration) *DB
- type Error
- type Ident
- type IntSet
- type Ints
- type Listener
- func (ln *Listener) Channel() <-chan Notification
- func (ln *Listener) ChannelSize(size int) <-chan Notification
- func (ln *Listener) Close() error
- func (ln *Listener) Listen(ctx context.Context, channels ...string) error
- func (ln *Listener) Receive(ctx context.Context) (channel string, payload string, err error)
- func (ln *Listener) ReceiveTimeout(ctx context.Context, timeout time.Duration) (channel, payload string, err error)
- func (ln *Listener) String() string
- func (ln *Listener) Unlisten(ctx context.Context, channels ...string) error
- type Notification
- type NullTime
- type Options
- type PoolStats
- type QueryEvent
- type QueryHook
- type Result
- type Safe
- type Stmt
- func (stmt *Stmt) Close() error
- func (stmt *Stmt) Exec(params ...interface{}) (Result, error)
- func (stmt *Stmt) ExecContext(c context.Context, params ...interface{}) (Result, error)
- func (stmt *Stmt) ExecOne(params ...interface{}) (Result, error)
- func (stmt *Stmt) ExecOneContext(c context.Context, params ...interface{}) (Result, error)
- func (stmt *Stmt) Query(model interface{}, params ...interface{}) (Result, error)
- func (stmt *Stmt) QueryContext(c context.Context, model interface{}, params ...interface{}) (Result, error)
- func (stmt *Stmt) QueryOne(model interface{}, params ...interface{}) (Result, error)
- func (stmt *Stmt) QueryOneContext(c context.Context, model interface{}, params ...interface{}) (Result, error)
- type Strings
- func (Strings) AddColumnScanner(_ orm.ColumnScanner) error
- func (strings Strings) AppendValue(dst []byte, quote int) ([]byte, error)
- func (strings *Strings) Init() error
- func (strings *Strings) NextColumnScanner() orm.ColumnScanner
- func (strings *Strings) ScanColumn(col types.ColumnInfo, rd types.Reader, n int) error
- type Tx
- func (tx *Tx) Begin() (*Tx, error)
- func (tx *Tx) Close() error
- func (tx *Tx) CloseContext(ctx context.Context) error
- func (tx *Tx) Commit() error
- func (tx *Tx) CommitContext(ctx context.Context) error
- func (tx *Tx) Context() context.Context
- func (tx *Tx) CopyFrom(r io.Reader, query interface{}, params ...interface{}) (res Result, err error)
- func (tx *Tx) CopyTo(w io.Writer, query interface{}, params ...interface{}) (res Result, err error)
- func (tx *Tx) Exec(query interface{}, params ...interface{}) (Result, error)
- func (tx *Tx) ExecContext(c context.Context, query interface{}, params ...interface{}) (Result, error)
- func (tx *Tx) ExecOne(query interface{}, params ...interface{}) (Result, error)
- func (tx *Tx) ExecOneContext(c context.Context, query interface{}, params ...interface{}) (Result, error)
- func (tx *Tx) Formatter() orm.QueryFormatter
- func (tx *Tx) Model(model ...interface{}) *orm.Query
- func (tx *Tx) ModelContext(c context.Context, model ...interface{}) *orm.Query
- func (tx *Tx) Prepare(q string) (*Stmt, error)
- func (tx *Tx) Query(model interface{}, query interface{}, params ...interface{}) (Result, error)
- func (tx *Tx) QueryContext(c context.Context, model interface{}, query interface{}, params ...interface{}) (Result, error)
- func (tx *Tx) QueryOne(model interface{}, query interface{}, params ...interface{}) (Result, error)
- func (tx *Tx) QueryOneContext(c context.Context, model interface{}, query interface{}, params ...interface{}) (Result, error)
- func (tx *Tx) Rollback() error
- func (tx *Tx) RollbackContext(ctx context.Context) error
- func (tx *Tx) RunInTransaction(ctx context.Context, fn func(*Tx) error) error
- func (tx *Tx) Stmt(stmt *Stmt) *Stmt
Examples ¶
- Package (Placeholders)
- Array
- Connect
- DB (ArrayValueScanner)
- DB (JsonUseNumber)
- DB.Begin
- DB.CopyFrom
- DB.Exec
- DB.Model
- DB.Model (BelongsTo)
- DB.Model (BulkDelete)
- DB.Model (BulkInsert)
- DB.Model (BulkInsertSlice)
- DB.Model (BulkUpdate)
- DB.Model (BulkUpdateSlice)
- DB.Model (CompositeType)
- DB.Model (Count)
- DB.Model (CountEstimate)
- DB.Model (CreateTable)
- DB.Model (CustomType)
- DB.Model (Delete)
- DB.Model (DeleteMultipleRows)
- DB.Model (DiscardUnknownColumns)
- DB.Model (Exists)
- DB.Model (ForEach)
- DB.Model (HasMany)
- DB.Model (HasManySelf)
- DB.Model (HasOne)
- DB.Model (HstoreStructTag)
- DB.Model (Insert)
- DB.Model (InsertDynamicTableName)
- DB.Model (InsertOnConflictDoNothing)
- DB.Model (InsertOnConflictDoUpdate)
- DB.Model (ManyToMany)
- DB.Model (ManyToManySelf)
- DB.Model (NullEmptyValue)
- DB.Model (PostgresArrayStructTag)
- DB.Model (Select)
- DB.Model (SelectAllColumns)
- DB.Model (SelectAndCount)
- DB.Model (SelectApplyFunc)
- DB.Model (SelectFirstRow)
- DB.Model (SelectGroupBy)
- DB.Model (SelectLastRow)
- DB.Model (SelectOrInsert)
- DB.Model (SelectSQLExpression)
- DB.Model (SelectSomeColumns)
- DB.Model (SelectSomeColumnsIntoVars)
- DB.Model (SelectWhereGroup)
- DB.Model (SelectWhereIn)
- DB.Model (SelectWith)
- DB.Model (SelectWrapWith)
- DB.Model (SoftDelete)
- DB.Model (SoftDeleteCustom)
- DB.Model (Update)
- DB.Model (UpdateNotZero)
- DB.Model (UpdateSetValues)
- DB.Model (UpdateSomeColumns)
- DB.Model (UpdateSomeColumns2)
- DB.Model (UpdateUseZeroBool)
- DB.Prepare
- DB.Query
- DB.QueryOne
- DB.QueryOne (Returning_id)
- DB.RunInTransaction
- DB.WithTimeout
- Error
- Hstore
- Ident
- Ints
- Listener
- Safe
- Scan
- Strings
Constants ¶
Variables ¶
var Discard orm.Discard
Discard is used with Query and QueryOne to discard rows.
var ErrMultiRows = internal.ErrMultiRows
ErrMultiRows is returned by QueryOne and ExecOne when query returned multiple rows but exactly one row is expected.
var ErrNoRows = internal.ErrNoRows
ErrNoRows is returned by QueryOne and ExecOne when query returned zero rows but at least one row is expected.
var ErrTxDone = errors.New("pg: transaction has already been committed or rolled back")
ErrTxDone is returned by any operation that is performed on a transaction that has already been committed or rolled back.
Functions ¶
func Array ¶
Array accepts a slice and returns a wrapper for working with PostgreSQL array data type.
For struct fields you can use array tag:
Emails []string `pg:",array"`
Example ¶
Output: [one@example.com two@example.com]
func Hstore ¶
Hstore accepts a map and returns a wrapper for working with hstore data type. Supported map types are:
- map[string]string
For struct fields you can use hstore tag:
Attrs map[string]string `pg:",hstore"`
Example ¶
Output: map[hello:world]
func In ¶
func In(slice interface{}) types.ValueAppender
In accepts a slice and returns a wrapper that can be used with PostgreSQL IN operator:
Where("id IN (?)", pg.In([]int{1, 2, 3, 4}))
produces
WHERE id IN (1, 2, 3, 4)
func InMulti ¶
func InMulti(values ...interface{}) types.ValueAppender
InMulti accepts multiple values and returns a wrapper that can be used with PostgreSQL IN operator:
Where("(id1, id2) IN (?)", pg.InMulti([]int{1, 2}, []int{3, 4}))
produces
WHERE (id1, id2) IN ((1, 2), (3, 4))
func ModelContext ¶
ModelContext returns a new query for the optional model with a context.
func SafeQuery ¶
func SafeQuery(query string, params ...interface{}) *orm.SafeQueryAppender
SafeQuery replaces any placeholders found in the query.
func Scan ¶
func Scan(values ...interface{}) orm.ColumnScanner
Scan returns ColumnScanner that copies the columns in the row into the values.
Example ¶
Output: foo bar
Types ¶
type AfterDeleteHook ¶
type AfterDeleteHook = orm.AfterDeleteHook
type AfterInsertHook ¶
type AfterInsertHook = orm.AfterInsertHook
type AfterScanHook ¶
type AfterScanHook = orm.AfterScanHook
type AfterSelectHook ¶
type AfterSelectHook = orm.AfterSelectHook
type AfterUpdateHook ¶
type AfterUpdateHook = orm.AfterUpdateHook
type BeforeDeleteHook ¶
type BeforeDeleteHook = orm.BeforeDeleteHook
type BeforeInsertHook ¶
type BeforeInsertHook = orm.BeforeInsertHook
type BeforeScanHook ¶
type BeforeScanHook = orm.BeforeScanHook
type BeforeUpdateHook ¶
type BeforeUpdateHook = orm.BeforeUpdateHook
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
Conn represents a single database connection rather than a pool of database connections. Prefer running queries from DB unless there is a specific need for a continuous single database connection.
A Conn must call Close to return the connection to the database pool and may do so concurrently with a running query.
After a call to Close, all operations on the connection fail.
func (Conn) AddQueryHook ¶
func (db Conn) AddQueryHook(hook QueryHook)
AddQueryHook adds a hook into query processing.
func (Conn) Close ¶
func (db Conn) Close() error
Close closes the database client, releasing any open resources.
It is rare to Close a DB, as the DB handle is meant to be long-lived and shared between many goroutines.
func (Conn) CopyFrom ¶
func (db Conn) CopyFrom(r io.Reader, query interface{}, params ...interface{}) (res Result, err error)
CopyFrom copies data from reader to a table.
func (Conn) CopyTo ¶
func (db Conn) CopyTo(w io.Writer, query interface{}, params ...interface{}) (res Result, err error)
CopyTo copies data from a table to writer.
func (Conn) Exec ¶
Exec executes a query ignoring returned rows. The params are for any placeholders in the query.
func (Conn) ExecContext ¶
func (Conn) ExecOne ¶
ExecOne acts like Exec, but query must affect only one row. It returns ErrNoRows error when query returns zero rows or ErrMultiRows when query returns multiple rows.
func (Conn) ExecOneContext ¶
func (Conn) Formatter ¶
func (db Conn) Formatter() orm.QueryFormatter
func (Conn) ModelContext ¶
func (Conn) Param ¶
func (db Conn) Param(param string) interface{}
Param returns value for the param.
func (Conn) Ping ¶
Ping verifies a connection to the database is still alive, establishing a connection if necessary.
func (Conn) PoolStats ¶
func (db Conn) PoolStats() *PoolStats
PoolStats returns connection pool stats.
func (Conn) Prepare ¶
Prepare creates a prepared statement for later queries or executions. Multiple queries or executions may be run concurrently from the returned statement.
func (Conn) Query ¶
Query executes a query that returns rows, typically a SELECT. The params are for any placeholders in the query.
func (Conn) QueryContext ¶
func (Conn) QueryOne ¶
QueryOne acts like Query, but query must return only one row. It returns ErrNoRows error when query returns zero rows or ErrMultiRows when query returns multiple rows.
func (Conn) QueryOneContext ¶
func (Conn) RunInTransaction ¶
RunInTransaction runs a function in a transaction. If function returns an error transaction is rolled back, otherwise transaction is committed.
func (*Conn) WithContext ¶
WithContext returns a copy of the DB that uses the ctx.
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB is a database handle representing a pool of zero or more underlying connections. It's safe for concurrent use by multiple goroutines.
Example (ArrayValueScanner) ¶
Output: 55
Example (JsonUseNumber) ¶
Output: json.Number
func Connect ¶
Connect connects to a database using provided options.
The returned DB is safe for concurrent use by multiple goroutines and maintains its own connection pool.
Example ¶
Output: 1
func (DB) AddQueryHook ¶
func (db DB) AddQueryHook(hook QueryHook)
AddQueryHook adds a hook into query processing.
func (DB) Begin ¶
Begin starts a transaction. Most callers should use RunInTransaction instead.
Example ¶
Output: 10
func (DB) Close ¶
func (db DB) Close() error
Close closes the database client, releasing any open resources.
It is rare to Close a DB, as the DB handle is meant to be long-lived and shared between many goroutines.
func (*DB) Conn ¶
Conn returns a single connection from the connection pool. Queries run on the same Conn will be run in the same database session.
Every Conn must be returned to the database pool after use by calling Conn.Close.
func (DB) CopyFrom ¶
func (db DB) CopyFrom(r io.Reader, query interface{}, params ...interface{}) (res Result, err error)
CopyFrom copies data from reader to a table.
Example ¶
Output: hello,5 foo,3
func (DB) Exec ¶
Exec executes a query ignoring returned rows. The params are for any placeholders in the query.
Example ¶
Output: -1
func (DB) ExecContext ¶
func (DB) ExecOne ¶
ExecOne acts like Exec, but query must affect only one row. It returns ErrNoRows error when query returns zero rows or ErrMultiRows when query returns multiple rows.
func (DB) ExecOneContext ¶
func (DB) Formatter ¶
func (db DB) Formatter() orm.QueryFormatter
func (DB) Model ¶
Model returns new query for the model.
Example ¶
Output: User<1 admin [admin1@admin admin2@admin]> [User<1 admin [admin1@admin admin2@admin]> User<2 root [root1@root root2@root]>] Story<1 Cool story User<1 admin [admin1@admin admin2@admin]>>
Example (BelongsTo) ¶
Output: 2 results 1 user 1 &{1 en 1} 2 user 2 &{2 ru 2}
Example (BulkDelete) ¶
Output: deleted 3 left 0
Example (BulkInsert) ¶
Output: Book<Id=4 Title="new book 1"> Book<Id=5 Title="new book 2">
Example (BulkInsertSlice) ¶
Output: [Book<Id=4 Title="new book 1"> Book<Id=5 Title="new book 2">]
Example (BulkUpdate) ¶
Output: [Book<Id=1 Title="updated book 1"> Book<Id=2 Title="updated book 2"> Book<Id=3 Title="book 3">]
Example (BulkUpdateSlice) ¶
Output: [Book<Id=1 Title="updated book 1"> Book<Id=2 Title="updated book 2"> Book<Id=3 Title="book 3">]
Example (Count) ¶
Output: 3
Example (CountEstimate) ¶
Output: 3
Example (CreateTable) ¶
Output: [{id bigint} {name text} {model1_id bigint}]
Example (Delete) ¶
Output: pg: no rows in result set
Example (DeleteMultipleRows) ¶
Output: deleted 3 left 0
Example (DiscardUnknownColumns) ¶
Output: Model1: pg: can't find column=id in model=Model1 (prefix the column with underscore or use discard_unknown_columns) Model2: <nil>
Example (Exists) ¶
Output: true
Example (ForEach) ¶
Output: Book<Id=1 Title="book 1"> Book<Id=2 Title="book 2"> Book<Id=3 Title="book 3">
Example (HasMany) ¶
Output: 1 user 1 &{1 en true 1} &{2 ru true 1}
Example (HasManySelf) ¶
Output: Item 1 Subitems 2 3
Example (HasOne) ¶
Output: 2 results 1 user 1 &{1 en} 2 user 2 &{2 ru}
Example (HstoreStructTag) ¶
Output: {1 map[hello:world]}
Example (Insert) ¶
Output: Book<Id=4 Title="new book">
Example (InsertDynamicTableName) ¶
Output: id is 123
Example (InsertOnConflictDoNothing) ¶
Output: created did nothing
Example (InsertOnConflictDoUpdate) ¶
Output: Book<Id=100 Title="title version #0"> Book<Id=100 Title="title version #1">
Example (NullEmptyValue) ¶
Output: false
Example (PostgresArrayStructTag) ¶
Output: &{1 [one@example.com two@example.com] [[1 2] [3 4]]}
Example (Select) ¶
Output: Book<Id=1 Title="book 1">
Example (SelectAllColumns) ¶
Output: Book<Id=1 Title="book 1"> 1
Example (SelectAndCount) ¶
Output: 3 [Book<Id=1 Title="book 1"> Book<Id=2 Title="book 2">]
Example (SelectApplyFunc) ¶
Output: [Book<Id=1 Title="book 1"> Book<Id=2 Title="book 2">]
Example (SelectFirstRow) ¶
Output: Book<Id=1 Title="book 1">
Example (SelectGroupBy) ¶
Output: len 2 author 1 has 2 books author 11 has 1 books
Example (SelectLastRow) ¶
Output: Book<Id=3 Title="book 3">
Example (SelectOrInsert) ¶
Output: true Author<ID=2 Name="R. Scott Bakker">
Example (SelectSQLExpression) ¶
Output: [1 2 3]
Example (SelectSomeColumns) ¶
Output: Book<Id=1 Title="book 1">
Example (SelectSomeColumnsIntoVars) ¶
Output: 1 book 1
Example (SelectWhereGroup) ¶
Output: [Book<Id=1 Title="book 1"> Book<Id=2 Title="book 2">]
Example (SelectWhereIn) ¶
Output: [Book<Id=1 Title="book 1"> Book<Id=2 Title="book 2">]
Example (SelectWith) ¶
Output: [Book<Id=1 Title="book 1"> Book<Id=2 Title="book 2">]
Example (SelectWrapWith) ¶
Output: [Book<Id=1 Title="book 1"> Book<Id=2 Title="book 2">]
Example (SoftDelete) ¶
Output: count 0 deleted count 1 deleted count 0
Example (Update) ¶
Output: Book<Id=1 Title="updated book 1">
Example (UpdateNotZero) ¶
Output: Book<Id=1 Title="updated book 1">
Example (UpdateSetValues) ¶
Output: Book<Id=1 Title="prefix book 1 suffix">
Example (UpdateSomeColumns) ¶
Output: Book<Id=1 Title="updated book 1"> 1
Example (UpdateSomeColumns2) ¶
Output: Book<Id=1 Title="updated book 1"> 1
Example (UpdateUseZeroBool) ¶
Output: &{1 true} &{1 false}
func (DB) ModelContext ¶
func (DB) Ping ¶
Ping verifies a connection to the database is still alive, establishing a connection if necessary.
func (DB) Prepare ¶
Prepare creates a prepared statement for later queries or executions. Multiple queries or executions may be run concurrently from the returned statement.
Example ¶
Output: foo bar
func (DB) Query ¶
Query executes a query that returns rows, typically a SELECT. The params are for any placeholders in the query.
Example ¶
Output: User<1 admin [admin1@admin admin2@admin]> [User<1 admin [admin1@admin admin2@admin]> User<2 root [root1@root root2@root]>] Story<1 Cool story User<1 admin [admin1@admin admin2@admin]>>
func (DB) QueryContext ¶
func (DB) QueryOne ¶
QueryOne acts like Query, but query must return only one row. It returns ErrNoRows error when query returns zero rows or ErrMultiRows when query returns multiple rows.
Example ¶
Output: 1 {admin}
Example (Returning_id) ¶
Output: {1 admin}
func (DB) QueryOneContext ¶
func (DB) RunInTransaction ¶
RunInTransaction runs a function in a transaction. If function returns an error transaction is rolled back, otherwise transaction is committed.
Example ¶
Output: 10
func (*DB) WithContext ¶
WithContext returns a copy of the DB that uses the ctx.
type Error ¶
type Error interface { error // Field returns a string value associated with an error field. // // https://www.postgresql.org/docs/10/static/protocol-error-fields.html Field(field byte) string // IntegrityViolation reports whether an error is a part of // Integrity Constraint Violation class of errors. // // https://www.postgresql.org/docs/10/static/errcodes-appendix.html IntegrityViolation() bool }
Error represents an error returned by PostgreSQL server using PostgreSQL ErrorResponse protocol.
https://www.postgresql.org/docs/10/static/protocol-message-formats.html
Example ¶
Output: video already exists: ERROR #23505 duplicate key value violates unique constraint "videos_pkey"
type Ident ¶
Ident represents a SQL identifier, e.g. table or column name.
Example ¶
Output: Book<Id=1 Title="book 1">
type IntSet ¶
type IntSet map[int64]struct{}
IntSet is a set of int64 values.
func (IntSet) AddColumnScanner ¶
func (IntSet) AddColumnScanner(_ orm.ColumnScanner) error
AddColumnScanner ...
func (*IntSet) NextColumnScanner ¶
func (set *IntSet) NextColumnScanner() orm.ColumnScanner
NextColumnScanner ...
func (*IntSet) ScanColumn ¶
ScanColumn scans the columns and appends them to `IntSet`.
type Ints ¶
type Ints []int64
Ints is a type alias for a slice of int64 values.
Example ¶
Output: [0 1 2 3 4 5 6 7 8 9 10]
func (Ints) AddColumnScanner ¶
func (Ints) AddColumnScanner(_ orm.ColumnScanner) error
AddColumnScanner ...
func (Ints) AppendValue ¶
AppendValue appends the values from `ints` to the given byte slice.
func (*Ints) NextColumnScanner ¶
func (ints *Ints) NextColumnScanner() orm.ColumnScanner
NewColumnScanner ...
func (*Ints) ScanColumn ¶
ScanColumn scans the columns and appends them to `ints`.
type Listener ¶
type Listener struct {
// contains filtered or unexported fields
}
Listener listens for notifications sent with NOTIFY command. It's NOT safe for concurrent use by multiple goroutines except the Channel API.
Example ¶
Output: {mychan hello world}
func (*Listener) Channel ¶
func (ln *Listener) Channel() <-chan Notification
Channel returns a channel for concurrently receiving notifications. It periodically sends Ping notification to test connection health.
The channel is closed with Listener. Receive* APIs can not be used after channel is created.
func (*Listener) ChannelSize ¶
func (ln *Listener) ChannelSize(size int) <-chan Notification
ChannelSize is like Channel, but creates a Go channel with specified buffer size.
func (*Listener) Receive ¶
Receive indefinitely waits for a notification. This is low-level API and in most cases Channel should be used instead.
type Notification ¶
Notification which is received with LISTEN command.
type NullTime ¶
NullTime is a time.Time wrapper that marshals zero time as JSON null and PostgreSQL NULL.
type Options ¶
type Options struct { // Network type, either tcp or unix. // Default is tcp. Network string // TCP host:port or Unix socket depending on Network. Addr string // Dialer creates new network connection and has priority over // Network and Addr options. Dialer func(ctx context.Context, network, addr string) (net.Conn, error) // Hook that is called after new connection is established // and user is authenticated. OnConnect func(ctx context.Context, cn *Conn) error User string Password string Database string // ApplicationName is the application name. Used in logs on Pg side. // Only available from pg-9.0. ApplicationName string // TLS config for secure connections. TLSConfig *tls.Config // Dial timeout for establishing new connections. // Default is 5 seconds. DialTimeout time.Duration // Timeout for socket reads. If reached, commands will fail // with a timeout instead of blocking. ReadTimeout time.Duration // Timeout for socket writes. If reached, commands will fail // with a timeout instead of blocking. WriteTimeout time.Duration // Maximum number of retries before giving up. // Default is to not retry failed queries. MaxRetries int // Whether to retry queries cancelled because of statement_timeout. RetryStatementTimeout bool // Minimum backoff between each retry. // Default is 250 milliseconds; -1 disables backoff. MinRetryBackoff time.Duration // Maximum backoff between each retry. // Default is 4 seconds; -1 disables backoff. MaxRetryBackoff time.Duration // Maximum number of socket connections. // Default is 10 connections per every CPU as reported by runtime.NumCPU. PoolSize int // Minimum number of idle connections which is useful when establishing // new connection is slow. MinIdleConns int // Connection age at which client retires (closes) the connection. // It is useful with proxies like PgBouncer and HAProxy. // Default is to not close aged connections. MaxConnAge time.Duration // Time for which client waits for free connection if all // connections are busy before returning an error. // Default is 30 seconds if ReadTimeOut is not defined, otherwise, // ReadTimeout + 1 second. PoolTimeout time.Duration // Amount of time after which client closes idle connections. // Should be less than server's timeout. // Default is 5 minutes. -1 disables idle timeout check. IdleTimeout time.Duration // Frequency of idle checks made by idle connections reaper. // Default is 1 minute. -1 disables idle connections reaper, // but idle connections are still discarded by the client // if IdleTimeout is set. IdleCheckFrequency time.Duration }
Options contains database connection options.
type QueryEvent ¶
type QueryEvent struct { StartTime time.Time DB orm.DB Model interface{} Query interface{} Params []interface{} Result Result Err error Stash map[interface{}]interface{} // contains filtered or unexported fields }
QueryEvent ...
func (*QueryEvent) FormattedQuery ¶
func (e *QueryEvent) FormattedQuery() ([]byte, error)
FormattedQuery returns the formatted query of a query event. The query is only valid until the query Result is returned to the user.
func (*QueryEvent) UnformattedQuery ¶
func (e *QueryEvent) UnformattedQuery() ([]byte, error)
UnformattedQuery returns the unformatted query of a query event. The query is only valid until the query Result is returned to the user.
type QueryHook ¶
type QueryHook interface { BeforeQuery(context.Context, *QueryEvent) (context.Context, error) AfterQuery(context.Context, *QueryEvent) error }
QueryHook ...
type Stmt ¶
type Stmt struct {
// contains filtered or unexported fields
}
Stmt is a prepared statement. Stmt is safe for concurrent use by multiple goroutines.
func (*Stmt) ExecContext ¶
ExecContext executes a prepared statement with the given parameters.
func (*Stmt) ExecOne ¶
ExecOne acts like Exec, but query must affect only one row. It returns ErrNoRows error when query returns zero rows or ErrMultiRows when query returns multiple rows.
func (*Stmt) ExecOneContext ¶
ExecOneContext acts like ExecOne but additionally receives a context.
func (*Stmt) QueryContext ¶
func (stmt *Stmt) QueryContext(c context.Context, model interface{}, params ...interface{}) (Result, error)
QueryContext acts like Query but additionally receives a context.
type Strings ¶
type Strings []string
Strings is a type alias for a slice of strings.
Example ¶
Output: [foo bar]
func (Strings) AddColumnScanner ¶
func (Strings) AddColumnScanner(_ orm.ColumnScanner) error
AddColumnScanner ...
func (Strings) AppendValue ¶
AppendValue appends the values from `strings` to the given byte slice.
func (*Strings) NextColumnScanner ¶
func (strings *Strings) NextColumnScanner() orm.ColumnScanner
NextColumnScanner ...
func (*Strings) ScanColumn ¶
ScanColumn scans the columns and appends them to `strings`.
type Tx ¶
type Tx struct {
// contains filtered or unexported fields
}
Tx is an in-progress database transaction. It is safe for concurrent use by multiple goroutines.
A transaction must end with a call to Commit or Rollback.
After a call to Commit or Rollback, all operations on the transaction fail with ErrTxDone.
The statements prepared for a transaction by calling the transaction's Prepare or Stmt methods are closed by the call to Commit or Rollback.
func (*Tx) CloseContext ¶
Close calls Rollback if the tx has not already been committed or rolled back.
func (*Tx) CommitContext ¶
Commit commits the transaction.
func (*Tx) CopyFrom ¶
func (tx *Tx) CopyFrom(r io.Reader, query interface{}, params ...interface{}) (res Result, err error)
CopyFrom is an alias for DB.CopyFrom.
func (*Tx) ExecContext ¶
func (tx *Tx) ExecContext(c context.Context, query interface{}, params ...interface{}) (Result, error)
ExecContext acts like Exec but additionally receives a context.
func (*Tx) ExecOneContext ¶
func (tx *Tx) ExecOneContext(c context.Context, query interface{}, params ...interface{}) (Result, error)
ExecOneContext acts like ExecOne but additionally receives a context.
func (*Tx) Formatter ¶
func (tx *Tx) Formatter() orm.QueryFormatter
Formatter is an alias for DB.Formatter.
func (*Tx) ModelContext ¶
ModelContext acts like Model but additionally receives a context.
func (*Tx) Prepare ¶
Prepare creates a prepared statement for use within a transaction.
The returned statement operates within the transaction and can no longer be used once the transaction has been committed or rolled back.
To use an existing prepared statement on this transaction, see Tx.Stmt.
func (*Tx) QueryContext ¶
func (tx *Tx) QueryContext( c context.Context, model interface{}, query interface{}, params ...interface{}, ) (Result, error)
QueryContext acts like Query but additionally receives a context.
func (*Tx) QueryOneContext ¶
func (tx *Tx) QueryOneContext( c context.Context, model interface{}, query interface{}, params ...interface{}, ) (Result, error)
QueryOneContext acts like QueryOne but additionally receives a context.
func (*Tx) RollbackContext ¶
Rollback aborts the transaction.
func (*Tx) RunInTransaction ¶
RunInTransaction runs a function in the transaction. If function returns an error transaction is rolled back, otherwise transaction is committed.
Source Files
Directories
Path | Synopsis |
---|---|
The API in this package is not stable and may change without any notice.
|
The API in this package is not stable and may change without any notice. |
The API in this package is not stable and may change without any notice.
|
The API in this package is not stable and may change without any notice. |
internal is a private internal package.
|
internal is a private internal package. |