pgsrv

README

postgres-srv

Postgres Server (incomplete) protocol implementation in Go https://godoc.org/github.com/panoplyio/pgsrv

Documentation

Index

• Constants
• Variables
• func QueryFromContext(ctx context.Context) string
• type AuthType
• type Err
  • func Disallowed(msg string, args ...interface{}) Err
  • func Invalid(msg string, args ...interface{}) Err
  • func Unrecognized(msg string, args ...interface{}) Err
  • func Unsupported(msg string, args ...interface{}) Err
  • func WithDetail(err error, detail string, args ...interface{}) Err
  • func WithHint(err error, hint string, args ...interface{}) Err
  • func WithPosition(err error, position int) Err
  • func WithSeverity(err error, severity string) Err
• type Execer
• type PasswordProvider
• type Queryer
• type ResultTag
• type Server
  • func New(queryer Queryer) Server
• type Session

Constants

const (
	SessionCtxKey ctxKey = "Session"
	SqlCtxKey     ctxKey = "SQL"
	AstCtxKey     ctxKey = "AST"
)

Variables

var GlobCtx = make(chan map[string]interface{})

Functions

func QueryFromContext

func QueryFromContext(ctx context.Context) string

QueryFromContext returns the sql string as saved in the given context

Types

type AuthType

type AuthType string

AuthType represents various types of authentication

const (
	// Trust is an auth type for trusted networks, it does not require a password
	Trust AuthType = "trust"

	// MD5 is an auth type where authentication uses md5 hashes with random salt
	MD5 AuthType = "md5"

	// Plain is an auth type where password is sent as plain text over network
	Plain AuthType = "plain"
)

type Err

type Err error

Err is a postgres-compatible error object. It's not required to be used, as any other normal error object would be converted to a generic internal error, but it provides the API to generate user-friendly error messages. Note that all of the construction functions (prefixed with With*) are updating the same error, and does not create a new one. The same error is returned for chaining. See: https://www.postgresql.org/docs/9.3/static/protocol-error-fields.html

Postgres has hundreds of different error codes, broken into categories. Use the constructors below (Invalid, Unsupported, etc.) to create errors with preset error codes. If you can't find the one you need, consider adding it here as a generic constructor. Otherwise, you can implement an object that adheres to this interface:

interface {
    error
    Code() string
}

For the full list of error codes, see: https://www.postgresql.org/docs/10/static/errcodes-appendix.html

func Disallowed

func Disallowed(msg string, args ...interface{}) Err

Disallowed indicates a permissions, authorization or permanently disallowed operation - access to table data, alerting users, etc.

func Invalid

func Invalid(msg string, args ...interface{}) Err

Invalid indicates that the user request is invalid or otherwise incorrect. It's very much similar to a syntax error, except that the invalidity is logical within the request rather than syntactic. For example, using a non- boolean expression in WHERE, or when a requested data type, table, or function is undefined.

func Unrecognized

func Unrecognized(msg string, args ...interface{}) Err

Unrecognized indicates that a certain entity (function, column, etc.) is not registered or available for use.

func Unsupported

func Unsupported(msg string, args ...interface{}) Err

Unsupported indicates that a certain feature is not supported. Unlike Undefined - this error is not for cases where a user-space entity is not recognized but when the recognized entity cannot perform some of its functionality

func WithDetail

func WithDetail(err error, detail string, args ...interface{}) Err

WithDetail decorates an error object to also include an optional secondary error message carrying more detail about the problem. Might run to multiple lines

func WithHint

func WithHint(err error, hint string, args ...interface{}) Err

WithHint decorates an error object to also include an optional suggestion what to do about the problem. This is intended to differ from Detail in that it offers advice (potentially inappropriate) rather than hard facts. Might run to multiple lines

func WithPosition

func WithPosition(err error, position int) Err

WithPosition decorates an error object to also include the cursor position (location) for the error in the original query string. Positions are measured in characters not bytes. This is useful to provide the client a specific marker of where the error occurred in his SQL

func WithSeverity

func WithSeverity(err error, severity string) Err

WithSeverity decorates an error object to also include an optional severity

type Execer

type Execer interface {
	Exec(ctx context.Context, n nodes.Node) (driver.Result, error)
}

Execer is a generic interface for objects capable of executing sql write commands, like INSERT or CREATE TABLE. The returned Result object provides the API for reading the number of affected rows.

type PasswordProvider

type PasswordProvider interface {
	Type() AuthType
	GetPassword(user string) ([]byte, error)
}

PasswordProvider describes objects that are able to provide a password given a user name.

type Queryer

type Queryer interface {
	Query(ctx context.Context, n nodes.Node) (driver.Rows, error)
}

Queryer is a generic interface for objects capable of performing sql queries. The returned Rows object provides the API for reading the row data as well as metadata (like Columns, types, etc.)

type ResultTag

type ResultTag interface {
	Tag() (string, error)
}

ResultTag can be implemented by driver.Result to provide the tag name to be used to notify the postgres client of the completed command. If left unimplemented, the default behavior follows the spec described in the link below. For all un-documented cases, "UPDATE N" will be used, where N is the number of affected rows. See CommandComplete: https://www.postgresql.org/docs/10/static/protocol-message-formats.html

type Server

type Server interface {
	// Manually serve a connection
	Serve(net.Conn) error // blocks. Run in go-routine.
}

Server is an interface for objects capable for handling the postgres protocol by serving client connections. Each connection is assigned a Session that's maintained in-memory until the connection is closed.

func New

func New(queryer Queryer) Server

New creates a Server object capable of handling postgres client connections. It delegates query execution to the provided Queryer. If the provided Queryer also implements Execer, the returned server will also be able to handle executing SQL commands (see Execer).

If queryer implements passwordProvider interface, a new server will be protected with a new md5Authenticator.

type Session

type Session interface {
	Set(k string, v interface{})
	Get(k string) interface{}
	Del(k string)
	All() map[string]interface{}
}

Session represents a connected client session. It provides the API to set, get, delete and accessing all of the session variables. The session should added to the context of all queries executed via the "Session" key:

ctx.Value("Session").(Session)