redshiftdata

package
v1.1.4 Latest Latest
Warning

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

Go to latest
Published: Jul 20, 2026 License: MIT Imports: 18 Imported by: 0

README

Redshift Data

Parity grade: A · SDK aws-sdk-go-v2/service/redshiftdata@v1.41.0 · last audited 2026-07-13 (1c45a3ba)

Coverage

Metric Value
Operations audited 11 (7 ok, 4 gap)
Feature families 1 (1 ok)
Known gaps 4
Deferred items 1
Resource leaks clean
Known gaps
  • CancelStatement can never succeed against this backend: ExecuteStatement/BatchExecuteStatement set Status=FINISHED synchronously, so by the time a client calls CancelStatement the statement is always already terminal and CancelStatement always returns ErrTerminalState (ValidationException). This matches real AWS semantics ("To be canceled, a query must be running") given the backend's synchronous-completion design, and is already covered by TestRefinement3_CancelStatement_NotFound-style tests; flagged here only because a caller relying on "start statement then cancel it" integration pattern will never see a successful cancel. Not fixed this pass -- would require modeling async statement execution (a state machine with a delay before reaching FINISHED), which is a larger behavioral change beyond a wire-shape/bug-fix pass.
  • ValidateConnectionTarget (backend.go) enforces "exactly one of ClusterIdentifier/WorkgroupName" per real AWS constraints but is never called from any handler. ExecuteStatement/BatchExecuteStatement handlers are intentionally permissive (see TestHandler_ExecuteStatement_AllowsBothClusterAndWorkgroup / AllowsNeitherClusterNorWorkgroup in handler_parity_test.go, added in a prior sweep) -- this looks like a deliberate relaxation for ease of testing rather than an oversight, so left as-is. Re-review if strict AWS-parity validation becomes a priority.
  • DescribeStatement does not return RedshiftPid (optional field, always absent instead of 0); DbGroups/SessionId not returned by ExecuteStatement/BatchExecuteStatement. All are optional wire fields the real client zero-values when absent, so not a functional gap, just lower fidelity.
  • ListStatements items include several fields (ClusterIdentifier, WorkgroupName, Database, DbUser, HasResultSet, Duration) that don't exist on the real StatementData shape at all. The AWS SDK's JSON deserializer silently discards unknown keys, so this is harmless today, but flagged in case a future SDK version repurposes one of those key names.
Deferred
  • none

More

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrNotFound is returned when a statement does not exist.
	ErrNotFound = awserr.New("ResourceNotFoundException", awserr.ErrNotFound)
	// ErrTerminalState is returned when cancelling a statement that is already in a terminal state.
	ErrTerminalState = awserr.New("ValidationException", awserr.ErrConflict)
	// ErrValidation is returned when input validation fails.
	ErrValidation = awserr.New("ValidationException", awserr.ErrInvalidParameter)
	// ErrNoResultSet is returned when fetching results for a statement with no result set.
	ErrNoResultSet = awserr.New("ValidationException", awserr.ErrInvalidParameter)
)
View Source
var ErrNilAppContext = errors.New("nil AppContext passed to RedshiftData Provider.Init")

ErrNilAppContext is returned by Init when a nil AppContext is passed.

Functions

func ValidateConnectionTarget

func ValidateConnectionTarget(clusterIdentifier, workgroupName string) error

ValidateConnectionTarget verifies that exactly one of clusterIdentifier or workgroupName is provided, matching the AWS constraint.

func ValidateListStatementsStatus

func ValidateListStatementsStatus(status string) error

ValidateListStatementsStatus returns ErrValidation if status is not a known value. An empty string is also accepted (matches FINISHED per AWS default).

Types

type ConfigProvider

type ConfigProvider interface {
	GetRedshiftDataSettings() Settings
}

ConfigProvider is a private interface to extract Redshift Data configuration from the abstract AppContext Config.

type Handler

type Handler struct {
	Backend StorageBackend

	AccountID string
	Region    string
	// contains filtered or unexported fields
}

Handler is the HTTP handler for the AWS Redshift Data API.

func NewHandler

func NewHandler(backend StorageBackend) *Handler

NewHandler creates a new Redshift Data handler.

func (*Handler) ChaosOperations

func (h *Handler) ChaosOperations() []string

ChaosOperations returns all operations that can be fault-injected.

func (*Handler) ChaosRegions

func (h *Handler) ChaosRegions() []string

ChaosRegions returns all regions this handler handles.

func (*Handler) ChaosServiceName

func (h *Handler) ChaosServiceName() string

ChaosServiceName returns the lowercase AWS service name for fault rule matching.

func (*Handler) ExtractOperation

func (h *Handler) ExtractOperation(c *echo.Context) string

ExtractOperation extracts the operation name from the X-Amz-Target header.

func (*Handler) ExtractResource

func (h *Handler) ExtractResource(c *echo.Context) string

ExtractResource extracts the statement ID from the request body.

func (*Handler) GetSupportedOperations

func (h *Handler) GetSupportedOperations() []string

GetSupportedOperations returns the list of supported Redshift Data operations.

func (*Handler) Handler

func (h *Handler) Handler() echo.HandlerFunc

Handler returns the Echo handler function for Redshift Data requests.

func (*Handler) MatchPriority

func (h *Handler) MatchPriority() int

MatchPriority returns the routing priority.

func (*Handler) Name

func (h *Handler) Name() string

Name returns the service name.

func (*Handler) Reset

func (h *Handler) Reset()

Reset clears all backend state. Useful for test isolation.

func (*Handler) Restore

func (h *Handler) Restore(ctx context.Context, data []byte) error

Restore implements persistence.Persistable by delegating to the backend.

func (*Handler) RouteMatcher

func (h *Handler) RouteMatcher() service.Matcher

RouteMatcher returns a function that matches Redshift Data API requests. Requests are identified by the X-Amz-Target header prefix "RedshiftData.".

func (*Handler) Snapshot

func (h *Handler) Snapshot(ctx context.Context) []byte

Snapshot implements persistence.Persistable by delegating to the backend. Before this, Handler had no Snapshot/Restore of its own, so redshiftdata was silently excluded from Gopherstack's persistence.Manager (it type- asserts each service's Registerable to persistence.Persistable) even though InMemoryBackend fully implemented both methods -- a dead-wiring bug fixed as part of the Phase 3.3 rollout.

func (*Handler) StartWorker

func (h *Handler) StartWorker(ctx context.Context) error

StartWorker starts the background janitor if configured.

func (*Handler) WithJanitor

func (h *Handler) WithJanitor(interval, statementTTL time.Duration, taskTimeout ...time.Duration) *Handler

WithJanitor attaches a background janitor to the handler. If the backend is not an *InMemoryBackend, this is a no-op.

type InMemoryBackend

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

InMemoryBackend is an in-memory store for Redshift Data API statements. All regional resource maps are nested by region (outer key = region) so that the same-named statement in two regions are fully isolated.

func NewInMemoryBackend

func NewInMemoryBackend(accountID, region string) *InMemoryBackend

NewInMemoryBackend creates a new in-memory Redshift Data backend.

func (*InMemoryBackend) AccountID

func (b *InMemoryBackend) AccountID() string

AccountID returns the AWS account ID this backend is configured for.

func (*InMemoryBackend) BatchExecuteStatement

func (b *InMemoryBackend) BatchExecuteStatement(
	ctx context.Context,
	sqls []string, clusterIdentifier, workgroupName, database, dbUser, secretARN, statementName string,
	withEvent bool, resultFormat string,
) (*Statement, error)

BatchExecuteStatement creates and immediately completes a batch SQL statement.

func (*InMemoryBackend) CancelStatement

func (b *InMemoryBackend) CancelStatement(ctx context.Context, id string) error

CancelStatement marks a statement as aborted.

func (*InMemoryBackend) DescribeStatement

func (b *InMemoryBackend) DescribeStatement(ctx context.Context, id string) (*Statement, error)

DescribeStatement returns the details of a statement by ID.

func (*InMemoryBackend) EvictExpiredStatements

func (b *InMemoryBackend) EvictExpiredStatements(cutoff time.Time) int

EvictExpiredStatements removes terminal statements whose UpdatedAt is older than the given cutoff across all regions. Returns the number of evicted statements. Only terminal states (FINISHED, FAILED, ABORTED) are eligible for eviction.

func (*InMemoryBackend) ExecuteStatement

func (b *InMemoryBackend) ExecuteStatement(
	ctx context.Context,
	sql, clusterIdentifier, workgroupName, database, dbUser, secretARN, statementName string,
	withEvent bool, resultFormat string,
	parameters []SQLParameter,
) (*Statement, error)

ExecuteStatement creates and immediately completes a SQL statement.

func (*InMemoryBackend) ListStatements

func (b *InMemoryBackend) ListStatements(
	ctx context.Context,
	filter ListStatementsFilter,
) ([]*Statement, string, error)

ListStatements returns statements sorted by creation time (newest first). An omitted Status matches AWS by returning only finished statements. Returns the page slice and a next-token string (non-empty when more pages exist).

func (*InMemoryBackend) Region

func (b *InMemoryBackend) Region() string

Region returns the AWS region this backend is configured for.

func (*InMemoryBackend) Reset

func (b *InMemoryBackend) Reset()

Reset clears all stored statements across all regions.

func (*InMemoryBackend) Restore

func (b *InMemoryBackend) Restore(ctx context.Context, data []byte) error

Restore loads backend state from a JSON snapshot. It implements persistence.Persistable.

func (*InMemoryBackend) Snapshot

func (b *InMemoryBackend) Snapshot(ctx context.Context) []byte

Snapshot serializes the backend state to JSON. It implements persistence.Persistable.

type Janitor

type Janitor struct {
	Backend      *InMemoryBackend
	Interval     time.Duration
	StatementTTL time.Duration
	// TaskTimeout bounds each individual sweep task. When zero, each task runs
	// without a deadline. When non-zero, a child context with this timeout is
	// created for each sweep pass, preventing a stalled operation from blocking
	// the janitor loop indefinitely.
	TaskTimeout time.Duration
}

Janitor is the Redshift Data background worker that evicts completed statements after a configurable TTL to prevent unbounded growth of in-memory state. It complements the ring-buffer cap: the ring buffer evicts by count, the janitor evicts by age.

func NewJanitor

func NewJanitor(backend *InMemoryBackend, interval, statementTTL time.Duration) *Janitor

NewJanitor creates a new Janitor for the given backend. Zero values for interval or statementTTL fall back to package defaults.

func (*Janitor) Run

func (j *Janitor) Run(ctx context.Context)

Run runs the janitor loop until ctx is cancelled. It should be started in a goroutine: go janitor.Run(ctx).

func (*Janitor) SweepOnce

func (j *Janitor) SweepOnce(ctx context.Context)

SweepOnce runs a single sweep pass. Exposed for testing.

type ListStatementsFilter

type ListStatementsFilter struct {
	ClusterIdentifier string
	WorkgroupName     string
	Database          string
	StatementName     string
	Status            string
	NextToken         string
	MaxResults        int
}

ListStatementsFilter controls statement filtering and pagination.

type Provider

type Provider struct{}

Provider implements service.Provider for AWS Redshift Data.

func (*Provider) Init

Init initializes the Redshift Data service backend and handler.

func (*Provider) Name

func (p *Provider) Name() string

Name returns the provider name.

type SQLParameter

type SQLParameter struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

SQLParameter is a named SQL parameter for use in parameterized queries, matching the SQLParameter type in the AWS Redshift Data API.

type Settings

type Settings struct {
	JanitorInterval time.Duration `json:"janitor_interval" env:"REDSHIFTDATA_JANITOR_INTERVAL" default:"1m"  help:"Janitor tick interval."` //nolint:lll // Kong struct tag makes this line long
	StatementTTL    time.Duration ``                                                                                                        //nolint:lll // Kong struct tag makes this line long
	/* 134-byte string literal not displayed */
}

Settings holds service-level configuration for the Redshift Data backend. Fields are picked up by the Kong CLI parser when this struct is embedded in the root CLI command.

type Statement

type Statement struct {
	CreatedAt         time.Time          `json:"createdAt"`
	UpdatedAt         time.Time          `json:"updatedAt"`
	Database          string             `json:"database"`
	ID                string             `json:"id"`
	ClusterIdentifier string             `json:"clusterIdentifier"`
	WorkgroupName     string             `json:"workgroupName"`
	QueryString       string             `json:"queryString"`
	DBUser            string             `json:"dbUser"`
	SecretARN         string             `json:"secretARN"`
	StatementName     string             `json:"statementName"`
	ResultFormat      string             `json:"resultFormat"`
	Status            string             `json:"status"`
	Error             string             `json:"error"`
	QueryStrings      []string           `json:"queryStrings"`
	Parameters        []SQLParameter     `json:"parameters,omitempty"`
	SubStatements     []SubStatementData `json:"subStatements,omitempty"`
	// DurationMs is the total wall-clock execution time in milliseconds. Populated
	// when the statement reaches a terminal state (FINISHED / FAILED / ABORTED).
	DurationMs       int64 `json:"durationMs"`
	ResultRows       int64 `json:"resultRows"`
	ResultSize       int64 `json:"resultSize"`
	HasResultSet     bool  `json:"hasResultSet"`
	IsBatchStatement bool  `json:"isBatchStatement"`
	// WithEvent indicates whether an EventBridge event is generated on completion.
	WithEvent bool `json:"withEvent"`
}

Statement represents an AWS Redshift Data API SQL statement.

type StorageBackend

type StorageBackend interface {
	// Statement execution
	ExecuteStatement(
		ctx context.Context,
		sql, clusterIdentifier, workgroupName, database, dbUser, secretARN, statementName string,
		withEvent bool, resultFormat string,
		parameters []SQLParameter,
	) (*Statement, error)
	BatchExecuteStatement(
		ctx context.Context,
		sqls []string, clusterIdentifier, workgroupName, database, dbUser, secretARN, statementName string,
		withEvent bool, resultFormat string,
	) (*Statement, error)

	// Statement inspection
	DescribeStatement(ctx context.Context, id string) (*Statement, error)
	CancelStatement(ctx context.Context, id string) error
	// ListStatements returns a page of statements and a next-token for pagination.
	ListStatements(ctx context.Context, filter ListStatementsFilter) (
		[]*Statement, string, error,
	)

	// Maintenance
	// EvictExpiredStatements removes terminal statements older than cutoff.
	// Returns the number of evicted statements.
	EvictExpiredStatements(cutoff time.Time) int

	// Lifecycle
	Reset()
	Region() string
	AccountID() string
	Snapshot(ctx context.Context) []byte
	Restore(ctx context.Context, data []byte) error
}

StorageBackend defines the interface for Redshift Data backend implementations. All methods must be safe for concurrent use.

type SubStatementData

type SubStatementData struct {
	ID           string    `json:"id"`
	CreatedAt    time.Time `json:"createdAt"`
	UpdatedAt    time.Time `json:"updatedAt"`
	QueryString  string    `json:"queryString"`
	Status       string    `json:"status"`
	Error        string    `json:"error"`
	HasResultSet bool      `json:"hasResultSet"`
	ResultRows   int64     `json:"resultRows"`
	ResultSize   int64     `json:"resultSize"`
	DurationMs   int64     `json:"durationMs"`
}

SubStatementData represents a single sub-statement within a batch, matching the SubStatementData shape returned by AWS DescribeStatement for batch runs.

Jump to

Keyboard shortcuts

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