Documentation
¶
Overview ¶
Package postgres is the PostgreSQL dialect of sqlate: how the engine renders the nth bind parameter, how its driver's errors classify, the session-level advisory lock the migrate protocol takes, and the statement that reads the server's version. It is a sub-module so the driver it names, pgx, enters a consumer's build only through this import, made once where it opens its pool; a consumer opens its own pool with the driver and hands it to sqlate.Wrap with Dialect.
Error classification ¶
Dialect.MapError reads the SQLSTATE the driver exposes. Class 22, a data exception (invalid text for a type, a value out of range, a bad datetime), becomes sqlate.ErrInvalidValue wrapping the driver error, the engine-side half of request validation. Class 23 constraint violations become a sqlate.ConstraintError whose fields are the class sentinel, the driver error, and the violated constraint's name: 23505 unique, 23503 foreign key, 23514 check, 23502 not null. MapError returns everything else unchanged, sql.ErrNoRows included, and errors.As finds the driver error through every wrap.
Locking ¶
Dialect.Lock and Dialect.Unlock implement sqlate.Locker over pg_advisory_lock and pg_advisory_unlock on a pinned connection. The name enters the engine's key space through hashtext, so locks are named and never numbered; the lock belongs to the connection's session and outlives any transaction on it. Unlock of a lock the session does not hold is ErrLockNotHeld.
Server version ¶
Dialect.ServerVersion returns SELECT version(), the statement an administrative layer runs to report the engine's version. It is a capability rather than part of sqlate.Dialect, since every engine spells the read differently and the session layer never needs it.
Native forms ¶
The sqlint.toml beside this file exports the engine's native forms: the spellings a standard-tier SQL file must not use, each a regular expression under the name a finding reports. PostgreSQL accepts every library pattern as written in standard SQL, so the module supplies no overlay.
Index ¶
- Variables
- type Dialect
- func (Dialect) Lock(ctx context.Context, conn *sql.Conn, name string) error
- func (Dialect) MapError(err error) error
- func (Dialect) Name() string
- func (Dialect) Placeholder(n int) string
- func (Dialect) ServerVersion() string
- func (Dialect) Unlock(ctx context.Context, conn *sql.Conn, name string) error
Constants ¶
This section is empty.
Variables ¶
var ErrLockNotHeld = errors.New("advisory lock not held by this session")
ErrLockNotHeld reports an Unlock of a name this session did not hold; the engine answers false rather than failing, so the dialect makes it an error.
Functions ¶
This section is empty.
Types ¶
type Dialect ¶
type Dialect struct{}
Dialect is the PostgreSQL dialect: sqlate.Dialect plus the sqlate.Locker capability and the server-version statement. It has no fields; the zero value is the dialect.
func (Dialect) Lock ¶
Lock takes the session-level advisory lock for name on conn, blocking until it is granted or ctx ends. The name enters the engine's 32-bit key space through hashtext. The lock belongs to the connection's session and outlives any transaction on it; Unlock on the same conn releases it.
func (Dialect) MapError ¶
MapError classifies a driver error by its SQLSTATE: class 22 as sqlate.ErrInvalidValue with the engine's message reachable, the four class-23 constraint violations as a sqlate.ConstraintError with the constraint name, and everything else unchanged. nil stays nil.
func (Dialect) Placeholder ¶
Placeholder renders the 1-based nth bind parameter as $n.
func (Dialect) ServerVersion ¶ added in v0.1.1
ServerVersion returns the statement an administrative read runs to learn the server's version: one row, one text column. Every engine spells it differently, so the dialect carries it as a capability an administrative layer discovers by type assertion.
Source Files