pgxsql

Documentation

Index

• Constants
• Variables
• func BuildDeleteUri(resource string) string
• func BuildInsertUri(resource string) string
• func BuildQueryUri(resource string) string
• func BuildUpdateUri(resource string) string
• func ClientShutdown()
• func ClientStartup(db messaging.DatabaseUrl, credentials messaging.Credentials) error
• func IsStarted() bool
• func Ping[E runtime.ErrorHandler](ctx context.Context) (status *runtime.Status)
• func Scan[T Scanner[T]](rows Rows) ([]T, error)
• type CommandTag
  • func Exec[E runtime.ErrorHandler](ctx context.Context, expectedCount int64, req *Request, args ...any) (tag CommandTag, status *runtime.Status)
• type FieldDescription
• type Request
  • func NewDeleteRequest(resource, template string, where []pgxdml.Attr) *Request
  • func NewInsertRequest(resource, template string, values [][]any) *Request
  • func NewQueryRequest(resource, template string, where []pgxdml.Attr) *Request
  • func NewQueryRequestFromValues(resource, template string, values map[string][]string) *Request
  • func NewUpdateRequest(resource, template string, attrs []pgxdml.Attr, where []pgxdml.Attr) *Request
  • func (r *Request) BuildSql() string
  • func (r *Request) String() string
  • func (r *Request) Validate() error
• type Rows
  • func Query[E runtime.ErrorHandler](ctx context.Context, req *Request, args ...any) (result Rows, status *runtime.Status)
• type Scanner
• type Stats
  • func Stat[E runtime.ErrorHandler](ctx context.Context) (stat *Stats, status *runtime.Status)

Examples

• ClientStartup
• Ping
• Request.Validate
• Stat

Constants

const (
	PostgresNID = "postgres"
	QueryNSS    = "query"
	InsertNSS   = "insert"
	UpdateNSS   = "update"
	DeleteNSS   = "delete"
	PingNSS     = "ping"
	StatNSS     = "stat"

	PingUri = "urn:" + PostgresNID + ":" + PingNSS
	StatUri = "urn:" + PostgresNID + ":" + StatNSS
)

const (
	NullCount = int64(-1)
)

Variables

var (
	Uri = pkgPath
)

Functions

func BuildDeleteUri

func BuildDeleteUri(resource string) string

BuildDeleteUri - build an uri with the Delete NSS

func BuildInsertUri

func BuildInsertUri(resource string) string

BuildInsertUri - build an uri with the Insert NSS

func BuildQueryUri

func BuildQueryUri(resource string) string

BuildQueryUri - build an uri with the Query NSS

func BuildUpdateUri

func BuildUpdateUri(resource string) string

BuildUpdateUri - build an uri with the Update NSS

func ClientShutdown

func ClientShutdown()

func ClientStartup

func ClientStartup(db messaging.DatabaseUrl, credentials messaging.Credentials) error

ClientStartup - entry point for creating the pooling client and verifying a connection can be acquired

Example

db := messaging.DatabaseUrl{Url: ""}
err := ClientStartup(db, nil)
if err == nil {
	defer ClientShutdown()
}
fmt.Printf("test: ClientStartup() -> %v\n", err)

Output:

test: ClientStartup() -> database URL is empty

func IsStarted

func IsStarted() bool

IsStarted - returns status of startup

func Ping

func Ping[E runtime.ErrorHandler](ctx context.Context) (status *runtime.Status)

Ping - templated function for pinging the database cluster

Example

err := testStartup()
if err != nil {
	fmt.Printf("test: testStartup() -> [error:%v]\n", err)
} else {
	defer ClientShutdown()
	fmt.Printf("test: clientStartup() -> [started:%v]\n", IsStarted())

	status := Ping[runtime.DebugError](nil)
	fmt.Printf("test: Ping(nil) -> %v\n", status)
}

Output:

test: clientStartup() -> [started:true]
test: Ping(nil) -> OK

func Scan

func Scan[T Scanner[T]](rows Rows) ([]T, error)

Scan - templated function for scanning rows

Types

type CommandTag

type CommandTag struct {
	Sql          string
	RowsAffected int64
	Insert       bool
	Update       bool
	Delete       bool
	Select       bool
}

CommandTag - results from an Exec command

func Exec

func Exec[E runtime.ErrorHandler](ctx context.Context, expectedCount int64, req *Request, args ...any) (tag CommandTag, status *runtime.Status)

Exec - templated function for executing a SQL statement

type FieldDescription

type FieldDescription struct {
	Name                 string
	TableOID             uint32
	TableAttributeNumber uint16
	DataTypeOID          uint32
	DataTypeSize         int16
	TypeModifier         int32
	Format               int16
}

FieldDescription - data for defining the returned Query fields/columns

type Request

type Request struct {
	Uri      string
	Template string
	Values   [][]any
	Attrs    []pgxdml.Attr
	Where    []pgxdml.Attr
	Error    error
	// contains filtered or unexported fields
}

Request - contains data needed to build the SQL statement related to the uri

func NewDeleteRequest

func NewDeleteRequest(resource, template string, where []pgxdml.Attr) *Request

func NewInsertRequest

func NewInsertRequest(resource, template string, values [][]any) *Request

func NewQueryRequest

func NewQueryRequest(resource, template string, where []pgxdml.Attr) *Request

func NewQueryRequestFromValues

func NewQueryRequestFromValues(resource, template string, values map[string][]string) *Request

func NewUpdateRequest

func NewUpdateRequest(resource, template string, attrs []pgxdml.Attr, where []pgxdml.Attr) *Request

func (*Request) BuildSql

func (r *Request) BuildSql() string

func (*Request) String

func (r *Request) String() string

func (*Request) Validate

func (r *Request) Validate() error

Example

uri := "urn:postgres:query.resource"
sql := "select * from table"
req := Request{}

err := req.Validate()
fmt.Printf("test: Validate(empty) -> %v\n", err)

req.Uri = uri
err = req.Validate()
fmt.Printf("test: Validate(%v) -> %v\n", uri, err)

req.Uri = ""
req.Template = sql
err = req.Validate()
fmt.Printf("test: Validate(%v) -> %v\n", sql, err)

req.Uri = uri
req.Template = sql
err = req.Validate()
fmt.Printf("test: Validate(all) -> %v\n", err)

//rsc := "access-log"
//t := "delete from access_log"
//req1 := NewDeleteRequest(rsc, t, nil)
//err = req1.Validate()
//fmt.Printf("test: Validate(%v) -> %v\n", t, err)

//t = "update access_log"
//req1 = NewUpdateRequest(rsc, t, nil, nil)
//err = req1.Validate()
//fmt.Printf("test: Validate(%v) -> %v\n", t, err)

//t = "update access_log"
//req1 = NewUpdateRequest(rsc, t, []pgxdml.Attr{{Name: "test", Val: "test"}}, nil)
//err = req1.Validate()
//fmt.Printf("test: Validate(%v) -> %v\n", t, err)

Output:

test: Validate(empty) -> invalid argument: request Uri is empty
test: Validate(urn:postgres:query.resource) -> invalid argument: request template is empty
test: Validate(select * from table) -> invalid argument: request Uri is empty
test: Validate(all) -> <nil>

type Rows

type Rows interface {
	// Close closes the rows, making the connection ready for use again. It is safe
	// to call Close after rows is already closed.
	Close()

	// Err returns any error that occurred while reading.
	Err() error

	// CommandTag returns the command tag from this query. It is only available after Rows is closed.
	CommandTag() CommandTag

	FieldDescriptions() []FieldDescription

	// Next prepares the next row for reading. It returns true if there is another
	// row and false if no more rows are available. It automatically closes rows
	// when all rows are read.
	Next() bool

	// Scan reads the values from the current row into dest values positionally.
	// dest can include pointers to core pgxsql, values implementing the Scanner
	// interface, and nil. nil will skip the value entirely. It is an error to
	// call Scan without first calling Next() and checking that it returned true.
	Scan(dest ...any) error

	// Values returns the decoded row values. As with Scan(), it is an error to
	// call Values without first calling Next() and checking that it returned
	// true.
	Values() ([]any, error)

	// RawValues returns the unparsed bytes of the row values. The returned data is only valid until the next Next
	// call or the Rows is closed.
	RawValues() [][]byte
}

Rows - interface that proxies the postgresql Rows interface

func Query

func Query[E runtime.ErrorHandler](ctx context.Context, req *Request, args ...any) (result Rows, status *runtime.Status)

Query - templated function for a Query

type Scanner

type Scanner[T any] interface {
	Scan(columnNames []string, values []any) (T, error)
}

Scanner - templated interface for scanning rows

type Stats

type Stats = pgxpool.Stat

Stats - pool statistics

func Stat

func Stat[E runtime.ErrorHandler](ctx context.Context) (stat *Stats, status *runtime.Status)

Stat - templated function for retrieving runtime stats

Example

err := testStartup()
if err != nil {
	fmt.Printf("test: testStartup() -> [error:%v]\n", err)
} else {
	defer ClientShutdown()
	fmt.Printf("test: clientStartup() -> [started:%v]\n", IsStarted())

	stat, status := Stat[runtime.DebugError](nil)
	fmt.Printf("test: Stat(nil) -> [status:%v] [stat:%v]\n", status, stat != nil)
}

Output:

test: clientStartup() -> [started:true]
test: Stat(nil) -> [status:OK] [stat:true]