contract

Documentation

Overview

Package contract defines the versioned, serialized IR exchanged between db-catalyst and out-of-process WASM codegen plugins (RFC 0002).

The wire format is a versioned JSON document. The RFC specifies protobuf (with sqlc wire compatibility) as the long-term target; the v1 implementation uses JSON to avoid a protoc build step and stay buildable + testable in CI. A protobuf + sqlc-wire-compatible contract is a future enhancement; the JSON shape here is intentionally additive-only within a major version so a later protobuf encoding can mirror it.

Index

• Constants
• func Marshal(v any) ([]byte, error)
• func Unmarshal(data []byte, v any) error
• type CatalogJSON
• type CodeGenRequest
  • func BuildRequest(catalog *model.Catalog, analyses []analyzer.Result, settings SettingsJSON, ...) *CodeGenRequest
• type CodeGenResponse
• type ColumnJSON
• type DiagJSON
• type FileJSON
• type ParamJSON
• type QueryJSON
• type ResultColumnJSON
• type SettingsJSON
• type TableJSON

Constants

const ContractVersion = 1

ContractVersion is the current major version of the request/response wire format. Plugins inspect CodeGenRequest.Version to negotiate compatibility.

Functions

func Marshal

func Marshal(v any) ([]byte, error)

Marshal serializes a value to stable, indented JSON. The same input always yields byte-identical output (Go's encoding/json sorts map keys; struct field order is fixed by declaration), which keeps plugin runs deterministic.

func Unmarshal

func Unmarshal(data []byte, v any) error

Unmarshal deserializes JSON into v.

Types

type CatalogJSON

type CatalogJSON struct {
	// Tables are the schema tables, sorted by name.
	Tables []TableJSON `json:"tables"`
}

CatalogJSON is the serialized schema catalog.

type CodeGenRequest

type CodeGenRequest struct {
	// Version is the contract major version (ContractVersion).
	Version int `json:"version"`
	// Catalog is the parsed schema (tables and their columns).
	Catalog CatalogJSON `json:"catalog"`
	// Queries is the per-query analysis output, sorted by name.
	Queries []QueryJSON `json:"queries"`
	// Settings carries language/package/database generation settings.
	Settings SettingsJSON `json:"settings"`
	// Options is the opaque, plugin-specific options object passed verbatim from
	// the [[codegen]] entry's `options` table. Plugins decode it themselves.
	Options json.RawMessage `json:"options,omitempty"`
}

CodeGenRequest is the serialized IR handed to a plugin: the parsed catalog, the analyzed queries, generation settings, and an opaque per-plugin options blob. It is deterministic: tables, columns, and queries are sorted.

func BuildRequest

func BuildRequest(catalog *model.Catalog, analyses []analyzer.Result, settings SettingsJSON, options json.RawMessage) *CodeGenRequest

BuildRequest maps a parsed catalog and per-query analyses into a deterministic CodeGenRequest. Tables, columns, and queries are sorted so the serialized bytes are stable across runs for the same input.

type CodeGenResponse

type CodeGenResponse struct {
	Files       []FileJSON `json:"files"`
	Diagnostics []DiagJSON `json:"diagnostics,omitempty"`
}

CodeGenResponse is what a plugin writes back: the generated files plus any diagnostics. A diagnostic with severity "error" fails the generate run.

type ColumnJSON

type ColumnJSON struct {
	Name    string `json:"name"`
	Type    string `json:"type"`
	NotNull bool   `json:"not_null"`
}

ColumnJSON is a single table column.

type DiagJSON

type DiagJSON struct {
	// Severity is "error" or "warning". An "error" fails the generate run.
	Severity string `json:"severity"`
	Message  string `json:"message"`
}

DiagJSON is a single diagnostic emitted by a plugin.

type FileJSON

type FileJSON struct {
	Path     string `json:"path"`
	Contents string `json:"contents"`
}

FileJSON is a single generated file. Contents is the full file body; Path is relative to the [[codegen]] entry's `out` directory.

type ParamJSON

type ParamJSON struct {
	Name     string `json:"name"`
	GoType   string `json:"go_type"`
	Nullable bool   `json:"nullable"`
}

ParamJSON is a single bind parameter of a query.

type QueryJSON

type QueryJSON struct {
	Name    string             `json:"name"`
	SQL     string             `json:"sql"`
	Cmd     string             `json:"cmd"`
	Columns []ResultColumnJSON `json:"columns"`
	Params  []ParamJSON        `json:"params"`
}

QueryJSON is the analysis of a single named query.

type ResultColumnJSON

type ResultColumnJSON struct {
	Name     string `json:"name"`
	GoType   string `json:"go_type"`
	Nullable bool   `json:"nullable"`
}

ResultColumnJSON is a single output column of a query.

type SettingsJSON

type SettingsJSON struct {
	Package  string `json:"package"`
	Database string `json:"database"`
	Language string `json:"language"`
}

SettingsJSON carries the generation settings relevant to a plugin.

type TableJSON

type TableJSON struct {
	Name    string       `json:"name"`
	Columns []ColumnJSON `json:"columns"`
}

TableJSON is a single table and its columns.