indexquery

Documentation

Overview

Package indexquery exposes read-only programmatic access to the bintrail index — live MySQL partitions and Parquet archives merged — for tooling and embedding distributions that import the core as a module.

It is a thin facade over the internal query layer: type aliases to the internal types (usable across module boundaries through the alias) plus one-line wrappers over the internal entry points, so external code can run the exact fetch/merge/gap-detection pipeline the CLI commands use. The index schema stays owned by the core: EnsureSchema is the only sanctioned migration entry point, and this package adds no write surface beyond it.

Index

• Constants
• func AddDuckDBTuningFlags(cmd *cobra.Command)
• func Connect(dsn string) (*sql.DB, error)
• func EnsureSchema(db *sql.DB) error
• func EventTypeName(t EventType) string
• func FetchMerged(ctx context.Context, db *sql.DB, engine *Engine, o FetchMergedOptions) ([]ResultRow, *QueryPlan, error)
• func FormatGapWarning(gaps []time.Time) string
• func OutputJSON(v any) error
• func ParseSourceDSN(dsn string) (host string, port uint16, user, password string, err error)
• func WrapSchemaMigrationErr(err error) error
• type ArchiveFetcher
  • func TunedArchiveFetcher(t Tuning) ArchiveFetcher
• type Engine
  • func New(db *sql.DB) *Engine
• type EventType
• type FetchMergedOptions
• type GapError
• type Options
• type QueryPlan
• type ResultRow
• type SourceEmptyError
• type Tuning
  • func DuckDBTuningFromFlags(cmd *cobra.Command) (Tuning, error)

Constants

const (
	EventInsert   = event.EventInsert
	EventUpdate   = event.EventUpdate
	EventDelete   = event.EventDelete
	EventDDL      = event.EventDDL
	EventGTID     = event.EventGTID
	EventSnapshot = event.EventSnapshot
)

The persisted event-type values a ResultRow can carry. (Capture-side transient types — commit markers, PG relation messages — are never written to binlog_events, so they cannot appear in query results.)

Functions

func AddDuckDBTuningFlags

func AddDuckDBTuningFlags(cmd *cobra.Command)

AddDuckDBTuningFlags registers the shared DuckDB resource flags (--ultrafast, --duckdb-threads, --duckdb-memory-limit) on an offline read command.

func Connect

func Connect(dsn string) (*sql.DB, error)

Connect opens and verifies a MySQL connection with the core's connection invariants applied (parseTime=true, UTC, default connect timeout). The caller closes the returned *sql.DB.

func EnsureSchema

func EnsureSchema(db *sql.DB) error

EnsureSchema brings the index schema up to date (idempotent — safe to call on every startup). This is the only schema-mutating entry point exposed here; the schema definition itself stays owned by the core.

func EventTypeName

func EventTypeName(t EventType) string

EventTypeName returns the canonical upper-case name for a persisted event type ("INSERT", "UPDATE", "DELETE", "DDL", "GTID", "SNAPSHOT"), or "UNKNOWN" for a value outside that vocabulary.

func FetchMerged

func FetchMerged(ctx context.Context, db *sql.DB, engine *Engine, o FetchMergedOptions) ([]ResultRow, *QueryPlan, error)

FetchMerged fetches events from live MySQL partitions and Parquet archives, deduplicates and sorts them, and enforces coverage-gap detection according to o.AllowGaps. See query.FetchMerged for the full failure-mode contract.

Two caveats external callers cannot discover from the signature:

• Callers running with redaction options (an RBAC profile — DenyTables / RedactColumns / ProfileActive on o.Opts) must set o.NoArchive = true: Parquet archives store the raw rows, so the archive branch would serve unredacted columns.
• The returned *QueryPlan may be nil when the planner didn't run (e.g. no DBName or no time range) — nil-check it before use.

func FormatGapWarning

func FormatGapWarning(gaps []time.Time) string

FormatGapWarning renders the planner's gap hours as the standard human-readable coverage warning.

func OutputJSON

func OutputJSON(v any) error

OutputJSON writes v to stdout as indented JSON.

func ParseSourceDSN

func ParseSourceDSN(dsn string) (host string, port uint16, user, password string, err error)

ParseSourceDSN decomposes a go-sql-driver DSN into host, port, user, and password. It requires a TCP address and rejects unix-socket DSNs.

func WrapSchemaMigrationErr

func WrapSchemaMigrationErr(err error) error

WrapSchemaMigrationErr rewrites an EnsureSchema failure caused by a read-only DSN (missing ALTER/CREATE privilege) into an actionable error. Read-plane callers only — capture-plane callers must keep failing hard on the raw error.

Types

type ArchiveFetcher

type ArchiveFetcher = query.ArchiveFetcher

Aliases to the internal query types. FetchMergedOptions is fully constructible through these (including its ArchiveFetcher field); GapError and SourceEmptyError are aliased so callers can inspect FetchMerged failures with errors.As.

func TunedArchiveFetcher

func TunedArchiveFetcher(t Tuning) ArchiveFetcher

TunedArchiveFetcher adapts a DuckDB Tuning into an ArchiveFetcher suitable for FetchMergedOptions.ArchiveFetcher.

type Engine

type Engine = query.Engine

Aliases to the internal query types. FetchMergedOptions is fully constructible through these (including its ArchiveFetcher field); GapError and SourceEmptyError are aliased so callers can inspect FetchMerged failures with errors.As.

func New

func New(db *sql.DB) *Engine

New returns a query engine over the index database.

type EventType

type EventType = event.EventType

EventType aliases the event-type vocabulary so external code can interpret ResultRow.EventType without magic numbers. The numeric values are a persistence contract (binlog_events.event_type) — never renumber.

type FetchMergedOptions

type FetchMergedOptions = query.FetchMergedOptions

Aliases to the internal query types. FetchMergedOptions is fully constructible through these (including its ArchiveFetcher field); GapError and SourceEmptyError are aliased so callers can inspect FetchMerged failures with errors.As.

type GapError

type GapError = query.GapError

Aliases to the internal query types. FetchMergedOptions is fully constructible through these (including its ArchiveFetcher field); GapError and SourceEmptyError are aliased so callers can inspect FetchMerged failures with errors.As.

type Options

type Options = query.Options

Aliases to the internal query types. FetchMergedOptions is fully constructible through these (including its ArchiveFetcher field); GapError and SourceEmptyError are aliased so callers can inspect FetchMerged failures with errors.As.

type QueryPlan

type QueryPlan = query.QueryPlan

Aliases to the internal query types. FetchMergedOptions is fully constructible through these (including its ArchiveFetcher field); GapError and SourceEmptyError are aliased so callers can inspect FetchMerged failures with errors.As.

type ResultRow

type ResultRow = query.ResultRow

Aliases to the internal query types. FetchMergedOptions is fully constructible through these (including its ArchiveFetcher field); GapError and SourceEmptyError are aliased so callers can inspect FetchMerged failures with errors.As.

type SourceEmptyError

type SourceEmptyError = query.SourceEmptyError

Aliases to the internal query types. FetchMergedOptions is fully constructible through these (including its ArchiveFetcher field); GapError and SourceEmptyError are aliased so callers can inspect FetchMerged failures with errors.As.

type Tuning

type Tuning = duckdbutil.Tuning

Aliases to the internal query types. FetchMergedOptions is fully constructible through these (including its ArchiveFetcher field); GapError and SourceEmptyError are aliased so callers can inspect FetchMerged failures with errors.As.

func DuckDBTuningFromFlags

func DuckDBTuningFromFlags(cmd *cobra.Command) (Tuning, error)

DuckDBTuningFromFlags resolves the effective DuckDB tuning for a command carrying the flags registered by AddDuckDBTuningFlags. An invalid --duckdb-memory-limit is a hard error.