pgconnstr

README

pgconnstr

Postgres connection string parsing and rendering

Installation

go get -u github.com/tfoertsch123/pgconnstr

Documentation

Overview

Package pgconnstr implements postgres connection-string parsing and rendering. It is not a general purpose syntax checker. It just allows you to convert from the URL representation to a key=value style connection string and vice versa. It might generate invalid connection strings on invalid input.

Index

• Variables
• type PgConnstr
  • func Parse(s string) (PgConnstr, error)
  • func (pgc PgConnstr) Copy() PgConnstr
  • func (pgc PgConnstr) DSN() string
  • func (pgc PgConnstr) Redacted() PgConnstr
  • func (pgc PgConnstr) String() string
  • func (pgc PgConnstr) URL() string

Variables

var (
	ErrKeyExpected   = errors.New("Key expected")
	ErrDanglingEsc   = errors.New("Dangling escape at end of string")
	ErrNotTerminated = errors.New("Unterminated quoted value")
	ErrExpectingEq   = errors.New("Expecting '=' after key")
)

Errors returned by the DSN parser. Each describes a specific malformed-input condition and may be tested for with errors.Is.

var (
	ErrNotPg             = errors.New("Not a postgres URL")
	ErrInvalidQuery      = errors.New("Invalid query")
	ErrInvalidDB         = errors.New("Invalid DB name")
	ErrInvalidUser       = errors.New("Invalid user name")
	ErrInvalidPW         = errors.New("Invalid password")
	ErrInvalidHost       = errors.New("Invalid host")
	ErrTooManyColons     = errors.New("Too many colons")
	ErrMissingColon      = errors.New("Missing colon")
	ErrUntermintatedIPv6 = errors.New("Unterminated IPv6 address")
)

Errors returned by the URL parser. Each describes a specific malformed-input condition and may be tested for with errors.Is.

Types

type PgConnstr

type PgConnstr map[string]string

PgConnstr is a map of PostgreSQL connection-string keyword/value pairs. It is the in-memory representation produced by Parse and consumed by the DSN and URL rendering methods. Keys are libpq parameter keywords (such as "host", "port", "dbname", "user", and "password"); values are their unquoted, unescaped string values.

func Parse

func Parse(s string) (PgConnstr, error)

Parse parses a PostgreSQL connection string into a PgConnstr. It accepts either a libpq keyword/value (DSN) string or a connection URL using the postgres:// or postgresql:// scheme; the form is detected automatically. An error is returned if the input is malformed. According to the Postgres documentation, the multi-host URL postgres://host1:port1,host2:port2,host3:port3/ is equivalent to the DSN "host=host1,host2,host3 port=port1,port2,port3". The spec also allows for a single port which applies to all hosts. The corresponding URL would be postgres://host1,host2,host3:port. Other than that, the documentation requires the same number of elements in the port and host lists and also in hostaddr if specified. This module does not validate this condition in any format.

func (PgConnstr) Copy

func (pgc PgConnstr) Copy() PgConnstr

Copy returns a shallow copy of the connection parameters. The returned PgConnstr is a distinct map: mutating it does not affect the original, and mutating the original does not affect the copy.

func (PgConnstr) DSN

func (pgc PgConnstr) DSN() string

DSN renders the connection parameters as a libpq keyword/value (DSN) string. Keys are emitted in a canonical order — the well-known libpq keywords first, then any remaining keys alphabetically. Values that contain a single quote or a backslash are single-quoted and have those characters backslash-escaped.

func (PgConnstr) Redacted

func (pgc PgConnstr) Redacted() PgConnstr

Redacted returns a copy of the connection parameters with the "password" value, if present, replaced by "XXXXXXXX". The original PgConnstr is left unmodified. The result is suitable for producing connection strings that are safe to log.

func (PgConnstr) String

func (pgc PgConnstr) String() string

String returns the connection parameters as a libpq keyword/value (DSN) string. It is a convenience alias for DSN so that PgConnstr satisfies the fmt.Stringer interface.

func (PgConnstr) URL

func (pgc PgConnstr) URL() string

URL renders the connection parameters as a PostgreSQL connection URL using the postgres:// scheme. The userinfo (user and password), host and port, and database name are emitted in their conventional URL positions and percent-encoded as needed; IPv6 host literals keep their brackets. Any remaining parameters are appended as a query string, ordered by the same canonical keyword sort as DSN. According to the Postgres documentation, the multi-host URL postgres://host1:port1,host2:port2,host3:port3/ is equivalent to the DSN "host=host1,host2,host3 port=port1,port2,port3". The spec also allows for a single port which applies to all hosts. The corresponding URL would be postgres://host1,host2,host3:port. Other than that, the documentation requires the same number of elements in the port and host lists and also in hostaddr if specified. This module does not check that and might generate invalid URLs on invalid input.