pg

package module
v4.0.10+incompatible Latest Latest
Warning

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

 Go to latest Published: Apr 29, 2016 License: BSD-3-Clause Imports: 16 Imported by: 0

README

PostgreSQL client for Golang Build Status

Supports:

API docs: http://godoc.org/gopkg.in/pg.v4. Examples: http://godoc.org/gopkg.in/pg.v4#pkg-examples.

Table of contents

Installation

Install:

go get gopkg.in/pg.v4

Quickstart

package pg_test

import (
	"fmt"

	"gopkg.in/pg.v4"
)

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
	UserId int64
	User   *User
}

func (s Story) String() string {
	return fmt.Sprintf("Story<%d %s %s>", s.Id, s.Title, s.User)
}

func createSchema(db *pg.DB) error {
	queries := []string{
		`CREATE TEMP TABLE users (id serial, name text, emails jsonb)`,
		`CREATE TEMP TABLE stories (id serial, title text, user_id bigint)`,
	}
	for _, q := range queries {
		_, err := db.Exec(q)
		if err != nil {
			return err
		}
	}
	return nil
}

func ExampleDB_Query() {
	db := pg.Connect(&pg.Options{
		User: "postgres",
	})

	err := createSchema(db)
	if err != nil {
		panic(err)
	}

	user1 := &User{
		Name:   "admin",
		Emails: []string{"admin1@admin", "admin2@admin"},
	}
	err = db.Create(user1)
	if err != nil {
		panic(err)
	}

	err = db.Create(&User{
		Name:   "root",
		Emails: []string{"root1@root", "root2@root"},
	})
	if err != nil {
		panic(err)
	}

	story1 := &Story{
		Title:  "Cool story",
		UserId: user1.Id,
	}
	err = db.Create(story1)
	if err != nil {
		panic(err)
	}

	var user User
	err = db.Model(&user).Where("id = ?", user1.Id).Select()
	if err != nil {
		panic(err)
	}

	var users []User
	err = db.Model(&users).Select()
	if err != nil {
		panic(err)
	}

	var story Story
	err = db.Model(&story).
		Column("story.*", "User").
		Where("story.id = ?", story1.Id).
		Select()
	if err != nil {
		panic(err)
	}

	fmt.Println(user)
	fmt.Println(users[0], users[1])
	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]>>
}

Howto

Please go through examples to get the idea how to use this package.

Writing queries

type Book struct {
    Id int
    Title string
    Text string
}

// Insert new book returning primary keys.
err := db.Create(&book)
// INSERT INTO "books" (title, text) VALUES ('my title', 'my text') RETURNING "id"

// Insert new book returning all columns.
err := db.Model(&book).Returning("*").Create()
// INSERT INTO "books" (title, text) VALUES ('my title', 'my text') RETURNING *

// Select existing book by name or create new book.
err := db.Model(&book).
    Where("title = ?title").
    OnConflict("DO NOTHING"). // optional
    SelectOrCreate()
// 1. SELECT * FROM "books" WHERE title = 'my title'
// 2. INSERT INTO "books" (title, text) VALUES ('my title', 'my text') RETURNING "id"
// 3. go to step 1 on error

// Update all columns except primary keys.
err := db.Update(&book)
// UPDATE "books" SET title = 'my title', text = 'my text' WHERE id = 1

// Update only column "title".
res, err := db.Model(&book).Set("title = ?title").Where("id = ?id").Update()
// UPDATE "books" SET title = 'my title' WHERE id = 1

// Update only column "title".
res, err := db.Model(&book).Column("title").Update()
// UPDATE "books" SET title = 'my title' WHERE id = 1

// Update only column "title".
res, err := db.Model(&book).UpdateValues(map[string]interface{}{
    "title": book.Title,
})
// UPDATE "books" SET title = 'my title' WHERE id = 1

// Delete book by primary key.
err := db.Delete(&book)
// DELETE FROM "books" WHERE id = 1

// Delete book by title.
res, err := db.Model(&book).Where("title = ?title").Delete()

// Select book by primary key.
err := db.Select(&book)
// SELECT * FROM "books" WHERE id = 1

// Select book by title.
err := db.Model(&book).Where("title = ?title").Select()

// Select first 20 books.
err := db.Model(&books).Order("id ASC").Offset(0).Limit(20).Select()

// Count books.
count, err := db.Model(Book{}).Count()

Model definition

Models are defined using Go structs. Order of the struct fields usually does not matter with the only exception being primary key(s) that must defined before any other fields. Otherwise table relationshipts can be recognized incorrectly.

type Genre struct {
	TableName struct{} `sql:"genres"` // specifies custom table name

	Id     int // Id is automatically detected as primary key
	Name   string
	Rating int `sql:"-"` // - is used to ignore field

	Books []Book `pg:",many2many:book_genres"` // many to many relation

	ParentId  int     `sql:",null"`
	Subgenres []Genre `pg:",fk:Parent"` // fk specifies prefix for foreign key (ParentId)
}

func (g Genre) String() string {
	return fmt.Sprintf("Genre<Id=%d Name=%q>", g.Id, g.Name)
}

type Author struct {
	ID    int // both "Id" and "ID" are detected as primary key
	Name  string
	Books []Book // has many relation
}

func (a Author) String() string {
	return fmt.Sprintf("Author<ID=%d Name=%q>", a.ID, a.Name)
}

type BookGenre struct {
	BookId  int `sql:",pk"` // pk tag is used to mark field as primary key
	GenreId int `sql:",pk"`

	Genre_Rating int // belongs to and is copied to Genre model
}

type Book struct {
	Id        int
	Title     string
	AuthorID  int
	Author    *Author // has one relation
	EditorID  int
	Editor    *Author // has one relation
	CreatedAt time.Time

	Genres       []Genre       `pg:",many2many:book_genres" gorm:"many2many:book_genres;"` // many to many relation
	Translations []Translation // has many relation
	Comments     []Comment     `pg:",polymorphic:Trackable"` // has many polymorphic relation
}

func (b Book) String() string {
	return fmt.Sprintf("Book<Id=%d Title=%q>", b.Id, b.Title)
}

type Translation struct {
	Id     int
	BookId int
	Book   *Book // belongs to relation
	Lang   string

	Comments []Comment `pg:",polymorphic:Trackable"` // has many polymorphic relation
}

type Comment struct {
	TrackableId   int    `sql:",pk"` // Book.Id or Translation.Id
	TrackableType string `sql:",pk"` // "book" or "translation"
	Text          string
}

FAQ

Why go-pg

  • No rows.Close to manually manage connections.

  • go-pg automatically maps rows on Go structs and slice.

  • go-pg is 2x-10x faster than GORM on querying 100 rows from table.

    BenchmarkQueryRowsGopgOptimized-4	   10000	    158443 ns/op	   83432 B/op	     625 allocs/op
BenchmarkQueryRowsGopgReflect-4  	   10000	    189014 ns/op	   94759 B/op	     826 allocs/op
BenchmarkQueryRowsGopgORM-4      	   10000	    199685 ns/op	   95024 B/op	     830 allocs/op
BenchmarkQueryRowsStdlibPq-4     	    5000	    242135 ns/op	  161646 B/op	    1324 allocs/op
BenchmarkQueryRowsGORM-4         	    2000	    704366 ns/op	  396184 B/op	    6767 allocs/op

  • go-pg generates much more effecient queries for joins.

    Has one relation
    BenchmarkModelHasOneGopg-4                 	    5000	    313091 ns/op	   78481 B/op	    1290 allocs/op
BenchmarkModelHasOneGORM-4                 	     500	   3849634 ns/op	 1529982 B/op	   71636 allocs/op

    go-pg:

    db.Model(&books).Column("book.*", "Author").Limit(100).Select()

    SELECT "book".*, "author"."id" AS "author__id", "author"."name" AS "author__name"
FROM "books" AS "book"
LEFT JOIN "authors" AS "author" ON "author"."id" = "book"."author_id"
LIMIT 100

    GORM:

    db.Preload("Author").Limit(100).Find(&books).Error

    SELECT  * FROM "books"   LIMIT 100
SELECT  * FROM "authors"  WHERE ("id" IN ('1','2'...'100'))
    Has many relation
    BenchmarkModelHasManyGopg-4                	     500	   3034576 ns/op	  409288 B/op	    8700 allocs/op
BenchmarkModelHasManyGORM-4                	      50	  24677309 ns/op	10121839 B/op	  519411 allocs/op

    go-pg:

    db.Model(&books).Column("book.*", "Translations").Limit(100).Select()

     SELECT "book".* FROM "books" AS "book" LIMIT 100
 SELECT "translation".* FROM "translations" AS "translation"
 WHERE ("translation"."book_id") IN ((100), (101), ... (199));

    GORM:

    db.Preload("Translations").Limit(100).Find(&books).Error

    SELECT * FROM "books" LIMIT 100;
SELECT * FROM "translations"
WHERE ("book_id" IN (1, 2, ..., 100));
SELECT * FROM "authors" WHERE ("book_id" IN (1, 2, ..., 100));
    Many to many relation
    BenchmarkModelHasMany2ManyGopg-4           	     500	   3329123 ns/op	  394738 B/op	    9739 allocs/op
BenchmarkModelHasMany2ManyGORM-4           	     200	   7847630 ns/op	 3350304 B/op	   66239 allocs/op

    go-pg:

    db.Model(&books).Column("book.*", "Genres").Limit(100).Select()

    SELECT "book"."id" FROM "books" AS "book" LIMIT 100;
SELECT * FROM "genres" AS "genre"
JOIN "book_genres" AS "book_genre" ON ("book_genre"."book_id") IN ((1), (2), ..., (100))
WHERE "genre"."id" = "book_genre"."genre_id";

    GORM:

    db.Preload("Genres").Limit(100).Find(&books).Error

    SELECT * FROM "books" LIMIT 100;
SELECT * FROM "genres"
INNER JOIN "book_genres" ON "book_genres"."genre_id" = "genres"."id"
WHERE ("book_genres"."book_id" IN ((1), (2), ..., (100)));
How can I view queries this library generates?

You can configure PostgreSQL to log every query by adding following lines to your postgresql.conf (usually /etc/postgresql/9.5/main/postgresql.conf):

log_statement = 'all'
log_min_duration_statement = 0

Then just tail the log file:

tail -f /var/log/postgresql/postgresql-9.5-main.log

Documentation

Overview

Package gopkg.in/pg.v4 implements a PostgreSQL client.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	ErrNoRows    = internal.ErrNoRows
	ErrMultiRows = internal.ErrMultiRows
)
View Source 
var Discard orm.Discard

Discard is used with Query and QueryOne to discard rows.

Functions

func Array 

func Array(v interface{}) *types.Array

Array returns an Array type that represents PostgreSQL array of any type.

Example 
Output:

[one@example.com two@example.com]

func F 

func F(field string, params ...interface{}) types.F

F returns a ValueAppender that represents SQL identifier, e.g. table or column name.

Example 
Output:

Book<Id=1 Title="book 1">

func Q 

func Q(query string, params ...interface{}) types.Q

Q returns a ValueAppender that represents safe SQL query.

Example 
Output:

3

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

func SetLogger 

func SetLogger(logger *log.Logger)

Types

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.

func Connect 

func Connect(opt *Options) *DB

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:

<nil>

func (*DB) Begin 

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

Begin starts a transaction. Most callers should use RunInTransaction instead.

Example 
Output:

1

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) CopyFrom 

func (db *DB) CopyFrom(r io.Reader, query interface{}, params ...interface{}) (*types.Result, error)

CopyFrom copies data from reader to a table.

Example 
Output:

hello,5
foo,3

func (*DB) CopyTo 

func (db *DB) CopyTo(w io.Writer, query interface{}, params ...interface{}) (*types.Result, error)

CopyTo copies data from a table to writer.

func (*DB) Create 

func (db *DB) Create(model interface{}) error

Create inserts the model updating primary keys if they are empty.

Example 
Output:

Book<Id=4 Title="new book">
Example (OnConflict) 
Output:

created
did nothing
Example (SelectOrCreate) 
Output:

true Author<ID=2 Name="R. Scott Bakker">

func (*DB) Delete 

func (db *DB) Delete(model interface{}) error

Delete deletes the model by primary key.

Example 
Output:

pg: no rows in result set
Example (MultipleRows) 
Output:

deleted 3
left 0

func (*DB) Exec 

func (db *DB) Exec(query interface{}, params ...interface{}) (res *types.Result, err error)

Exec executes a query ignoring returned rows. The params are for any placeholder parameters in the query.

Example 
Output:

-1 <nil>

func (*DB) ExecOne 

func (db *DB) ExecOne(query interface{}, params ...interface{}) (*types.Result, error)

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) FormatQuery 

func (db *DB) FormatQuery(dst []byte, query string, params ...interface{}) []byte

func (*DB) Listen 

func (db *DB) Listen(channels ...string) (*Listener, error)

Listen listens for notifications sent by NOTIFY statement.

func (*DB) Model 

func (db *DB) Model(model interface{}) *orm.Query

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 (CountRows) 
Output:

3
Example (HasMany) 
Output:

Item 1
Subitems 2 3
Example (HasOne) 
Output:

found 2 items
item 2, subitem 1
item 4, subitem 2
Example (ManyToMany) 
Output:

Item 1
Subitems 2 3
Example (NullEmptyValue) 
Output:

false
Example (PostgresArrayStructTag) 
Output:

{1 [one@example.com two@example.com] [123 321]}

func (*DB) Options 

func (db *DB) Options() *Options

Options returns read-only Options that were used to connect to the DB.

func (*DB) Prepare 

func (db *DB) Prepare(q string) (*Stmt, error)

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

func (*DB) Query 

func (db *DB) Query(model, query interface{}, params ...interface{}) (res *types.Result, err error)

Query executes a query that returns rows, typically a SELECT. The params are for any placeholder parameters 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) QueryOne 

func (db *DB) QueryOne(model, query interface{}, params ...interface{}) (*types.Result, error)

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) RunInTransaction 

func (db *DB) RunInTransaction(fn func(*Tx) error) error

RunInTransaction runs a function in a transaction. If function returns an error transaction is rollbacked, otherwise transaction is committed.

Example 
Output:

1

func (*DB) Select 

func (db *DB) Select(model interface{}) error

Select selects the model by primary key.

Example 
Output:

Book<Id=1 Title="book 1">
Example (AllColumns) 
Output:

Book<Id=1 Title="book 1"> 1
Example (FirstRow) 
Output:

Book<Id=1 Title="book 1">
Example (LastRow) 
Output:

Book<Id=3 Title="book 3">
Example (SomeColumns) 
Output:

Book<Id=1 Title="">
Example (SomeColumnsIntoVars) 
Output:

1 book 1

func (*DB) Update 

func (db *DB) Update(model interface{}) error

Update updates the model by primary key.

Example 
Output:

Book<Id=1 Title="updated book 1">
Example (MultipleRows) 
Output:

Book<Id=1 Title="prefix book 1 suffix"> Book<Id=2 Title="prefix book 2 suffix">
Example (SetValues) 
Output:

Book<Id=1 Title="prefix book 1 suffix">
Example (SomeColumns) 
Output:

Book<Id=1 Title="updated book 1"> 1
Example (SomeColumns2) 
Output:

Book<Id=1 Title="updated book 1"> 1
Example (UpdateValues) 
Output:

Book<Id=1 Title="prefix book 1 suffix">

func (*DB) WithTimeout 

func (db *DB) WithTimeout(d time.Duration) *DB

WithTimeout returns a DB that uses d as the read/write timeout.

Example 
Output:

type Error 

type Error interface {
	Field(byte) string
	IntegrityViolation() bool
}

type IntSet 

type IntSet map[int64]struct{}

func (IntSet) AddModel 

func (IntSet) AddModel(_ orm.ColumnScanner) error

func (*IntSet) NewModel 

func (set *IntSet) NewModel() orm.ColumnScanner

func (*IntSet) ScanColumn 

func (setptr *IntSet) ScanColumn(colIdx int, colName string, b []byte) error

type Ints 

type Ints []int64
Example 
Output:

[0 1 2 3 4 5 6 7 8 9 10] <nil>
Example (In) 
Output:

SELECT * FROM table WHERE id IN (1,2,3)

func (Ints) AddModel 

func (Ints) AddModel(_ orm.ColumnScanner) error

func (Ints) AppendValue 

func (ints Ints) AppendValue(dst []byte, quote int) ([]byte, error)

func (*Ints) NewModel 

func (ints *Ints) NewModel() orm.ColumnScanner

func (*Ints) ScanColumn 

func (ints *Ints) ScanColumn(colIdx int, colName string, b []byte) error

type Listener 

type Listener struct {
	// contains filtered or unexported fields
}

Not thread-safe.

Example 
Output:

mychan "hello world" <nil>

func (*Listener) Close 

func (l *Listener) Close() error

func (*Listener) Listen 

func (l *Listener) Listen(channels ...string) error

func (*Listener) Receive 

func (l *Listener) Receive() (channel string, payload string, err error)

func (*Listener) ReceiveTimeout 

func (l *Listener) ReceiveTimeout(readTimeout time.Duration) (channel, payload string, err error)

type Options 

type Options struct {
	// The network type, either tcp or unix.
	// Default is tcp.
	Network string
	// TCP host:port or Unix socket depending on Network.
	Addr     string
	User     string
	Password string
	Database string
	// Whether to use secure TCP/IP connections (TLS).
	SSL bool

	// PostgreSQL run-time configuration parameters to be set on connection.
	Params map[string]interface{}

	// The maximum number of retries before giving up.
	// Default is to not retry failed queries.
	MaxRetries int

	// The deadline for establishing new connections. If reached,
	// dial will fail with a timeout.
	// Default is 5 seconds.
	DialTimeout time.Duration
	// The timeout for socket reads. If reached, commands will fail
	// with a timeout error instead of blocking.
	// Default is no timeout.
	ReadTimeout time.Duration
	// The timeout for socket writes. If reached, commands will fail
	// with a timeout error instead of blocking.
	// Default is no timeout.
	WriteTimeout time.Duration

	// The maximum number of open socket connections.
	// Default is 10 connections.
	PoolSize int
	// The amount of time client waits for free connection if all
	// connections are busy before returning an error.
	// Default is 5 seconds.
	PoolTimeout time.Duration
	// The amount of time after which client closes idle connections.
	// Default is to not close idle connections.
	IdleTimeout time.Duration
	// The frequency of idle checks.
	// Default is 1 minute.
	IdleCheckFrequency time.Duration
}

Database connection options.

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) Close 

func (stmt *Stmt) Close() error

Close closes the statement.

func (*Stmt) Exec 

func (stmt *Stmt) Exec(params ...interface{}) (res *types.Result, err error)

Exec executes a prepared statement with the given parameters.

func (*Stmt) ExecOne 

func (stmt *Stmt) ExecOne(params ...interface{}) (*types.Result, error)

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) Query 

func (stmt *Stmt) Query(model interface{}, params ...interface{}) (res *types.Result, err error)

Query executes a prepared query statement with the given parameters.

func (*Stmt) QueryOne 

func (stmt *Stmt) QueryOne(model interface{}, params ...interface{}) (*types.Result, error)

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.

type Strings 

type Strings []string
Example 
Output:

[foo bar] <nil>

func (Strings) AddModel 

func (Strings) AddModel(_ orm.ColumnScanner) error

func (Strings) AppendValue 

func (strings Strings) AppendValue(dst []byte, quote int) ([]byte, error)

func (*Strings) NewModel 

func (strings *Strings) NewModel() orm.ColumnScanner

func (*Strings) ScanColumn 

func (strings *Strings) ScanColumn(colIdx int, _ string, b []byte) error

type Tx 

type Tx struct {
	// contains filtered or unexported fields
}

Not thread-safe.

func (*Tx) Commit 

func (tx *Tx) Commit() (err error)

Commit commits the transaction.

func (*Tx) CopyFrom 

func (tx *Tx) CopyFrom(r io.Reader, query string, params ...interface{}) (*types.Result, error)

CopyFrom copies data from reader to a table.

func (*Tx) Create 

func (tx *Tx) Create(model interface{}) error

Create inserts the model updating primary keys if they are empty.

func (*Tx) Delete 

func (tx *Tx) Delete(model interface{}) error

Delete deletes the model by primary key.

func (*Tx) Exec 

func (tx *Tx) Exec(query interface{}, params ...interface{}) (*types.Result, error)

Exec executes a query with the given parameters in a transaction.

func (*Tx) ExecOne 

func (tx *Tx) ExecOne(query interface{}, params ...interface{}) (*types.Result, error)

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 (*Tx) FormatQuery 

func (tx *Tx) FormatQuery(dst []byte, query string, params ...interface{}) []byte

func (*Tx) Model 

func (tx *Tx) Model(model interface{}) *orm.Query

Model returns new query for the model.

func (*Tx) Prepare 

func (tx *Tx) Prepare(q string) (*Stmt, error)

TODO(vmihailenco): track and close prepared statements

func (*Tx) Query 

func (tx *Tx) Query(model interface{}, query interface{}, params ...interface{}) (*types.Result, error)

Query executes a query with the given parameters in a transaction.

func (*Tx) QueryOne 

func (tx *Tx) QueryOne(model interface{}, query interface{}, params ...interface{}) (*types.Result, error)

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 (*Tx) Rollback 

func (tx *Tx) Rollback() (err error)

Rollback aborts the transaction.

func (*Tx) Select 

func (tx *Tx) Select(model interface{}) error

Select selects the model by primary key.

func (*Tx) Update 

func (tx *Tx) Update(model interface{}) error

Update updates the model by primary key.

Source Files

View all Source files

Directories

Path Synopsis

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.