README
¶
Sevlumen PostgreSQL
A PostgreSQL-native database/sql driver written in Go without pgx, libpq, or C dependencies.
Status: stable
v1.0.0, validated on Go 1.23/current and PostgreSQL 14 through 18.
v1 scope
The stable v1 contract is intentionally focused on production service workloads such as Identity:
- PostgreSQL protocol 3.0 over TCP;
- TLS modes
disable,require,verify-ca, andverify-full; - SCRAM-SHA-256, MD5, and TLS-protected cleartext authentication;
- extended query protocol with positional parameters;
database/sqlconnector and registered stdlib driver;- query, exec, prepared-statement facade, transactions, and pooling through
database/sql; - context cancellation through PostgreSQL
CancelRequest; - structured PostgreSQL errors and SQLSTATE helpers;
- text codecs for bool, integers, floats, numeric, text, bytea, date, timestamp, timestamptz, UUID, JSON, and JSONB;
- PostgreSQL 14–18 compatibility matrix.
Explicitly outside v1:
- Unix-domain sockets;
- SCRAM-SHA-256-PLUS/channel binding;
- protocol 3.2 variable-length cancellation keys;
- COPY, LISTEN/NOTIFY public APIs, replication, and pipelining;
- binary parameter/result codecs;
- server-side prepared-statement caching.
Those exclusions do not block Identity workloads and prevent the first stable API from becoming unnecessarily broad.
Install
go get github.com/sevlumen/postgres@v1.0.0
Recommended usage
package main
import (
"context"
"log"
"time"
postgres "github.com/sevlumen/postgres"
)
func main() {
db, err := postgres.Open(
"postgres://identity:password@localhost:5432/identity?sslmode=verify-full",
)
if err != nil {
log.Fatal(err)
}
defer db.Close()
db.SetMaxOpenConns(20)
db.SetMaxIdleConns(5)
db.SetConnMaxLifetime(30 * time.Minute)
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
if err := db.PingContext(ctx); err != nil {
log.Fatal(err)
}
}
Registered database/sql driver
import (
"database/sql"
_ "github.com/sevlumen/postgres/stdlib"
)
db, err := sql.Open(
"sevlumen-postgres",
"postgres://identity:password@localhost:5432/identity?sslmode=require",
)
Prefer postgres.Open or sql.OpenDB(postgres.NewConnector(...)) because these paths validate configuration before returning the pool.
Queries and parameters
var id string
var email string
err := db.QueryRowContext(
ctx,
`SELECT id, email FROM users WHERE email = $1`,
"admin@example.com",
).Scan(&id, &email)
Arguments are encoded separately from SQL through PostgreSQL's extended query protocol. Do not interpolate request values into SQL strings.
Transactions
tx, err := db.BeginTx(ctx, nil)
if err != nil {
return err
}
defer tx.Rollback()
if _, err := tx.ExecContext(ctx,
`UPDATE refresh_tokens SET consumed_at = now()
WHERE token_hash = $1 AND consumed_at IS NULL`, tokenHash,
); err != nil {
return err
}
if _, err := tx.ExecContext(ctx,
`INSERT INTO refresh_tokens(id, token_hash) VALUES($1, $2)`, id, replacementHash,
); err != nil {
return err
}
return tx.Commit()
SQLSTATE
_, err := db.ExecContext(ctx, statement, email)
if postgres.IsUniqueViolation(err) {
// duplicate email
}
postgres.Error exposes severity, SQLSTATE, detail, hint, schema, table, column, and constraint fields.
TLS defaults
The default is sslmode=verify-full. Production services should keep that setting and provide a certificate chain trusted by the operating system or a custom RootCAs pool.
sslmode=require encrypts the transport but does not verify the server identity. sslmode=disable should be limited to local development and isolated CI. Cleartext and MD5 password authentication are rejected on an unencrypted transport unless AllowInsecureAuthentication is explicitly enabled.
Validation
Local unit and race tests:
go vet ./...
go test -race ./...
PostgreSQL integration suite:
SEVLUMEN_POSTGRES_TEST_DSN='postgres://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable' \
go test -race ./integration -count=1
See architecture, security boundaries, and the release checklist.
Documentation
¶
Index ¶
- Constants
- Variables
- func IsDeadlockDetected(err error) bool
- func IsForeignKeyViolation(err error) bool
- func IsSQLState(err error, code string) bool
- func IsSerializationFailure(err error) bool
- func IsUniqueViolation(err error) bool
- func Open(dsn string) (*sql.DB, error)
- func OpenConfig(config Config) (*sql.DB, error)
- type Config
- type Connector
- type Error
- type TLSMode
Constants ¶
const Version = "1.0.0"
Version is the stable semantic version of the driver.
Variables ¶
var ErrOperationOutcomeUnknown = errors.New("postgres: connection lost after operation started; outcome is unknown")
ErrOperationOutcomeUnknown means a connection failed after an operation may have reached PostgreSQL. The driver returns this instead of driver.ErrBadConn so database/sql does not retry a potentially non-idempotent statement.
Functions ¶
func IsDeadlockDetected ¶
func IsForeignKeyViolation ¶
func IsSQLState ¶
func IsSerializationFailure ¶
func IsUniqueViolation ¶
Types ¶
type Config ¶
type Config struct {
Host string
Port uint16
User string
Password string
Database string
TLSMode TLSMode
TLSConfig *tls.Config
RootCAs *x509.CertPool
ServerName string
ConnectTimeout time.Duration
CancelTimeout time.Duration
MaxMessageSize int32
ApplicationName string
RuntimeParams map[string]string
// AllowInsecureAuthentication permits cleartext or MD5 password authentication
// on an unencrypted transport. It is false by default.
AllowInsecureAuthentication bool
}
Config contains connection settings for one PostgreSQL server.
func ParseConfig ¶
ParseConfig parses a postgres:// or postgresql:// URL.
type Connector ¶
type Connector struct {
// contains filtered or unexported fields
}
Connector implements database/sql/driver.Connector.
func NewConnector ¶
type Error ¶
type Error struct {
Severity string
SeverityNonLocal string
Code string
Message string
Detail string
Hint string
Position string
InternalPosition string
InternalQuery string
Where string
Schema string
Table string
Column string
DataType string
Constraint string
File string
Line string
Routine string
}
Error is a structured PostgreSQL ErrorResponse.
Source Files
Directories