README
¶
Online Session Module
Shared online connection identity and error boundaries for the CLI, HTTP, and public Query Access session APIs.
Files
| File | Responsibility |
|---|---|
| identity.go | Parses server identity, derives supported capability series, and classifies the bounded PostgreSQL PG17 version boundary |
| session.go | Opens and pins MySQL/TiDB or PostgreSQL sessions, performs liveness and identity probes, and closes owned resources |
| errors.go | Maps online operation failures to bounded HTTP codes, messages, and statuses without exposing driver or connection details |
| identity_test.go | Verifies supported, mismatched, malformed, unsupported, and bounded PostgreSQL identity behavior |
| session_test.go | Verifies identity probes, session lifecycle, DSN construction, and connection defaults |
| session_integration_test.go | Verifies real Docker-backed identity and session behavior |
Exports
ProductFamily,VersionSeries,ServerIdentity, andCapabilityTargetParseServerIdentity(),DeriveCapabilityTarget(), andIdentifyFromConn()SessionConfig,Session, andOpenSession()MapOnlineError(),IsAuthenticationFailure(), and bounded online error sentinelsPostgreSQLQueryAccessVersionRequirementandErrPostgreSQLQueryAccessVersionUnsupported
Dependencies
- Upstream:
pkg/deltascope,internal/interfaces/cli,internal/interfaces/http - Downstream:
database/sql, MySQL driver, pgx/stdlib,internal/application/auditmeta,internal/application/connresolve
Update Rule
- If members, identity contracts, error mappings, or dependencies change, update this file in the same change.
Documentation
¶
Overview ¶
Package online provides the shared online session factory for SDK, CLI, and HTTP. input: errors from online operations (session open, identity, authorization) and connresolve Connection Failure Class output: bounded error taxonomy and status mapping that never leaks secrets, endpoints, observed identity, authentication details, or driver text pos: shared error boundary for all online surfaces (HTTP, MCP, CLI) note: if this file changes, update this header and module README.md.
Package online provides the shared online session factory for SDK, CLI, and HTTP. input: pinned *sql.Conn, server version string, expected dialect output: validated ServerIdentity, CapabilityTarget, and bounded identity errors including the fixed PostgreSQL Query Access version requirement pos: shared identity parsing and session lifecycle for online query access note: if this file changes, update this header and module README.md.
Package online provides the shared online session factory for SDK, CLI, and HTTP. input: SessionConfig with connection parameters, TLS mode, and expected dialect output: pinned *sql.Conn with validated ServerIdentity and CapabilityTarget, with bounded authentication and connection failures pos: shared session lifecycle for online query access (open, pin, identify, close) note: if this file changes, update this header and module README.md.
Index ¶
Constants ¶
const PostgreSQLQueryAccessVersionRequirement = "online PostgreSQL Query Access requires PostgreSQL 17"
PostgreSQLQueryAccessVersionRequirement is the stable bounded message for a reachable PostgreSQL server outside the trusted online PG17 capability.
Variables ¶
var ( ErrConnectionNotFound = errors.New("connection not found") ErrPurposeNotAllowed = errors.New("purpose not allowed for this connection") ErrPrincipalNotAllowed = errors.New("principal not authorized for this connection") ErrConnectionFailed = errors.New("connection failed") // ErrAuthenticationFailed identifies a database authentication failure. ErrAuthenticationFailed = errors.New("authentication failed") ErrSchemaRequired = errors.New("schema is required") ErrSchemaLookupFailed = errors.New("schema lookup failed") ErrTimeout = errors.New("operation timed out") ErrCanceled = errors.New("operation canceled") ErrInternal = errors.New("internal error") )
Sentinel errors for online operations. Messages are bounded — they never contain secrets, endpoints, observed versions, or driver text. The PostgreSQL Query Access requirement is a fixed supported-version phrase.
var ( ErrIdentityUnknown = errors.New("unsupported database product") ErrIdentityMalformed = errors.New("malformed server version") ErrIdentityUnsupported = errors.New("unsupported database version series") ErrDialectMismatch = errors.New("configured dialect disagrees with server identity") )
Bounded sentinel errors for identity parsing. These messages never contain observed version strings, hostnames, ports, DSNs, or credentials. The fixed PostgreSQL Query Access requirement is safe to expose at transport boundaries.
var ErrPostgreSQLQueryAccessVersionUnsupported error = postgreSQLQueryAccessVersionUnsupportedError{}
ErrPostgreSQLQueryAccessVersionUnsupported identifies a recognized PostgreSQL server whose version is outside the intentionally trusted PG17 capability. It unwraps to ErrIdentityUnsupported for existing identity callers.
Functions ¶
func IsAuthenticationFailure ¶ added in v0.500.0
IsAuthenticationFailure reports whether an online driver error uses one of the bounded authentication signals recognized by the transport adapters.
func MapOnlineError ¶
MapOnlineError maps an error from online operations to a bounded (code, message, status) tuple. The returned message never contains sensitive information such as DSNs, credentials, hostnames, ports, observed version strings, or driver text.
Types ¶
type CapabilityTarget ¶
type CapabilityTarget string
CapabilityTarget represents the internal analysis capability derived from identity.
const ( TargetMySQL57 CapabilityTarget = "mysql-5.7" TargetMySQL80 CapabilityTarget = "mysql-8.0" TargetMySQL84 CapabilityTarget = "mysql-8.4" TargetTiDB85 CapabilityTarget = "tidb-8.5" TargetPG17 CapabilityTarget = "postgresql-17" )
func DeriveCapabilityTarget ¶
func DeriveCapabilityTarget(id *ServerIdentity) CapabilityTarget
DeriveCapabilityTarget maps a validated ServerIdentity to its internal capability target.
type ProductFamily ¶
type ProductFamily string
ProductFamily identifies the database product family.
const ( ProductMySQL ProductFamily = "mysql" ProductTiDB ProductFamily = "tidb" ProductPostgreSQL ProductFamily = "postgresql" )
type ServerIdentity ¶
type ServerIdentity struct {
Product ProductFamily
Major int
Minor int
Patch int
Series VersionSeries
RawVersion string // internal only, never exposed
}
ServerIdentity represents the validated database server identity. It never appears in public results, errors, or logs.
func IdentifyFromConn ¶
func IdentifyFromConn(ctx context.Context, conn *sql.Conn, expectedDialect string) (*ServerIdentity, error)
IdentifyFromConn queries VERSION() on the pinned connection and parses the identity.
func ParseServerIdentity ¶
func ParseServerIdentity(rawVersion string, expectedDialect string) (*ServerIdentity, error)
ParseServerIdentity parses a VERSION() string and validates against supported series. Returns bounded sentinel errors for unknown/unsupported/malformed identity. The raw version string is stored internally but never exposed in errors.
type Session ¶
type Session struct {
DB *sql.DB
Conn *sql.Conn
Identity *ServerIdentity
Target CapabilityTarget
Close func() error // idempotent, closes both Conn and DB
}
Session holds the pinned connection and derived identity/metadata.
func OpenSession ¶
func OpenSession(ctx context.Context, cfg SessionConfig) (*Session, error)
OpenSession opens a database connection, pins it, captures identity, and returns a session. On any failure after opening, both DB and Conn are closed. The caller must call session.Close() when done.
type SessionConfig ¶
type SessionConfig struct {
Host string
Port int
Socket string
User string
Password string
Database string
Schema string
Dialect string
ConnectTimeout time.Duration
TLSMode string // "disabled" or "enabled"
CACert *x509.CertPool // pre-parsed CA pool; only used when tls_mode=enabled
}
SessionConfig holds the connection parameters for opening an online session.
type VersionSeries ¶
type VersionSeries string
VersionSeries identifies a supported major/minor version series.
const ( SeriesMySQL57 VersionSeries = "mysql-5.7" SeriesMySQL80 VersionSeries = "mysql-8.0" SeriesMySQL84 VersionSeries = "mysql-8.4" SeriesTiDB85 VersionSeries = "tidb-8.5" SeriesPG17 VersionSeries = "postgresql-17" )
Source Files