Documentation
¶
Overview ¶
Package vectorsearch generates the pgvector k-NN SQL function for one table column and mirrors its Hasura tracking entry (P7-ADOPT-07, EPIC ADOPT D7).
Purpose: apps reach similarity search through Hasura GraphQL only (ADR 0003). A STABLE SQL function that returns SETOF the source table keeps the table's select filter on every row, so no new access path, role or grant is needed. Inputs: a Spec (schema.table.column, distance, roles) and the project dir. Outputs: a migration file, an optional live tracking call and an optional on-disk metadata mirror. Constraints: identifiers pass database.SanitizeIdentifier; the generated SQL is built with text/template over validated values only; no Postgres role, grant or connection string is ever created; metadata is never replaced.
Index ¶
- Constants
- Variables
- func CheckFunctionShape(ctx context.Context, run Exec, pg PG, s Spec) error
- func InspectColumn(ctx context.Context, run Exec, pg PG, s Spec) (int, error)
- func MetadataDrift(ctx context.Context, cfg *config.Config, projectDir string) ([]string, error)
- func MirrorFunction(projectDir, schema, name string, roles []string) (file string, changed bool, err error)
- func ParseDim(formatType string) (int, error)
- func Render(s Spec) (string, error)
- type Deps
- type Distance
- type Exec
- type Options
- type PG
- type Result
- type Spec
Constants ¶
const DefaultRole = "user"
DefaultRole is the Hasura role granted when --roles is not given.
Variables ¶
var ErrUnsupportedLayout = errors.New("on-disk metadata layout is not supported for mirroring")
ErrUnsupportedLayout means the on-disk metadata is not in a layout this package edits. The caller leaves disk untouched and prints a note.
Functions ¶
func CheckFunctionShape ¶
CheckFunctionShape returns E513 when the function is missing from Postgres or exists in a shape other than the one this command generates (for example one hand-written with SECURITY DEFINER, which would bypass the row filter).
func InspectColumn ¶
InspectColumn returns the dimension of the vector(n) column named by s. A non-vector column, a missing column or table, or a column without a fixed dimension is E513.
func MetadataDrift ¶
MetadataDrift lists what differs between live Hasura and the project's on-disk metadata. Empty means no drift.
func MirrorFunction ¶
func MirrorFunction(projectDir, schema, name string, roles []string) (file string, changed bool, err error)
MirrorFunction adds the function and its role permissions to the on-disk metadata of projectDir. It returns the file it wrote and whether anything changed (false when the entry already holds every role). The edit is idempotent. ErrUnsupportedLayout means nothing was written.
Types ¶
type Deps ¶
type Deps struct {
// Exec and PG read the column type from the Postgres container.
Exec Exec
PG PG
// TableTracked reports on-disk tracking: present is false when the project
// has no on-disk metadata at all.
TableTracked func(projectDir, schema, table string) (present, tracked bool, err error)
// ColumnVisible returns E514 when an on-disk select permission hides the
// column (ordering by it would reveal it); nil when all roles see it.
ColumnVisible func(projectDir, schema, table, column string) error
// Drift lists the on-disk metadata keys that differ from live Hasura.
Drift func(ctx context.Context, projectDir string) ([]string, error)
// Track sends one bulk call: pg_track_function plus a permission per role.
Track func(ctx context.Context, schema, name, table, column string, roles []string) error
// Now stamps a new migration file name.
Now func() time.Time
}
Deps are the seams Run uses; the command wires the real ones.
type Exec ¶
type Exec func(ctx context.Context, container string, cmd []string) (stdout, stderr string, err error)
Exec runs a command in a running container and returns stdout and stderr; it has the signature of docker.ExecCapture so tests inject a fake.
type Options ¶
type Options struct {
Spec Spec
ProjectDir string
MigrationDir string // default <ProjectDir>/migrations
Track bool
}
Options are the caller's choices.
type PG ¶
PG names the Postgres container and the role and database psql uses inside it. The role is the container's own superuser: this is the CLI's admin path (like db migrate), not a credential handed to apps.
type Result ¶
type Result struct {
Function string `json:"function"`
Table string `json:"table"`
Column string `json:"column"`
Dim int `json:"dim"`
Distance string `json:"distance"`
Roles []string `json:"roles"`
Migration string `json:"migration"`
MigrationNew bool `json:"migration_written"`
Tracked bool `json:"tracked"`
DiskMetadata string `json:"disk_metadata"` // updated | unchanged | skipped | none
Note string `json:"note"`
}
Result is what Run did; it is also the --json envelope data.
type Spec ¶
type Spec struct {
Schema string
Table string
Column string
Dim int // read from the column type by Inspect
Distance Distance // "" means cosine
Roles []string // empty means [DefaultRole]
}
Spec describes one generated function.
func ParseTarget ¶
ParseTarget splits "<schema>.<table>.<column>" into a Spec. Each part must be a plain identifier; the full check is Validate.
func (Spec) FunctionName ¶
FunctionName is the unqualified function name: <table>_nearest_<column>.
Source Files