pgdriver

README

pgdriver

pgdriver is a database/sql driver for PostgreSQL based on go-pg code.

You can install it with:

github.com/uptrace/bun/driver/pgdriver

And then create a sql.DB using it:

import _ "github.com/uptrace/bun/driver/pgdriver"

dsn := "postgres://postgres:@localhost:5432/test"
db, err := sql.Open("pg", dsn)

Alternatively:

dsn := "postgres://postgres:@localhost:5432/test"
db := sql.OpenDB(pgdriver.NewConnector(pgdriver.WithDSN(dsn)))

Benchmark:

BenchmarkInsert/pg-12 	            7254	    148380 ns/op	     900 B/op	      13 allocs/op
BenchmarkInsert/pgx-12         	    6494	    166391 ns/op	    2076 B/op	      26 allocs/op
BenchmarkSelect/pg-12          	    9100	    132952 ns/op	    1417 B/op	      18 allocs/op
BenchmarkSelect/pgx-12         	    8199	    154920 ns/op	    3679 B/op	      60 allocs/op

Documentation

Index

• Variables
• func NewConnector(opts ...DriverOption) driver.Connector
• type ChannelOption
  • func WithChannelSize(size int) ChannelOption
• type Config
• type Conn
  • func (cn *Conn) Begin() (driver.Tx, error)
  • func (cn *Conn) BeginTx(ctx context.Context, opts driver.TxOptions) (driver.Tx, error)
  • func (cn *Conn) Close() error
  • func (cn *Conn) ExecContext(ctx context.Context, query string, args []driver.NamedValue) (driver.Result, error)
  • func (cn *Conn) IsValid() bool
  • func (cn *Conn) Ping(ctx context.Context) error
  • func (cn *Conn) Prepare(query string) (driver.Stmt, error)
  • func (cn *Conn) QueryContext(ctx context.Context, query string, args []driver.NamedValue) (driver.Rows, error)
• type Driver
  • func NewDriver() Driver
  • func (d Driver) Open(name string) (driver.Conn, error)
  • func (d Driver) OpenConnector(name string) (driver.Connector, error)
• type DriverOption
  • func WithAddr(addr string) DriverOption
  • func WithApplicationName(appName string) DriverOption
  • func WithDSN(dsn string) DriverOption
  • func WithDatabase(database string) DriverOption
  • func WithDialTimeout(dialTimeout time.Duration) DriverOption
  • func WithPassword(password string) DriverOption
  • func WithReadTimeout(readTimeout time.Duration) DriverOption
  • func WithTLSConfig(cfg *tls.Config) DriverOption
  • func WithTimeout(timeout time.Duration) DriverOption
  • func WithUser(user string) DriverOption
  • func WithWriteTimeout(writeTimeout time.Duration) DriverOption
• type DriverStats
• type Error
  • func (err Error) Error() string
  • func (err Error) Field(k byte) string
  • func (err Error) IntegrityViolation() bool
• type Listener
  • func NewListener(db *bun.DB) *Listener
  • func (ln *Listener) Channel(opts ...ChannelOption) <-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) Unlisten(ctx context.Context, channels ...string) error
• type Notification

Variables

var Logger logging = &logger{
	log: log.New(os.Stderr, "pgdriver: ", log.LstdFlags|log.Lshortfile),
}

Functions

func NewConnector

func NewConnector(opts ...DriverOption) driver.Connector

Types

type ChannelOption

type ChannelOption func(c *channel)

func WithChannelSize

func WithChannelSize(size int) ChannelOption

type Config

type Config struct {
	// Network type, either tcp or unix.
	// Default is tcp.
	Network string
	// TCP host:port or Unix socket depending on Network.
	Addr string
	// Dial timeout for establishing new connections.
	// Default is 5 seconds.
	DialTimeout time.Duration
	// Dialer creates new network connection and has priority over
	// Network and Addr options.
	Dialer func(ctx context.Context, network, addr string) (net.Conn, error)

	// TLS config for secure connections.
	TLSConfig *tls.Config

	User     string
	Password string
	Database string
	AppName  string

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

type Conn

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

func (*Conn) Begin

func (cn *Conn) Begin() (driver.Tx, error)

func (*Conn) BeginTx

func (cn *Conn) BeginTx(ctx context.Context, opts driver.TxOptions) (driver.Tx, error)

func (*Conn) Close

func (cn *Conn) Close() error

func (*Conn) ExecContext

func (cn *Conn) ExecContext(
	ctx context.Context, query string, args []driver.NamedValue,
) (driver.Result, error)

func (*Conn) IsValid

func (cn *Conn) IsValid() bool

func (*Conn) Ping

func (cn *Conn) Ping(ctx context.Context) error

func (*Conn) Prepare

func (cn *Conn) Prepare(query string) (driver.Stmt, error)

func (*Conn) QueryContext

func (cn *Conn) QueryContext(
	ctx context.Context, query string, args []driver.NamedValue,
) (driver.Rows, error)

type Driver

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

func NewDriver

func NewDriver() Driver

func (Driver) Open

func (d Driver) Open(name string) (driver.Conn, error)

func (Driver) OpenConnector

func (d Driver) OpenConnector(name string) (driver.Connector, error)

type DriverOption

type DriverOption func(*driverConnector)

func WithAddr

func WithAddr(addr string) DriverOption

func WithApplicationName

func WithApplicationName(appName string) DriverOption

func WithDSN

func WithDSN(dsn string) DriverOption

func WithDatabase

func WithDatabase(database string) DriverOption

func WithDialTimeout

func WithDialTimeout(dialTimeout time.Duration) DriverOption

func WithPassword

func WithPassword(password string) DriverOption

func WithReadTimeout

func WithReadTimeout(readTimeout time.Duration) DriverOption

func WithTLSConfig

func WithTLSConfig(cfg *tls.Config) DriverOption

func WithTimeout

func WithTimeout(timeout time.Duration) DriverOption

func WithUser

func WithUser(user string) DriverOption

func WithWriteTimeout

func WithWriteTimeout(writeTimeout time.Duration) DriverOption

type DriverStats

type DriverStats struct {
	Queries uint64
	Errors  uint64
}

type Error

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

Error represents an error returned by PostgreSQL server using PostgreSQL ErrorResponse protocol.

https://www.postgresql.org/docs/current/static/protocol-message-formats.html

func (Error) Error

func (err Error) Error() string

func (Error) Field

func (err Error) Field(k byte) string

Field returns a string value associated with an error field.

https://www.postgresql.org/docs/current/static/protocol-error-fields.html

func (Error) IntegrityViolation

func (err Error) IntegrityViolation() bool

IntegrityViolation reports whether an error is a part of Integrity Constraint Violation class of errors.

https://www.postgresql.org/docs/current/static/errcodes-appendix.html

type Listener

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

func NewListener

func NewListener(db *bun.DB) *Listener

func (*Listener) Channel

func (ln *Listener) Channel(opts ...ChannelOption) <-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) Close

func (ln *Listener) Close() error

Close closes the listener, releasing any open resources.

func (*Listener) Listen

func (ln *Listener) Listen(ctx context.Context, channels ...string) error

Listen starts listening for notifications on channels.

func (*Listener) Receive

func (ln *Listener) Receive(ctx context.Context) (channel string, payload string, err error)

Receive indefinitely waits for a notification. This is low-level API and in most cases Channel should be used instead.

func (*Listener) ReceiveTimeout

func (ln *Listener) ReceiveTimeout(
	ctx context.Context, timeout time.Duration,
) (channel, payload string, err error)

ReceiveTimeout waits for a notification until timeout is reached. This is low-level API and in most cases Channel should be used instead.

func (*Listener) Unlisten

func (ln *Listener) Unlisten(ctx context.Context, channels ...string) error

Unlisten stops listening for notifications on channels.

type Notification

type Notification struct {
	Channel string
	Payload string
}

Notification received with LISTEN command.