Documentation
¶
Overview ¶
Package online provides the shared online session factory for SDK, CLI, and HTTP. input: errors from online operations (session open, identity, authorization) output: bounded error taxonomy and status mapping that never leaks secrets, endpoints, 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 sentinel errors 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 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 ¶
This section is empty.
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") 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, versions, or driver text.
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 version strings, hostnames, ports, DSNs, or credentials.
Functions ¶
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, driver text, or version strings.
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