README
¶
pgdriver
pgdriver is a database/sql driver for PostgreSQL based on go-pg code.
You can install it with:
go get 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)))
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
See documentation for more details.
Documentation
¶
Index ¶
- Variables
- func CopyFrom(ctx context.Context, conn bun.Conn, r io.Reader, query string, args ...any) (res sql.Result, err error)
- func CopyTo(ctx context.Context, conn bun.Conn, w io.Writer, query string, args ...any) (res sql.Result, err error)
- func Notify(ctx context.Context, db *bun.DB, channel, payload string) error
- func ParseTime(s string) (time.Time, error)
- type 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) Conn() net.Conn
- 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) PrepareContext(ctx context.Context, query string) (driver.Stmt, error)
- func (cn *Conn) QueryContext(ctx context.Context, query string, args []driver.NamedValue) (driver.Rows, error)
- func (cn *Conn) ResetSession(ctx context.Context) error
- type Connector
- type Driver
- type Error
- type 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
- type Option
- func WithAddr(addr string) Option
- func WithApplicationName(appName string) Option
- func WithBufferSize(size int) Option
- func WithConfig(after *Config) Option
- func WithConnParams(params map[string]any) Option
- func WithDSN(dsn string) Option
- func WithDatabase(database string) Option
- func WithDialTimeout(dialTimeout time.Duration) Option
- func WithInsecure(on bool) Option
- func WithNetwork(network string) Option
- func WithOptions(opts ...Option) Option
- func WithPassword(password string) Option
- func WithReadTimeout(readTimeout time.Duration) Option
- func WithResetSessionFunc(fn func(context.Context, *Conn) error) Option
- func WithTLSConfig(tlsConfig *tls.Config) Option
- func WithTimeout(timeout time.Duration) Option
- func WithTracing(on bool) Option
- func WithUnsafeStrings(allow bool) Option
- func WithUser(user string) Option
- func WithWriteTimeout(writeTimeout time.Duration) Option
Constants ¶
This section is empty.
Variables ¶
var Logger logging = &logger{ log: log.New(os.Stderr, "pgdriver: ", log.LstdFlags|log.Lshortfile), }
Functions ¶
func CopyFrom ¶ added in v1.0.18
func CopyFrom( ctx context.Context, conn bun.Conn, r io.Reader, query string, args ...any, ) (res sql.Result, err error)
CopyFrom copies data from the reader to the query destination.
func CopyTo ¶ added in v1.0.18
func CopyTo( ctx context.Context, conn bun.Conn, w io.Writer, query string, args ...any, ) (res sql.Result, err error)
CopyTo copies data from the query source to the writer.
Types ¶
type ChannelOption ¶
type ChannelOption func(c *channel)
func WithChannelOverflowHandler ¶ added in v1.2.12
func WithChannelOverflowHandler(handler channelOverflowHandler) ChannelOption
func WithChannelSize ¶
func WithChannelSize(size int) ChannelOption
type Config ¶ added in v0.1.3
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
// PostgreSQL session parameters updated with `SET` command when a connection is created.
ConnParams map[string]any
// Timeout for socket reads. If reached, commands fail with a timeout instead of blocking.
ReadTimeout time.Duration
// Timeout for socket writes. If reached, commands fail with a timeout instead of blocking.
WriteTimeout time.Duration
// ResetSessionFunc is called prior to executing a query on a connection
// that has been used before.
ResetSessionFunc func(context.Context, *Conn) error
// Enable tracing
EnableTracing bool
// size of reader buffer, default is 4096
BufferSize int
// Allow set standard_conforming_strings=off or client_encoding=other character sets
UnsafeStrings bool
}
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
func (*Conn) ExecContext ¶
func (*Conn) PrepareContext ¶ added in v1.2.9
func (*Conn) QueryContext ¶
type Connector ¶ added in v0.3.7
type Connector struct {
// contains filtered or unexported fields
}
func NewConnector ¶
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) Field ¶
Field returns a string value associated with an error field.
https://www.postgresql.org/docs/current/static/protocol-error-fields.html
func (Error) IntegrityViolation ¶
IntegrityViolation reports whether the error is a part of Integrity Constraint Violation class of errors.
https://www.postgresql.org/docs/current/static/errcodes-appendix.html
func (Error) StatementTimeout ¶ added in v1.0.12
StatementTimeout reports whether the error is a statement timeout error.
type Listener ¶
type Listener struct {
// contains filtered or unexported fields
}
Listener provides a high-level abstraction for PostgreSQL LISTEN/NOTIFY functionality, allowing clients to subscribe to one or more channels and receive asynchronous notifications.
A Listener manages a dedicated database connection for receiving events, automatically reconnecting when the connection becomes unhealthy. It can be used in two modes:
- Low-level mode: using Receive or ReceiveTimeout to explicitly wait for notifications.
- High-level mode: using Channel, which returns a Go channel that concurrently delivers Notification values and periodically pings the database to monitor connection health.
The Listener is NOT safe for concurrent use. Multiple goroutines can NOT call Listen, Unlisten, and receive notifications concurrently.
TODO: make it thread-safe by creating 2 separate mutexes for Listen and Receive
func NewListener ¶
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) Receive ¶
Receive indefinitely waits for a notification. This is low-level API and in most cases Channel should be used instead.
type Notification ¶
Notification received with LISTEN command.
type Option ¶ added in v1.0.12
type Option func(conf *Config)
func WithApplicationName ¶
func WithBufferSize ¶ added in v1.2.12
func WithConfig ¶ added in v1.2.12
func WithConnParams ¶ added in v1.0.9
func WithDatabase ¶
func WithDialTimeout ¶
func WithInsecure ¶ added in v1.0.13
func WithNetwork ¶ added in v1.0.12
func WithOptions ¶ added in v1.2.9
func WithPassword ¶
func WithReadTimeout ¶
func WithResetSessionFunc ¶ added in v1.1.8
WithResetSessionFunc configures a function that is called prior to executing a query on a connection that has been used before. If the func returns driver.ErrBadConn, the connection is discarded.
Source Files