Help us shape the future of Go! Take the 2026 Go Developer Survey

service

package
v0.2.3 Latest Latest
Warning

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

Go to latest
Published: Sep 25, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package service holds dbq's transport-agnostic business logic used by the CLI, health probes and MCP server.

Index

Constants

View Source
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

View Source
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.

func NewScope

func NewScope(ceiling database.Permission, allow []string, maxRows int) Scope

NewScope builds a Scope from a permission ceiling and an allowlist.

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service exposes database operations over a set of named connections.

func New

func New(manager *database.Manager) *Service

New builds a Service over the given connection manager.

func (*Service) CanWrite

func (s *Service) CanWrite(scope Scope) bool

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

func (s *Service) Health(ctx context.Context, timeout time.Duration) map[string]error

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) Manager

func (s *Service) Manager() *database.Manager

Manager exposes the underlying connection manager for lifecycle handling.

func (*Service) Ping

func (s *Service) Ping(ctx context.Context, scope Scope, connection string) error

Ping verifies that a connection is reachable.

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.

Jump to

Keyboard shortcuts

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