dialect

package
v0.1.17 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 16, 2026 License: MIT Imports: 0 Imported by: 0

Documentation

Overview

Package dialect abstracts SQL dialect differences: identifier quoting, parameter placeholders, EXPLAIN wrapping, and capability negotiation.

Concrete dialect implementations live in x/providers alongside each database adapter. The heavier EXPLAIN-result parsing (cost.Explainer) and schema introspection (introspect.Introspector) also stay in x/providers because they require live database access. Capabilities drive both codegen rendering and which Gate layers are assembled per database.

Index

Constants

This section is empty.

Variables

Keys lists every capability in report order.

Functions

This section is empty.

Types

type Claim added in v0.1.15

type Claim struct {
	Strength Strength
	Evidence Evidence
	// Reason says how it is provided or why it is degraded.
	Reason string
}

Claim is what a dialect or connection guarantees for one capability.

type Dialect

type Dialect interface {
	Name() string
	QuoteIdent(name string) string
	Placeholder(index int) string
	// Capabilities is what the dialect itself provides, whatever the
	// connection; a connection's Profile adds what depends on how it was
	// opened.
	Capabilities() Profile
}

Dialect abstracts the SQL differences core codegen needs. Implementations are stateless and safe for concurrent use.

type Evidence added in v0.1.15

type Evidence string

Evidence is what backs a claim.

const (
	// DBVerified: integration tests run it against the real database.
	DBVerified Evidence = "db_verified"
	// CoreVerified: shared-layer tests cover it; no test on this database.
	CoreVerified Evidence = "core_verified"
	// Declared: stated, not independently tested.
	Declared Evidence = "declared"
	// External: it rests on database or deployment configuration the server
	// does not manage.
	External Evidence = "external"
)

type Key added in v0.1.15

type Key string

Key names a capability.

const (
	// Returning: INSERT ... RETURNING reads the inserted row back in one
	// statement (otherwise exec + the last insert id).
	Returning Key = "write.returning"
	// Explain: EXPLAIN yields a numeric estimate the cost gate can score.
	Explain Key = "cost.explain"
	// ExplainAccurate: the estimates are trustworthy enough to gate on
	// without explain fail-closed.
	ExplainAccurate Key = "cost.explain.accurate"
	// ExplainAnalyze: EXPLAIN ANALYZE sampling for estimate feedback.
	ExplainAnalyze Key = "cost.explain.analyze"
	// TimeoutRead: a read statement stops at cost.queryTimeout on the server.
	TimeoutRead Key = "limit.timeout.read"
	// TimeoutWrite: a writing statement stops at cost.queryTimeout on the
	// server.
	TimeoutWrite Key = "limit.timeout.write"
	// UnkeyedWrite: the database refuses UPDATE/DELETE without a key, as a
	// backstop behind the gate's WriteGuard.
	UnkeyedWrite Key = "limit.unkeyedWrite"
)

type Profile added in v0.1.15

type Profile map[Key]Claim

Profile holds the claims of a dialect or connection. A missing key is unsupported.

func (Profile) Claim added in v0.1.15

func (p Profile) Claim(k Key) Claim

Claim returns the claim for k; a missing key is unsupported.

func (Profile) Enforced added in v0.1.15

func (p Profile) Enforced(k Key) bool

Enforced reports whether k is enforced.

func (Profile) Has added in v0.1.15

func (p Profile) Has(k Key) bool

Has reports whether k is provided at all (best effort or enforced).

func (Profile) With added in v0.1.15

func (p Profile) With(others Profile) Profile

With returns a copy of p with others' claims added or replacing p's.

type Strength added in v0.1.15

type Strength string

Strength is how firmly the server guarantees a capability.

const (
	// Unsupported: the server does not provide it.
	Unsupported Strength = "unsupported"
	// BestEffort: the server tries, but no hard guarantee rests on it.
	BestEffort Strength = "best_effort"
	// Enforced: an assembled, tested mechanism that does not silently degrade.
	Enforced Strength = "enforced"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL