db

package
v0.3.1 Latest Latest
Warning

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

 Go to latest Published: Mar 7, 2026 License: MIT Imports: 32 Imported by: 0

Documentation

Index

Constants

View Source 
const SystemCatalogName = "_system"

SystemCatalogName is the catalog name used for system types (scalars, directives). Using a named catalog instead of empty string prevents accidental collisions with types that don't specify a catalog.

Variables

View Source 
var ErrNoCompiler = errors.New("db provider: compiler not set (use NewWithCompiler)")

ErrNoCompiler is returned when CatalogManager methods are called on a Provider created without a compiler (use NewWithCompiler).

View Source 
var ErrReadOnly = errors.New("schema store is in read-only mode")

ErrReadOnly is returned when a write operation is attempted on a read-only provider.

Functions

func EmbeddingText 

func EmbeddingText(longDesc, desc, syntheticDesc string) string

EmbeddingText returns the best available text for embedding generation. Falls back through: longDesc → desc → syntheticDesc.

func SyntheticDescription 

func SyntheticDescription(hugrType, entityName, parentName, moduleName, catalog string) string

SyntheticDescription builds a fallback description from entity metadata. Used when no human-written description is available.

Types

type CacheConfig 

type CacheConfig struct {
	MaxEntries int
	TTL        time.Duration
}

CacheConfig controls the LRU cache behavior.

func DefaultCacheConfig 

func DefaultCacheConfig() CacheConfig

DefaultCacheConfig returns the default cache configuration.

type CatalogChecker 

type CatalogChecker interface {
	ExistsCatalog(name string) bool
}

CatalogChecker checks whether a catalog (data source) has an active engine.

type CatalogRecord 

type CatalogRecord struct {
	Name        string
	Version     string
	Description string
	Disabled    bool
	Suspended   bool
}

CatalogRecord holds metadata for a registered catalog.

type CatalogRuntimeSource 

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

CatalogRuntimeSource is the core.catalog runtime source backed by a Provider.

func (*CatalogRuntimeSource) AsModule 

func (s *CatalogRuntimeSource) AsModule() bool

func (*CatalogRuntimeSource) Attach 

func (s *CatalogRuntimeSource) Attach(_ context.Context, _ *dbpool.Pool) error

func (*CatalogRuntimeSource) Catalog 

func (s *CatalogRuntimeSource) Catalog(_ context.Context) (sources.Catalog, error)

func (*CatalogRuntimeSource) Engine 

func (s *CatalogRuntimeSource) Engine() engines.Engine

func (*CatalogRuntimeSource) IsReadonly 

func (s *CatalogRuntimeSource) IsReadonly() bool

func (*CatalogRuntimeSource) Name 

func (s *CatalogRuntimeSource) Name() string

type Config 

type Config struct {
	Cache       CacheConfig
	TablePrefix string // "core." for attached DuckDB, "" for native
	VecSize     int    // Embedding vector dimension; 0 = skip vec operations
	IsPostgres  bool   // true when CoreDB is PostgreSQL (affects vec column DDL)
	IsReadonly  bool   // true when CoreDB is read-only (rejects all writes)
}

Config holds all provider configuration.

type Connection 

type Connection = dbpkg.Connection

Connection is an alias for the db package Connection type.

type Embedder 

type Embedder interface {
	CreateEmbedding(ctx context.Context, input string) (types.Vector, error)
	CreateEmbeddings(ctx context.Context, inputs []string) ([]types.Vector, error)
}

Embedder is an optional dependency for computing embedding vectors. Defined in this package to avoid import cycles. The engine wires it to an EmbeddingSource at init time.

type Provider 

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

Provider is the DB-backed schema provider. It stores compiled GraphQL types in _schema_* tables and serves lookups via an LRU cache with DB fallback.

When a *compiler.Compiler is set (via NewWithCompiler), the provider also implements CatalogManager — managing catalog lifecycle (add/remove/ reload/disable/enable) with version-based skip-if-unchanged logic.

func New 

func New(ctx context.Context, pool *db.Pool, cfg Config, embedder Embedder) (*Provider, error)

New creates a new DB-backed schema provider.

It initializes the _schema_meta table (if not exists), checks vector dimension consistency, and prepares the LRU cache.

pool: *db.Pool for raw SQL access to CoreDB cfg: provider configuration (prefix, cache, vec size) embedder: optional (nil when embeddings not configured)

func NewWithCompiler 

func NewWithCompiler(ctx context.Context, pool *db.Pool, cfg Config, embedder Embedder, c *compiler.Compiler) (*Provider, error)

NewWithCompiler creates a DB-backed provider with CatalogManager support. The compiler is used for self-contained catalog compilation via AddCatalog/ReloadCatalog.

func (*Provider) AddCatalog 

func (p *Provider) AddCatalog(ctx context.Context, name string, catalog sources.Catalog) error

AddCatalog adds or updates a catalog with version-aware skip logic.

Flow:

  • Get version from source, check _schema_catalogs for existing record
  • Version match → skip compilation, store source handle only
  • Version mismatch → suspend dependents → drop schema objects → recompile
  • New catalog → compile and persist
  • After any change → reactivate suspended catalogs

func (*Provider) CatalogSource 

func (p *Provider) CatalogSource() *CatalogRuntimeSource

CatalogSource returns a RuntimeSource for the core.catalog module. The source exposes _schema_* tables as read-only GraphQL views.

func (*Provider) CleanOrphanedCatalogs 

func (p *Provider) CleanOrphanedCatalogs(ctx context.Context) error

CleanOrphanedCatalogs detects catalogs in _schema_catalogs that have no corresponding record in data_sources and are not runtime catalogs, then removes them. This handles the case where a data source was deleted via GraphQL mutation while the engine was stopped — its schema objects would otherwise remain stale in _schema_* tables.

Call after all runtime sources are registered via AddCatalog so that p.catalogs contains the full set of runtime catalog names to skip.

func (*Provider) Definitions 

func (p *Provider) Definitions(ctx context.Context) iter.Seq[*ast.Definition]

Definitions returns an iterator over all type definitions. Collects type names from DB first, then loads each definition via ForName (which uses cache + DB fallback).

func (*Provider) Description 

func (p *Provider) Description(_ context.Context) string

Description returns a static provider description.

func (*Provider) DirectiveDefinitions 

func (p *Provider) DirectiveDefinitions(ctx context.Context) iter.Seq2[string, *ast.DirectiveDefinition]

DirectiveDefinitions returns an iterator over all directive definitions.

func (*Provider) DirectiveForName 

func (p *Provider) DirectiveForName(ctx context.Context, name string) *ast.DirectiveDefinition

DirectiveForName returns the directive definition with the given name.

func (*Provider) DisableCatalog 

func (p *Provider) DisableCatalog(ctx context.Context, name string) error

DisableCatalog sets the disabled flag on a catalog without removing data.

func (*Provider) DropCatalog 

func (p *Provider) DropCatalog(ctx context.Context, name string, cascade bool) error

DropCatalog removes all types, fields, arguments, enum values, and metadata for the named catalog. If cascade is true, dependent catalogs are suspended.

Delete order: 

cascade suspension → schema objects → catalog_dependencies → catalog record

func (*Provider) EnableCatalog 

func (p *Provider) EnableCatalog(ctx context.Context, name string) error

EnableCatalog clears the disabled flag on a catalog.

func (*Provider) ExistsCatalog 

func (p *Provider) ExistsCatalog(name string) bool

ExistsCatalog checks whether a catalog exists, first in the in-memory source map, then falling back to the _schema_catalogs table.

func (*Provider) ForName 

func (p *Provider) ForName(ctx context.Context, name string) *ast.Definition

ForName returns the type definition with the given name. Checks LRU cache first, falls back to DB query. Returns nil if the type doesn't exist or its catalog is disabled/suspended.

func (*Provider) GetCatalog 

func (p *Provider) GetCatalog(ctx context.Context, name string) (*CatalogRecord, error)

GetCatalog returns the catalog record for the given name, or nil if not found.

func (*Provider) GetSchemaVersion 

func (p *Provider) GetSchemaVersion(ctx context.Context) (int64, error)

GetSchemaVersion returns the current schema version counter.

func (*Provider) HasEmbeddings 

func (p *Provider) HasEmbeddings() bool

HasEmbeddings returns true when the provider has an embedder and vec columns.

func (*Provider) Implements 

func (p *Provider) Implements(ctx context.Context, name string) iter.Seq[*ast.Definition]

Implements returns interfaces that the named type implements.

func (*Provider) IncrementSchemaVersion 

func (p *Provider) IncrementSchemaVersion(ctx context.Context) (int64, error)

IncrementSchemaVersion increments the schema version counter in _schema_settings and returns the new value. Called by management node after AddCatalog/RemoveCatalog/ReloadCatalog.

func (*Provider) InitSystemTypes 

func (p *Provider) InitSystemTypes(ctx context.Context) error

InitSystemTypes persists system scalars and directives (with catalog="") to the _schema_* tables. The version is checked against _schema_settings to skip re-persisting if nothing changed.

Called during engine bootstrap to ensure the DB provider can resolve basic types like Int, String, Boolean, etc.

func (*Provider) InvalidateAll 

func (p *Provider) InvalidateAll()

InvalidateAll purges the entire cache.

func (*Provider) InvalidateCatalog 

func (p *Provider) InvalidateCatalog(catalog string)

InvalidateCatalog evicts all cached entries for the given catalog name. Also evicts root types (Query, Mutation) since their fields may include module fields from the invalidated catalog. Types from other catalogs that had extension fields from this catalog will be refreshed from DB on next access (cache TTL or LRU eviction).

func (*Provider) IsInitialized 

func (p *Provider) IsInitialized(ctx context.Context) (bool, error)

IsInitialized checks whether the DB has been initialized with system types.

func (*Provider) IsReadonly 

func (p *Provider) IsReadonly() bool

IsReadonly returns whether this provider is in read-only mode.

func (*Provider) ListCatalogs 

func (p *Provider) ListCatalogs(ctx context.Context) ([]*CatalogRecord, error)

ListCatalogs returns all registered catalog records.

func (*Provider) MutationType 

func (p *Provider) MutationType(ctx context.Context) *ast.Definition

MutationType returns the Mutation root type definition.

func (*Provider) PossibleTypes 

func (p *Provider) PossibleTypes(ctx context.Context, name string) iter.Seq[*ast.Definition]

PossibleTypes returns implementations of an interface or union type.

func (*Provider) QueryType 

func (p *Provider) QueryType(ctx context.Context) *ast.Definition

QueryType returns the Query root type definition.

func (*Provider) RegisterUDFs 

func (p *Provider) RegisterUDFs(ctx context.Context, checker CatalogChecker) error

RegisterUDFs registers all schema management UDFs on the Provider's DB pool. The checker is used by _schema_hard_remove to verify the catalog is not loaded.

func (*Provider) ReindexEmbeddings 

func (p *Provider) ReindexEmbeddings(ctx context.Context, name string, batchSize int) (int, error)

ReindexEmbeddings recomputes embedding vectors for schema entities. If name is empty, all entities are reindexed. Otherwise, only entities from the specified catalog are reindexed. Returns the number of entities reindexed.

func (*Provider) ReloadCatalog 

func (p *Provider) ReloadCatalog(ctx context.Context, name string) error

ReloadCatalog reloads a catalog by name. If the source supports incremental changes (IncrementalCatalog), only the delta is compiled and applied. Otherwise falls back to full recompilation (drop + recompile).

func (*Provider) RemoveCatalog 

func (p *Provider) RemoveCatalog(ctx context.Context, name string) error

RemoveCatalog removes a catalog: suspends dependents, deletes all schema objects and the catalog record, and removes the source handle.

func (*Provider) ResetSummarized 

func (p *Provider) ResetSummarized(ctx context.Context, name, scope string) (int, error)

ResetSummarized clears the is_summarized flag so the summarizer re-processes entities.

scope controls granularity:

  • "all" — reset everything (name is ignored)
  • "catalog" — reset all types/fields/modules in the named catalog, plus the catalog record
  • "type" — reset the named type and its fields

func (*Provider) SetCatalogDescription 

func (p *Provider) SetCatalogDescription(ctx context.Context, name, desc, longDesc string) error

SetCatalogDescription updates a catalog's description and long description, and recomputes its embedding vector (if embedder is available).

func (*Provider) SetCatalogDisabled 

func (p *Provider) SetCatalogDisabled(ctx context.Context, name string, disabled bool) error

SetCatalogDisabled enables or disables a catalog.

func (*Provider) SetCatalogSuspended 

func (p *Provider) SetCatalogSuspended(ctx context.Context, name string, suspended bool) error

SetCatalogSuspended suspends or unsuspends a catalog.

func (*Provider) SetCatalogVersion 

func (p *Provider) SetCatalogVersion(ctx context.Context, name, version string) error

SetCatalogVersion updates the version of a catalog.

func (*Provider) SetDefinitionDescription 

func (p *Provider) SetDefinitionDescription(ctx context.Context, name, desc, longDesc string) error

SetDefinitionDescription updates a type's description and long description, and recomputes its embedding vector (if embedder is available).

func (*Provider) SetFieldDescription 

func (p *Provider) SetFieldDescription(ctx context.Context, typeName, fieldName, desc, longDesc string) error

SetFieldDescription updates a field's description and long description, and recomputes its embedding vector (if embedder is available).

func (*Provider) SetModuleDescription 

func (p *Provider) SetModuleDescription(ctx context.Context, name, desc, longDesc string) error

SetModuleDescription updates a module's description and long description, and recomputes its embedding vector (if embedder is available).

func (*Provider) SubscriptionType 

func (p *Provider) SubscriptionType(_ context.Context) *ast.Definition

SubscriptionType returns nil (subscriptions not supported).

func (*Provider) TablePrefix 

func (p *Provider) TablePrefix() string

TablePrefix returns the SQL table prefix (e.g. "core." for attached DuckDB).

func (*Provider) Types 

func (p *Provider) Types(ctx context.Context) iter.Seq2[string, *ast.Definition]

Types returns an iterator over all type (name, definition) pairs.

func (*Provider) Update 

func (p *Provider) Update(ctx context.Context, changes base.DefinitionsSource) error

Update persists compiled schema changes to the database.

Processes definitions (@drop, @replace, @if_not_exists, regular add) and extensions (field add/drop/replace, directive changes) within a single transaction. Computes hugr_type and embeddings. Reconciles module and data object metadata. Invalidates cache after commit.

The catalog name is extracted from the first definition with a @catalog directive.

func (*Provider) UpdateWithCatalog 

func (p *Provider) UpdateWithCatalog(ctx context.Context, changes base.DefinitionsSource, catalogOverride string) error

UpdateWithCatalog persists compiled schema changes with an explicit catalog name override. When catalogOverride is non-empty, it is used instead of extracting from @catalog directives. Used for system types which don't carry @catalog directives.

func (*Provider) UpdateWithCatalogAndOptions 

func (p *Provider) UpdateWithCatalogAndOptions(ctx context.Context, changes base.DefinitionsSource, catalogOverride string, opts *base.Options) error

UpdateWithCatalogAndOptions persists compiled schema changes with an explicit catalog name and compile options. Options are stored on the _schema_catalogs record so that catalog metadata (source_type, prefix, as_module, read_only) is available even for runtime catalogs that have no data_sources row.

func (*Provider) VecSize 

func (p *Provider) VecSize() int

VecSize returns the embedding vector dimension.

Source Files

View all Source files

Directories

Path Synopsis
Package schema provides serialization utilities for storing GraphQL schema metadata in database tables.
 Package schema provides serialization utilities for storing GraphQL schema metadata in database tables.

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.