sql

Documentation

Overview

Package sql provides a client for executing SQL operations through the Tarmac host runtime.

The client supports Exec for statements that do not return rows and Query for statements that return rows. Requests and responses are encoded with project protobufs and sent through waPC host calls.

Errors are returned as package sentinels and SDK host errors so callers can use errors.Is and errors.As for precise handling. Host partial-result responses are surfaced as ErrPartialResult with a PartialResultError that retains operation context and cause details.

Index

• Variables
• type Client
• type Config
• type DBClient
  • func New(config Config) (*DBClient, error)
  • func (c *DBClient) Close() error
  • func (c *DBClient) Exec(query string) (ExecResult, error)
  • func (c *DBClient) Query(query string) (QueryResult, error)
• type ExecResult
• type HostCall
• type PartialResultError
  • func (e *PartialResultError) Error() string
  • func (e *PartialResultError) Unwrap() []error
• type QueryResult

Variables

var (
	// ErrInvalidQuery indicates an empty or invalid SQL query.
	ErrInvalidQuery = errors.New("query is invalid")

	// ErrPartialResult indicates the host returned a partial result.
	ErrPartialResult = errors.New("operation completed with partial result")

	// ErrMarshalRequest wraps failures while encoding the request payload.
	ErrMarshalRequest = errors.New("failed to marshal request")

	// ErrUnmarshalResponse wraps failures while decoding the host response.
	ErrUnmarshalResponse = errors.New("failed to unmarshal response")
)

Types

type Client

type Client interface {
	// Exec executes a SQL statement that does not return rows.
	Exec(query string) (ExecResult, error)

	// Query executes a SQL statement that returns rows.
	Query(query string) (QueryResult, error)

	// Close releases resources held by the client.
	Close() error
}

Client defines the SQL capability interface.

type Config

type Config struct {
	// SDKConfig provides the runtime namespace used for host calls.
	SDKConfig sdk.RuntimeConfig

	// HostCall overrides the waPC host function used for SQL operations.
	HostCall HostCall
}

Config controls how a Client instance interacts with the host runtime.

type DBClient

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

DBClient is the SQL capability client implementation.

func New

func New(config Config) (*DBClient, error)

New creates a SQL client with namespace defaults and optional host-call override.

func (*DBClient) Close

func (c *DBClient) Close() error

Close releases resources held by the client.

func (*DBClient) Exec

func (c *DBClient) Exec(query string) (ExecResult, error)

Exec executes a SQL statement that does not return rows.

func (*DBClient) Query

func (c *DBClient) Query(query string) (QueryResult, error)

Query executes a SQL statement that returns rows.

type ExecResult

type ExecResult struct {
	// LastInsertID is the ID of the last inserted row, when available.
	LastInsertID int64
	// RowsAffected is the number of rows affected by the statement.
	RowsAffected int64
}

ExecResult mirrors the SQLExecResponse payload fields.

type HostCall

type HostCall func(string, string, string, []byte) ([]byte, error)

HostCall defines the waPC host function signature used by SQL operations.

type PartialResultError

type PartialResultError struct {
	Operation string
	Cause     error
}

PartialResultError indicates an operation completed with degraded metadata and includes the underlying cause reported by the host.

func (*PartialResultError) Error

func (e *PartialResultError) Error() string

Error returns a human-readable partial-result message.

func (*PartialResultError) Unwrap

func (e *PartialResultError) Unwrap() []error

Unwrap exposes both ErrPartialResult and the underlying cause to errors.Is/As.

type QueryResult

type QueryResult struct {
	// Columns are the column names returned by the query.
	Columns []string
	// Data is a JSON-encoded byte slice of the query result data.
	Data []byte
}

QueryResult mirrors the SQLQueryResponse payload fields.