Documentation
¶
Overview ¶
Package service holds dbq's transport-agnostic business logic used by the CLI, health probes and MCP server.
Index ¶
- Constants
- Variables
- type ExecuteRequest
- type ExportRequest
- type SchemaContext
- type SchemaContextRequest
- type Scope
- type Service
- func (s *Service) CanWrite(scope Scope) bool
- func (s *Service) Connections(scope Scope) []database.ConnectionInfo
- func (s *Service) DescribeTable(ctx context.Context, scope Scope, connection, schema, table string) (*database.TableDetail, error)
- func (s *Service) Execute(ctx context.Context, scope Scope, req ExecuteRequest) (*database.Result, error)
- func (s *Service) ExportInserts(ctx context.Context, scope Scope, req ExportRequest, w io.Writer) (*database.ExportResult, error)
- func (s *Service) Health(ctx context.Context, timeout time.Duration) map[string]error
- func (s *Service) ListTables(ctx context.Context, scope Scope, connection, schema string) ([]database.Table, error)
- func (s *Service) Manager() *database.Manager
- func (s *Service) Ping(ctx context.Context, scope Scope, connection string) error
- func (s *Service) SchemaContext(ctx context.Context, scope Scope, req SchemaContextRequest) (*SchemaContext, error)
Constants ¶
const DefaultMaxSchemaTables = 40
DefaultMaxSchemaTables bounds a schema context request. Describing a table is one round trip each, so an unbounded request against a large schema would be both slow and far too large for a model's context window.
Variables ¶
var FullScope = Scope{Cap: database.PermissionFull}
FullScope is the unrestricted scope used by trusted local callers.
Functions ¶
This section is empty.
Types ¶
type ExecuteRequest ¶
type ExecuteRequest struct {
// Connection is the required profile name.
Connection string
// SQL is the statement. Exactly one statement is expected.
SQL string
// MaxRows overrides the scope row limit. Zero uses the scope default.
MaxRows int
// MaxCellChars overrides the scope per-value limit. Zero uses the default.
MaxCellChars int
// ReadOnly forces the statement to be rejected unless it is a read, no
// matter what the connection permission allows.
ReadOnly bool
}
ExecuteRequest is a single SQL statement to run.
type ExportRequest ¶ added in v0.2.3
type ExportRequest struct {
Connection string
SQL string
TargetTable string
TargetDialect string
BatchSize int
MaxRows int
}
ExportRequest describes a read query rendered as INSERT statements.
type SchemaContext ¶
type SchemaContext struct {
Connection string `json:"connection"`
Schema string `json:"schema,omitempty"`
Tables []database.TableDetail `json:"tables"`
// TableCount is how many tables exist, before MaxTables was applied.
TableCount int `json:"table_count"`
// Truncated is true when TableCount exceeded the cap.
Truncated bool `json:"truncated,omitempty"`
// Compact is a one-line-per-table rendering, far cheaper in tokens than the
// structured form and usually all a model needs to write correct SQL.
Compact string `json:"compact"`
}
SchemaContext is a whole-schema summary aimed at an LLM context window.
type SchemaContextRequest ¶
type SchemaContextRequest struct {
Connection string
Schema string
// Tables restricts the output to these table names. Empty means all.
Tables []string
// MaxTables caps how many tables are described. Zero uses DefaultMaxSchemaTables.
MaxTables int
}
SchemaContextRequest asks for a compact description of a whole schema.
type Scope ¶
type Scope struct {
// Cap is the ceiling applied on top of a connection's own permission. The
// effective permission is the lower of the two. Empty means no extra cap.
Cap database.Permission
// Allow restricts which connections are visible. Nil or empty means all.
Allow map[string]struct{}
// MaxRows is the default row limit for this scope. Zero uses the database
// package default.
MaxRows int
// MaxCellChars is the default per-value character limit. Zero uses the
// database package default.
MaxCellChars int
// Timeout bounds a single statement. Zero means no dbq-imposed deadline.
Timeout time.Duration
}
Scope is a caller's view of the service: which connections it may see and how much it may do with them.
It lets each caller apply its own connection visibility and permission limits without duplicating the data access code.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service exposes database operations over a set of named connections.
func (*Service) CanWrite ¶
CanWrite reports whether any modifying statement could succeed in this scope. It is false when the ceiling forbids writes, or when every visible connection is itself read-only.
func (*Service) Connections ¶
func (s *Service) Connections(scope Scope) []database.ConnectionInfo
Connections returns the connections visible in the scope, with the effective permission already folded in so callers see what they can actually do.
func (*Service) DescribeTable ¶
func (s *Service) DescribeTable(ctx context.Context, scope Scope, connection, schema, table string) (*database.TableDetail, error)
DescribeTable returns the column layout of a table.
func (*Service) Execute ¶
func (s *Service) Execute(ctx context.Context, scope Scope, req ExecuteRequest) (*database.Result, error)
Execute authorizes and runs a statement.
Authorization happens before the statement reaches the driver: the statement is classified, the effective permission (connection permission capped by the scope) is checked, and only then is it executed.
func (*Service) ExportInserts ¶ added in v0.2.3
func (s *Service) ExportInserts(ctx context.Context, scope Scope, req ExportRequest, w io.Writer) (*database.ExportResult, error)
ExportInserts streams query results to w without materializing them in an MCP response.
func (*Service) Health ¶ added in v0.2.2
Health pings every connection concurrently, each under its own timeout, and reports the outcome per connection. Concurrency matters because one hung database must not delay the report on the others, and the timeout is what stops it from hanging the probe altogether. Zero timeout means none.
func (*Service) ListTables ¶
func (s *Service) ListTables(ctx context.Context, scope Scope, connection, schema string) ([]database.Table, error)
ListTables returns the tables and views of a connection.
func (*Service) SchemaContext ¶
func (s *Service) SchemaContext(ctx context.Context, scope Scope, req SchemaContextRequest) (*SchemaContext, error)
SchemaContext lists the tables of a connection and describes each one.