backend

Documentation

Overview

Package backend defines the StorageBackend composite interface and factory. This package sits above pkg/agent, pkg/artifacts, pkg/shuttle, and pkg/storage to avoid import cycles while composing their individual store interfaces.

Copyright 2026 Teradata

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2026 Teradata

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2026 Teradata

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• type AdminStorageProvider
• type MigrationInspector
• type PendingMigration
• type SQLiteBackend
  • func NewSQLiteBackend(cfg *loomv1.SQLiteStorageConfig, tracer observability.Tracer) (*SQLiteBackend, error)
  • func (b *SQLiteBackend) ArtifactStore() artifacts.ArtifactStore
  • func (b *SQLiteBackend) Close() error
  • func (b *SQLiteBackend) ErrorStore() agent.ErrorStore
  • func (b *SQLiteBackend) HumanRequestStore() shuttle.HumanRequestStore
  • func (b *SQLiteBackend) Migrate(ctx context.Context) error
  • func (b *SQLiteBackend) Migrator() *sqlite.Migrator
  • func (b *SQLiteBackend) PendingMigrations(ctx context.Context) ([]*PendingMigration, error)
  • func (b *SQLiteBackend) Ping(ctx context.Context) error
  • func (b *SQLiteBackend) ResultStore() storage.ResultStore
  • func (b *SQLiteBackend) SessionStorage() agent.SessionStorage
  • func (b *SQLiteBackend) StorageDetails(ctx context.Context) (int32, *loomv1.PoolStats, error)
• type StorageBackend
  • func NewStorageBackend(ctx context.Context, cfg *loomv1.StorageConfig, tracer observability.Tracer) (StorageBackend, error)
• type StorageDetailProvider

Types

type AdminStorageProvider

type AdminStorageProvider interface {
	// AdminStorage returns the admin storage implementation, or nil if unavailable.
	AdminStorage() agent.AdminStorage

	// ValidateAdminPermissions checks that the admin connection has appropriate
	// database privileges (e.g., BYPASSRLS for PostgreSQL). Logs a warning if
	// the admin role lacks expected privileges but does not fail -- the admin
	// connection may still work if RLS policies allow the role.
	ValidateAdminPermissions(ctx context.Context) error
}

AdminStorageProvider is an optional interface that StorageBackend implementations may satisfy to expose cross-tenant administrative queries. Only PostgreSQL backends implement this; SQLite backends do not need multi-tenant admin.

type MigrationInspector

type MigrationInspector interface {
	// PendingMigrations returns the list of migrations that have not yet been
	// applied to the database. Each entry contains the version, description,
	// and SQL that would be executed.
	PendingMigrations(ctx context.Context) ([]*PendingMigration, error)
}

MigrationInspector is an optional interface that StorageBackend implementations may satisfy to provide introspection into pending database migrations. This is used by the RunMigration RPC in dry-run mode to report which migrations would be applied without actually running them.

type PendingMigration

type PendingMigration struct {
	// Version is the migration version number.
	Version int32
	// Description is a human-readable summary of the migration.
	Description string
	// SQL is the SQL that would be executed (may be empty for non-SQL migrations).
	SQL string
}

PendingMigration describes a single migration that has not yet been applied.

type SQLiteBackend

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

SQLiteBackend implements StorageBackend by wrapping existing SQLite stores. All stores share the same loom.db file via separate connections with WAL mode.

func NewSQLiteBackend

func NewSQLiteBackend(cfg *loomv1.SQLiteStorageConfig, tracer observability.Tracer) (*SQLiteBackend, error)

NewSQLiteBackend creates a new SQLite-backed storage backend. If cfg is nil, uses default paths ($LOOM_DATA_DIR/loom.db).

func (*SQLiteBackend) ArtifactStore

func (b *SQLiteBackend) ArtifactStore() artifacts.ArtifactStore

ArtifactStore returns the artifact store implementation.

func (*SQLiteBackend) Close

func (b *SQLiteBackend) Close() error

Close closes all underlying store connections.

func (*SQLiteBackend) ErrorStore

func (b *SQLiteBackend) ErrorStore() agent.ErrorStore

ErrorStore returns the error store implementation.

func (*SQLiteBackend) HumanRequestStore

func (b *SQLiteBackend) HumanRequestStore() shuttle.HumanRequestStore

HumanRequestStore returns the human request store implementation.

func (*SQLiteBackend) Migrate

func (b *SQLiteBackend) Migrate(ctx context.Context) error

Migrate applies all pending versioned schema migrations to the SQLite database. Individual stores still create their schemas via initSchema() during construction (using CREATE TABLE IF NOT EXISTS), so Migrate acts as an additional layer for tracking schema versions and applying future incremental migrations.

func (*SQLiteBackend) Migrator

func (b *SQLiteBackend) Migrator() *sqlite.Migrator

Migrator returns the underlying SQLite migrator for direct access.

func (*SQLiteBackend) PendingMigrations

func (b *SQLiteBackend) PendingMigrations(ctx context.Context) ([]*PendingMigration, error)

PendingMigrations implements MigrationInspector by delegating to the SQLite migrator.

func (*SQLiteBackend) Ping

func (b *SQLiteBackend) Ping(ctx context.Context) error

Ping verifies the SQLite database is accessible.

func (*SQLiteBackend) ResultStore

func (b *SQLiteBackend) ResultStore() storage.ResultStore

ResultStore returns the SQL result store implementation.

func (*SQLiteBackend) SessionStorage

func (b *SQLiteBackend) SessionStorage() agent.SessionStorage

SessionStorage returns the session storage implementation.

func (*SQLiteBackend) StorageDetails

func (b *SQLiteBackend) StorageDetails(ctx context.Context) (int32, *loomv1.PoolStats, error)

StorageDetails implements StorageDetailProvider by querying the migrator for the current schema version. Pool stats are nil for SQLite (not connection-pooled).

type StorageBackend

type StorageBackend interface {
	// SessionStorage returns the session storage implementation.
	SessionStorage() agent.SessionStorage

	// ErrorStore returns the error store implementation.
	ErrorStore() agent.ErrorStore

	// ArtifactStore returns the artifact store implementation.
	ArtifactStore() artifacts.ArtifactStore

	// ResultStore returns the SQL result store implementation.
	ResultStore() storage.ResultStore

	// HumanRequestStore returns the human request store implementation.
	HumanRequestStore() shuttle.HumanRequestStore

	// Migrate runs database migrations to the latest version.
	Migrate(ctx context.Context) error

	// Ping verifies the storage backend is reachable and healthy.
	Ping(ctx context.Context) error

	// Close closes all underlying connections.
	Close() error
}

StorageBackend is the top-level composed interface for all storage operations. One StorageBackend per server; all agents share the same backend. Implementations include SQLiteBackend and PostgresBackend.

func NewStorageBackend

func NewStorageBackend(ctx context.Context, cfg *loomv1.StorageConfig, tracer observability.Tracer) (StorageBackend, error)

NewStorageBackend creates a StorageBackend from proto configuration. If cfg is nil or backend is unspecified, defaults to SQLite with default paths. The ctx parameter is used for PostgreSQL connection initialization; it is ignored for SQLite backends.

type StorageDetailProvider

type StorageDetailProvider interface {
	// StorageDetails returns the current migration version and connection pool
	// statistics. poolStats may be nil for non-pooled backends (e.g., SQLite).
	StorageDetails(ctx context.Context) (migrationVersion int32, poolStats *loomv1.PoolStats, err error)
}

StorageDetailProvider is an optional interface that StorageBackend implementations may satisfy to provide detailed health information (migration version, pool stats) for the GetStorageStatus RPC. Backends that don't implement this return zeros/nil.