Documentation
¶
Overview ¶
Package sql provides the dialect-agnostic engine shared by all SQL client blocks (`client "postgres"`, `client "mysql"`, `client "sqlite"`).
This package is pure Go and carries no database driver imports: a concrete dialect (e.g. clients/sql/sqlite) supplies a Dialect and calls ProcessCommon. SQL statements are executed through the existing polymorphic get()/call() functions; see doc/client-sql.md for the user-facing surface.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ProcessCommon ¶
func ProcessCommon(config *cfg.Config, block *hcl.Block, d Dialect, common *CommonDef, defaults PoolDefaults) (cfg.Client, hcl.Diagnostics)
ProcessCommon builds an *SQLClient from a decoded dialect definition and registers it as a Startable/Stoppable. The dialect package is responsible for decoding its own definition struct (embedding CommonDef) and constructing the Dialect before calling this.
Types ¶
type CommonDef ¶
type CommonDef struct {
MaxOpenConns *int `hcl:"max_open_conns,optional"`
MaxIdleConns *int `hcl:"max_idle_conns,optional"`
ConnMaxLifetime *string `hcl:"conn_max_lifetime,optional"`
ConnMaxIdleTime *string `hcl:"conn_max_idle_time,optional"`
StatementTimeout *string `hcl:"statement_timeout,optional"`
Queries []QueryDef `hcl:"query,block"`
}
CommonDef holds the configuration shared by every SQL dialect block. A dialect package decodes its own definition struct (with hcl:",remain" to capture the rest of the body), then passes the remaining body to DecodeCommonDef and the result to ProcessCommon.
gohcl does not flatten embedded structs, so CommonDef is decoded from the dialect struct's remaining body in a second pass rather than by embedding.
Note: `disabled` is consumed by the top-level client handler before the dialect processor runs, so it is intentionally absent here.
func DecodeCommonDef ¶
func DecodeCommonDef(body hcl.Body, ctx *hcl.EvalContext) (*CommonDef, hcl.Diagnostics)
DecodeCommonDef decodes the dialect-agnostic configuration from the remaining body of a SQL client block (after the dialect has decoded its own fields via hcl:",remain").
type Dialect ¶
type Dialect interface {
// DriverName is the database/sql driver name ("sqlite3", "pgx", "mysql").
DriverName() string
// DSN is the fully-assembled connection string passed to sql.Open. The
// dialect package owns all discrete-field → DSN assembly and escaping.
DSN() string
// BindType selects the sqlx.Rebind target style: sqlx.QUESTION for
// sqlite/mysql, sqlx.DOLLAR for postgres.
BindType() int
// Name is the dialect label reported in the result object's error.driver
// field ("sqlite", "postgres", "mysql").
Name() string
// ClassifyError extracts (code, sqlstate) from a driver error for the
// result error object. Returning ("", "") is fine — message-only errors
// still work.
ClassifyError(err error) (code, sqlstate string)
}
Dialect is everything the common engine needs from a concrete database. A dialect package implements this and hands it to ProcessCommon along with the decoded common configuration.
type PoolDefaults ¶
type PoolDefaults struct {
MaxOpenConns int
MaxIdleConns int
ConnMaxLifetime time.Duration
ConnMaxIdleTime time.Duration
}
PoolDefaults carries the dialect-flavored default pool tuning used when a client block leaves a knob unset. Postgres/MySQL use larger defaults than SQLite; the dialect package supplies the appropriate values.
type QueryDef ¶
type QueryDef struct {
Name string `hcl:",label"`
SQL string `hcl:"sql"`
Cardinality string `hcl:"cardinality,optional"` // one|zero_or_one|many|exec; default "many"
OnZero string `hcl:"on_zero,optional"` // null|error; default "null" (zero_or_one only)
StatementTimeout *string `hcl:"statement_timeout,optional"`
Disabled bool `hcl:"disabled,optional"`
DefRange hcl.Range `hcl:",def_range"`
}
QueryDef is a `query "name" { ... }` sub-block inside a SQL client block.
type SQLClient ¶
type SQLClient struct {
cfg.BaseClient
// contains filtered or unexported fields
}
SQLClient is the dialect-agnostic runtime for a SQL client block. The same type backs every dialect; the Dialect supplies driver name, DSN, and bindvar style.
func (*SQLClient) Call ¶
Call implements richcty.Callable for the bare client form:
call(ctx, client.<name>, "SQL ...", params...)
func (*SQLClient) CtyValue ¶
CtyValue exposes the client as `client.<name>`: a rich object whose _capsule is the client itself (for the bare inline-SQL form) and whose named attributes are the declared queries (`client.<name>.<query>`).
func (*SQLClient) Get ¶
Get implements richcty.Gettable for the bare client form:
get(ctx, client.<name>, "SELECT ...", params...)
args[0] is the inline SQL string; remaining args are parameters.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package mysql registers the `client "mysql"` block.
|
Package mysql registers the `client "mysql"` block. |
|
Package postgres registers the `client "postgres"` block.
|
Package postgres registers the `client "postgres"` block. |
|
Package sqlite registers the `client "sqlite"` block.
|
Package sqlite registers the `client "sqlite"` block. |