trino

package
v1.131.0 Latest Latest
Warning

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

 Go to latest Published: Sep 10, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Overview

Package trino provides a Trino toolkit adapter for the MCP data platform.

Package trino provides a Trino toolkit adapter for the MCP data platform.

Package trino provides a Trino toolkit adapter for the MCP data platform.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AnnotationConfig added in v0.20.0 

type AnnotationConfig = toolkit.AnnotationConfig

AnnotationConfig holds tool annotation overrides from configuration.

type Config 

type Config struct {
	Host     string `yaml:"host"`
	Port     int    `yaml:"port"`
	User     string `yaml:"user"`
	Password string `yaml:"password"` // #nosec G117 -- Trino credential from admin YAML config
	Catalog  string `yaml:"catalog"`
	Schema   string `yaml:"schema"`
	// SSL and SSLVerify are tri-state: nil means the key was absent, which is
	// what lets a non-default connection say plain HTTP. The multiserver
	// manager reads a nil SSL as "auto-detect from the host", and its
	// auto-detect turns HTTPS on for any host that is not localhost, so a
	// connection that set `ssl: false` has to be distinguishable from one that
	// never mentioned SSL. Read them through IsSSLEnabled and
	// IsSSLVerifyEnabled, which supply the primary connection's defaults:
	// SSL off, verification on.
	SSL          *bool         `yaml:"ssl"`
	SSLVerify    *bool         `yaml:"ssl_verify"`
	Timeout      time.Duration `yaml:"timeout"`
	DefaultLimit int           `yaml:"default_limit"`
	MaxLimit     int           `yaml:"max_limit"`
	ReadOnly     bool          `yaml:"read_only"`
	// ConnectionName is accepted for compatibility and has no effect. The
	// platform identifies a Trino connection by its instance name, which is
	// what the manager routes on and what Connection() reports (#1396).
	ConnectionName string                      `yaml:"connection_name"`
	Description    string                      `yaml:"description"` // Human-readable description of this connection's purpose
	Titles         map[string]string           `yaml:"titles"`
	Descriptions   map[string]string           `yaml:"descriptions"`
	Annotations    map[string]AnnotationConfig `yaml:"annotations"`

	// ProgressEnabled enables progress notifications for query execution.
	// Injected by the platform from progress.enabled config.
	ProgressEnabled bool `yaml:"progress_enabled"`

	// Elicitation configures user confirmation for expensive operations.
	// Injected by the platform from elicitation config.
	Elicitation ElicitationConfig `yaml:"elicitation"`

	// Scratch names the catalog and schema table registrations are written
	// into on this connection. Unset means registration is unavailable here.
	Scratch ScratchConfig `yaml:"scratch"`
}

Config holds Trino toolkit configuration.

func ParseConfig 

func ParseConfig(cfg map[string]any) (Config, error)

ParseConfig parses a Trino toolkit configuration from a map.

func (Config) IsSSLEnabled added in v1.125.2 

func (c Config) IsSSLEnabled() bool

IsSSLEnabled reports whether this connection speaks HTTPS. A config that never mentioned SSL is plain HTTP, which is what the field has always meant on the primary connection.

func (Config) IsSSLVerifyEnabled added in v1.125.2 

func (c Config) IsSSLVerifyEnabled() bool

IsSSLVerifyEnabled reports whether certificate verification is on, defaulting to true when the config did not say.

type ConnectionDescription added in v0.26.0 

type ConnectionDescription struct {
	Name        string
	Description string
	IsDefault   bool
}

ConnectionDescription holds display information about a connection for error messages when the connection parameter is missing.

type ConnectionRequiredMiddleware added in v0.26.0 

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

ConnectionRequiredMiddleware rejects tool calls that omit the connection parameter when multiple Trino connections are configured. The error message lists all available connections with their descriptions so the LLM can choose the correct one.

func NewConnectionRequiredMiddleware added in v0.26.0 

func NewConnectionRequiredMiddleware(connections []ConnectionDescription) *ConnectionRequiredMiddleware

NewConnectionRequiredMiddleware creates a middleware that enforces explicit connection selection. The connections slice describes all available backends.

func (*ConnectionRequiredMiddleware) After added in v0.26.0 

func (*ConnectionRequiredMiddleware) After(
	_ context.Context,
	_ *trinotools.ToolContext,
	result *mcp.CallToolResult,
	handlerErr error,
) (*mcp.CallToolResult, error)

After is a no-op — validation happens before execution.

func (*ConnectionRequiredMiddleware) Before added in v0.26.0 

func (m *ConnectionRequiredMiddleware) Before(ctx context.Context, tc *trinotools.ToolContext) (context.Context, error)

Before checks that the connection parameter is set for tools that need it.

type CostEstimationConfig added in v0.21.0 

type CostEstimationConfig struct {
	Enabled      bool  `yaml:"enabled"`
	RowThreshold int64 `yaml:"row_threshold"`
}

CostEstimationConfig configures query cost estimation.

type ElicitationConfig added in v0.21.0 

type ElicitationConfig struct {
	// Enabled is the master switch for all elicitation features.
	Enabled bool `yaml:"enabled"`

	// CostEstimation configures query cost estimation and confirmation.
	CostEstimation CostEstimationConfig `yaml:"cost_estimation"`

	// PIIConsent configures PII access consent.
	PIIConsent PIIConsentConfig `yaml:"pii_consent"`
}

ElicitationConfig configures elicitation triggers for the Trino toolkit.

type ElicitationDeclinedError added in v0.21.0 

type ElicitationDeclinedError struct {
	Reason string
}

ElicitationDeclinedError indicates the user declined an elicitation request. This error is returned when the user explicitly declines or cancels a confirmation prompt (cost estimation, PII consent, etc.).

func (*ElicitationDeclinedError) Error added in v0.21.0 

func (e *ElicitationDeclinedError) Error() string

func (*ElicitationDeclinedError) ErrorCategory added in v0.21.0 

func (*ElicitationDeclinedError) ErrorCategory() string

ErrorCategory implements middleware.CategorizedError.

type ElicitationMiddleware added in v0.21.0 

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

ElicitationMiddleware intercepts Trino query execution to request user confirmation when queries exceed cost thresholds or access PII data. It implements trinotools.ToolMiddleware.

func (*ElicitationMiddleware) After added in v0.21.0 

func (*ElicitationMiddleware) After(
	_ context.Context,
	_ *trinotools.ToolContext,
	result *mcp.CallToolResult,
	handlerErr error,
) (*mcp.CallToolResult, error)

After is a no-op — elicitation happens before query execution.

func (*ElicitationMiddleware) Before added in v0.21.0 

func (em *ElicitationMiddleware) Before(ctx context.Context, tc *trinotools.ToolContext) (context.Context, error)

Before checks cost and PII triggers before query execution. Returns an error to abort the query if the user declines.

func (*ElicitationMiddleware) SetSemanticProvider added in v0.21.0 

func (em *ElicitationMiddleware) SetSemanticProvider(p semantic.Provider)

SetSemanticProvider updates the semantic provider (called after toolkit init).

type ErrorSanitizerMiddleware added in v1.96.0 

type ErrorSanitizerMiddleware struct{}

ErrorSanitizerMiddleware scrubs internal topology from upstream engine errors before they reach tool callers. The full original error is logged at debug level for operators.

func (*ErrorSanitizerMiddleware) After added in v1.96.0 

func (*ErrorSanitizerMiddleware) After(_ context.Context, tc *trinotools.ToolContext, result *mcp.CallToolResult, handlerErr error) (*mcp.CallToolResult, error)

After sanitizes the handler error and any error-result text.

func (*ErrorSanitizerMiddleware) Before added in v1.96.0 

func (*ErrorSanitizerMiddleware) Before(ctx context.Context, _ *trinotools.ToolContext) (context.Context, error)

Before implements trinotools.ToolMiddleware; it passes through unchanged.

type ExportAsset added in v1.56.0 

type ExportAsset struct {
	ID             string
	OwnerID        string
	OwnerEmail     string
	Name           string
	Description    string
	ContentType    string
	S3Bucket       string
	S3Key          string
	SizeBytes      int64
	Tags           []string
	Provenance     ExportProvenance
	SessionID      string
	IdempotencyKey string
}

ExportAsset is the asset data needed for insert.

type ExportAssetRef added in v1.56.0 

type ExportAssetRef struct {
	ID        string
	SizeBytes int64
}

ExportAssetRef is returned by idempotency key lookup.

type ExportAssetStore added in v1.56.0 

type ExportAssetStore interface {
	InsertExportAsset(ctx context.Context, asset ExportAsset) error
	GetByIdempotencyKey(ctx context.Context, ownerID, key string) (*ExportAssetRef, error)
}

ExportAssetStore is the subset of portal.AssetStore needed by trino_export. Defined here to avoid import cycles (portal → registry → trino).

type ExportConfig added in v1.56.0 

type ExportConfig struct {
	MaxRows        int           `yaml:"max_rows"`
	MaxBytes       int64         `yaml:"max_bytes"`
	DefaultTimeout time.Duration `yaml:"default_timeout"`
	MaxTimeout     time.Duration `yaml:"max_timeout"`
}

ExportConfig holds configuration for the trino_export tool.

type ExportDeps added in v1.56.0 

type ExportDeps struct {
	AssetStore   ExportAssetStore
	VersionStore ExportVersionStore
	S3Client     ExportS3Client
	ShareCreator ExportShareCreator // nil = public link creation disabled
	// ResourceLander lands a result in a managed resource by path instead of in
	// a new asset (#1663). nil leaves the asset destination the only one, which
	// is what a deployment with no managed-resource library has.
	ResourceLander toolkit.ResourceLander
	S3Bucket       string
	S3Prefix       string
	BaseURL        string
	Config         ExportConfig

	// GetUserContext extracts user identity from the request context.
	// Injected by the platform to avoid importing middleware.
	GetUserContext func(ctx context.Context) *ExportUserContext
}

ExportDeps holds portal-side dependencies injected into the Trino toolkit. All types are defined locally to avoid import cycles (portal → registry → trino).

type ExportProvenance added in v1.56.0 

type ExportProvenance struct {
	ToolCalls []ExportProvenanceCall
	SessionID string
	UserID    string
}

ExportProvenance records provenance for an exported asset.

type ExportProvenanceCall added in v1.56.0 

type ExportProvenanceCall struct {
	ToolName   string
	Timestamp  string
	Parameters map[string]any
}

ExportProvenanceCall represents a tool call in the provenance chain.

type ExportS3Client added in v1.56.0 

type ExportS3Client interface {
	PutObject(ctx context.Context, bucket, key string, data []byte, contentType string) error
}

ExportS3Client is the subset of portal.S3Client needed by trino_export.

type ExportShareCreator added in v1.56.0 

type ExportShareCreator interface {
	CreatePublicShare(ctx context.Context, assetID, createdBy string) (shareURL string, err error)
}

ExportShareCreator creates public share links for exported assets.

type ExportUserContext added in v1.56.0 

type ExportUserContext struct {
	UserID    string
	UserEmail string
	SessionID string
}

ExportUserContext holds user identity extracted from the request context.

type ExportVersion added in v1.56.0 

type ExportVersion struct {
	ID            string
	AssetID       string
	S3Key         string
	S3Bucket      string
	ContentType   string
	SizeBytes     int64
	CreatedBy     string
	ChangeSummary string
}

ExportVersion is the version data for creating a new version.

type ExportVersionStore added in v1.56.0 

type ExportVersionStore interface {
	CreateExportVersion(ctx context.Context, version ExportVersion) (int, error)
}

ExportVersionStore is the subset of portal.VersionStore needed by trino_export.

type Formatter added in v1.56.0 

type Formatter interface {
	// Format serializes columns and rows into the target format.
	Format(columns []string, rows [][]any) ([]byte, error)
	// ContentType returns the MIME type for the formatted output.
	ContentType() string
	// FileExtension returns the file extension (including dot) for the format.
	FileExtension() string
}

Formatter converts query results into a specific output format.

func NewFormatter added in v1.121.0 

func NewFormatter(format string) (Formatter, error)

NewFormatter returns a Formatter for the given format name. Supported formats: csv, json, markdown, text.

It is exported because trino_export is not the only writer of these formats: a managed script's platform.export writes the same four from rows it computed itself, and it writes them with this implementation rather than a second one that would drift. The format an author sees in a draft preview is therefore byte-for-byte the format a platform run persists.

type MultiConfig added in v0.26.0 

type MultiConfig struct {
	// DefaultConnection is the name of the default connection.
	DefaultConnection string

	// Instances maps connection names to their parsed configurations.
	Instances map[string]Config
}

MultiConfig holds configuration for a multi-connection Trino toolkit.

func ParseMultiConfig added in v0.26.0 

func ParseMultiConfig(defaultName string, instances map[string]map[string]any) (MultiConfig, error)

ParseMultiConfig builds a MultiConfig from the aggregate factory's instance map.

type PIIConsentConfig added in v0.21.0 

type PIIConsentConfig struct {
	Enabled bool `yaml:"enabled"`
}

PIIConsentConfig configures PII access consent.

type ProgressInjector added in v0.20.0 

type ProgressInjector struct{}

ProgressInjector is a trinotools.ToolMiddleware that creates an mcpProgressNotifier per-request from the ServerSession and progress token stored in context by MCPToolCallMiddleware.

func (*ProgressInjector) After added in v0.20.0 

func (*ProgressInjector) After(
	_ context.Context,
	_ *trinotools.ToolContext,
	result *mcp.CallToolResult,
	handlerErr error,
) (*mcp.CallToolResult, error)

After is a no-op — progress notifications are sent during tool execution, not after.

func (*ProgressInjector) Before added in v0.20.0 

func (*ProgressInjector) Before(ctx context.Context, _ *trinotools.ToolContext) (context.Context, error)

Before reads the server session and progress token from context and, if both are present, creates an mcpProgressNotifier and stores it in context via trinotools.WithProgressNotifier.

type ReadOnlyInterceptor added in v0.2.0 

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

ReadOnlyInterceptor blocks write operations on read-only connections. It delegates write detection to the upstream mcp-trino IsWriteSQL function.

A multi-connection toolkit routes every one of its connections through a single interceptor, so the decision is per connection: Before records the connection the call named — or the default connection, when it named none, matching multiserver.Manager.Client("") — on the context, and Intercept rejects write SQL unless that connection is configured write-capable. Such an interceptor therefore registers as both a query interceptor and a tool middleware; with only the interceptor registered no connection resolves and every write is refused, so a wiring mistake closes the door rather than opening it.

A nil readOnly map means every connection is read-only unconditionally. That is the single-connection case, where the connection argument selects nothing, and trino_export, which is SELECT-only whatever the deployment configures.

func NewConnectionReadOnlyInterceptor added in v1.120.1 

func NewConnectionReadOnlyInterceptor(defaultConn string, readOnly map[string]bool) *ReadOnlyInterceptor

NewConnectionReadOnlyInterceptor creates a query interceptor that rejects write SQL only on the connections whose readOnly entry is true. defaultConn names the connection a call that omits the connection argument resolves to.

func NewReadOnlyInterceptor added in v0.2.0 

func NewReadOnlyInterceptor() *ReadOnlyInterceptor

NewReadOnlyInterceptor creates a query interceptor that rejects write SQL on every connection.

func (*ReadOnlyInterceptor) AcceptsWrites added in v1.126.0 

func (i *ReadOnlyInterceptor) AcceptsWrites(conn string) bool

AcceptsWrites reports whether a named connection may run write SQL, asked ahead of time rather than from inside a call.

It is checkWritable's question with the connection supplied instead of resolved from the context, and it answers identically: an interceptor with no per-connection settings refuses, a name it holds no setting for is not one the toolkit routes to and refuses, and a connection marked read-only refuses. A surface that offers a connection has to reach the same answer this will reach when the statement runs, or it offers a choice the write then refuses.

func (*ReadOnlyInterceptor) After added in v1.120.1 

func (*ReadOnlyInterceptor) After(
	_ context.Context,
	_ *trinotools.ToolContext,
	result *mcp.CallToolResult,
	handlerErr error,
) (*mcp.CallToolResult, error)

After is a no-op — enforcement happens in Intercept, before execution.

func (*ReadOnlyInterceptor) Before added in v1.120.1 

func (i *ReadOnlyInterceptor) Before(ctx context.Context, tc *trinotools.ToolContext) (context.Context, error)

Before records the connection this tool call is bound for so Intercept can apply that connection's read-only setting.

func (*ReadOnlyInterceptor) ForgetConnection added in v1.120.1 

func (i *ReadOnlyInterceptor) ForgetConnection(name string)

ForgetConnection drops a removed connection's read-only setting.

func (*ReadOnlyInterceptor) Intercept added in v0.2.0 

func (i *ReadOnlyInterceptor) Intercept(ctx context.Context, sql string, _ trinotools.ToolName) (string, error)

Intercept checks if the query is a write operation and blocks it when the connection it is bound for may not accept writes.

func (*ReadOnlyInterceptor) SetConnection added in v1.120.1 

func (i *ReadOnlyInterceptor) SetConnection(name string, readOnly bool)

SetConnection records whether a connection added at runtime is read-only. A no-op on the unconditional interceptor, where every connection already is.

type ScratchConfig added in v1.125.0 

type ScratchConfig struct {
	Catalog string `yaml:"catalog"`
	Schema  string `yaml:"schema"`
}

ScratchConfig names where a table registration writes on a connection.

It is a target, not a boundary: the platform's read_only flag is a statement-prefix denylist and nothing in this toolkit restricts a catalog or schema, so what keeps a registration off the warehouse is the Trino identity the connection authenticates as, not these two fields.

func (ScratchConfig) Configured added in v1.125.0 

func (s ScratchConfig) Configured() bool

Configured reports whether this target names somewhere to write.

type Toolkit 

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

Toolkit wraps mcp-trino toolkit for the platform.

func New 

func New(name string, cfg Config) (*Toolkit, error)

New creates a new Trino toolkit.

func NewMulti added in v0.26.0 

func NewMulti(cfg MultiConfig) (*Toolkit, error)

NewMulti creates a multi-connection Trino toolkit that routes requests to the correct backend based on the "connection" parameter in each tool call. This replaces the previous pattern of creating N separate single-client toolkits that would clobber each other's tool registrations.

func (*Toolkit) AcceptsWrites added in v1.126.0 

func (t *Toolkit) AcceptsWrites(connection string) bool

AcceptsWrites reports whether Exec would be allowed to run write SQL on a connection, without running any.

It mirrors checkExecWritable exactly, including the two asymmetries that are easy to get backwards: a toolkit with no interceptor at all is a single-connection toolkit that was not configured read-only, so writes are ALLOWED; and an empty connection name resolves to the default, as it does everywhere else here.

It exists so a surface can decline to offer a connection whose registration would be refused at DDL time. A form offering a connection the registration then refuses is the same defect as a registration refusing a connection the form offered.

func (*Toolkit) AddConnection added in v1.48.0 

func (t *Toolkit) AddConnection(name string, config map[string]any) error

AddConnection adds a named connection at runtime. Requires multi-connection mode (created via NewMulti).

func (*Toolkit) Client 

func (t *Toolkit) Client() *trinoclient.Client

Client returns the underlying Trino client for direct use.

func (*Toolkit) Close 

func (t *Toolkit) Close() error

Close releases resources.

func (*Toolkit) Config 

func (t *Toolkit) Config() Config

Config returns the toolkit configuration.

func (*Toolkit) Connection added in v0.12.1 

func (t *Toolkit) Connection() string

Connection returns the name a tool call binds when it names none: the identity audit records it under, a persona's connection rules match, and the connection source map is keyed by.

That name is the instance name in both modes. The multi-connection manager routes by instance, and this toolkit reports its connections by instance through ListConnections, so config.ConnectionName is a label nothing else in the platform can reach: returning it named a connection no persona rule could match, no `connection` argument could carry, and no source-map lookup could resolve (#1396).

func (*Toolkit) Exec added in v1.125.0 

func (t *Toolkit) Exec(ctx context.Context, connection, sql string) error

Exec runs a statement against a named connection and discards its rows.

It is the platform's one write path into Trino. The two direct callers of Manager().Client(name).Query -- the HTTP query func and trino_export -- run SELECT and reach the client without passing the read-only check, so neither is a model for a statement that writes. Exec runs the same ReadOnlyInterceptor the MCP tools run, against the same per-connection read_only settings that AddConnection and RemoveConnection maintain, so a read_only connection refuses DDL here exactly as trino_execute would.

Authorization above this line is the caller's: Exec asks whether the connection accepts writes, never whether this person may use it.

func (*Toolkit) HasConnection added in v1.48.0 

func (t *Toolkit) HasConnection(name string) bool

HasConnection returns true if a connection with the given name exists.

func (*Toolkit) Kind 

func (*Toolkit) Kind() string

Kind returns the toolkit kind.

func (*Toolkit) ListConnections added in v0.26.0 

func (t *Toolkit) ListConnections() []toolkit.ConnectionDetail

ListConnections returns details for all connections managed by this toolkit. Implements toolkit.ConnectionLister.

func (*Toolkit) Manager added in v1.57.0 

func (t *Toolkit) Manager() *multiserver.Manager

Manager returns the multi-connection manager when the toolkit was constructed in multi-mode (the typical platform startup path). Returns nil for single-connection toolkits. Callers that need a per-connection client (gateway enrichment, cross-toolkit lookups) use this to look up a client by name.

func (*Toolkit) Name 

func (t *Toolkit) Name() string

Name returns the toolkit instance name.

func (*Toolkit) RegisterTools 

func (t *Toolkit) RegisterTools(s *mcp.Server)

RegisterTools registers Trino tools with the MCP server. The platform provides a unified list_connections tool, so the per-toolkit trino_list_connections is excluded.

func (*Toolkit) RemoveConnection added in v1.48.0 

func (t *Toolkit) RemoveConnection(name string) error

RemoveConnection removes a named connection at runtime. Requires multi-connection mode (created via NewMulti).

func (*Toolkit) ScratchTarget added in v1.125.0 

func (t *Toolkit) ScratchTarget(connection string) (ScratchConfig, bool)

ScratchTarget returns the catalog and schema table registrations write into on a connection, and whether that connection has one. An empty name resolves to the default connection, matching multiserver.Manager.Client("").

func (*Toolkit) SetExportDeps added in v1.56.0 

func (t *Toolkit) SetExportDeps(deps ExportDeps)

SetExportDeps injects portal dependencies for trino_export.

func (*Toolkit) SetQueryProvider 

func (t *Toolkit) SetQueryProvider(provider query.Provider)

SetQueryProvider sets the query execution provider for enrichment.

func (*Toolkit) SetSemanticProvider 

func (t *Toolkit) SetSemanticProvider(provider semantic.Provider)

SetSemanticProvider sets the semantic metadata provider for enrichment.

func (*Toolkit) TableExists added in v1.126.6 

func (t *Toolkit) TableExists(ctx context.Context, connection, catalog, schema, table string) (bool, error)

TableExists reports whether a catalog on a connection holds a table, by asking its information_schema rather than by querying the table: a table that exists but cannot be read is still a table, and one whose metadata is gone is not, whatever its files say.

It is a read, so it runs past no write check; the identifiers come from a registration row and are quoted here rather than trusted, because the connection's catalog names them and this is the one place they meet SQL text.

func (*Toolkit) Tools 

func (t *Toolkit) Tools() []string

Tools returns the list of tool names that would be provided by this toolkit.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.