introspect

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Jul 17, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package introspect reads pg_catalog and produces a Catalog — the single serializable model that drives schema building, caching, and plugins.

Index

Constants

View Source 
const CatalogFormatVersion = 2

CatalogFormatVersion is bumped whenever the Catalog wire format changes incompatibly; the cache layer refuses to load mismatched versions.

Variables

This section is empty.

Functions

func Diff 

func Diff(cached, live *Catalog) []string

Diff describes the structural differences between two catalogs as human-readable lines, phrased as the change from cached to live ("added" = present in live only). Empty means no drift.

Types

type Catalog 

type Catalog struct {
	FormatVersion int          `json:"format_version"`
	ServerVersion string       `json:"server_version"`
	Schemas       []string     `json:"schemas"`
	Tables        []*Table     `json:"tables"`
	Enums         []*Enum      `json:"enums"`
	Composites    []*Composite `json:"composites"`
	Functions     []*Function  `json:"functions"`
}

Catalog is the complete introspected model of the database. It is the only input to GraphQL schema building, which keeps caching trivial and plugin transforms deterministic.

func Introspect 

func Introspect(ctx context.Context, db Querier, schemas []string) (*Catalog, error)

Introspect reads pg_catalog for the given schemas and builds a Catalog. pg_catalog is used instead of information_schema because the latter loses index, RLS, and array/domain detail.

func (*Catalog) Composite 

func (c *Catalog) Composite(schema, name string) *Composite

Composite returns the composite type with the given schema+name, or nil.

func (*Catalog) Enum 

func (c *Catalog) Enum(schema, name string) *Enum

Enum returns the enum with the given schema+name, or nil.

func (*Catalog) Hash 

func (c *Catalog) Hash() (string, error)

Hash returns a stable content hash of the catalog, used by the schema cache and the watch-mode poll fallback to detect drift.

func (*Catalog) Table 

func (c *Catalog) Table(schema, name string) *Table

Table returns the table with the given schema+name, or nil.

type Column 

type Column struct {
	Name       string `json:"name"`
	Position   int    `json:"position"`
	PGType     string `json:"pg_type"`     // canonical type name, e.g. int4, text, _text (array)
	TypeSchema string `json:"type_schema"` // pg schema of the type (for enums/domains/composites)
	IsArray    bool   `json:"is_array"`
	NotNull    bool   `json:"not_null"`
	HasDefault bool   `json:"has_default"`
	Generated  bool   `json:"generated"` // identity or generated column: excluded from create/update input
	Comment    string `json:"comment,omitempty"`
}

type Composite 

type Composite struct {
	Schema string    `json:"schema"`
	Name   string    `json:"name"`
	Fields []*Column `json:"fields"`
}

type Constraint 

type Constraint struct {
	Name    string   `json:"name"`
	Columns []string `json:"columns"`
	Comment string   `json:"comment,omitempty"`
}

type Enum 

type Enum struct {
	Schema  string   `json:"schema"`
	Name    string   `json:"name"`
	Values  []string `json:"values"`
	Comment string   `json:"comment,omitempty"`
}

type ForeignKey 

type ForeignKey struct {
	Name       string   `json:"name"`
	Columns    []string `json:"columns"`
	RefSchema  string   `json:"ref_schema"`
	RefTable   string   `json:"ref_table"`
	RefColumns []string `json:"ref_columns"`
	Comment    string   `json:"comment,omitempty"`
}

type FuncArg 

type FuncArg struct {
	Name       string `json:"name"`
	PGType     string `json:"pg_type"`
	TypeSchema string `json:"type_schema"`
}

type Function 

type Function struct {
	Schema           string     `json:"schema"`
	Name             string     `json:"name"`
	Args             []FuncArg  `json:"args"`
	ReturnType       string     `json:"return_type"`
	ReturnTypeSchema string     `json:"return_type_schema"`
	ReturnsSet       bool       `json:"returns_set"`
	Volatility       Volatility `json:"volatility"`
	Comment          string     `json:"comment,omitempty"`
}

type Index 

type Index struct {
	Name    string   `json:"name"`
	Columns []string `json:"columns"` // expression indexes contribute no columns
	Unique  bool     `json:"unique"`
	Method  string   `json:"method"` // btree, gin, gist, ...
}

type Privileges 

type Privileges struct {
	Select bool `json:"select"`
	Insert bool `json:"insert"`
	Update bool `json:"update"`
	Delete bool `json:"delete"`
}

type Querier 

type Querier interface {
	Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
	QueryRow(ctx context.Context, sql string, args ...any) pgx.Row
}

Querier is the subset of pgx used by introspection (satisfied by *pgx.Conn, pgxpool.Pool, and pgx.Tx).

type RelKind 

type RelKind string

RelKind distinguishes tables from the view family. 

const (
	RelTable            RelKind = "table"
	RelView             RelKind = "view"
	RelMaterializedView RelKind = "matview"
)

type Table 

type Table struct {
	Schema      string        `json:"schema"`
	Name        string        `json:"name"`
	Kind        RelKind       `json:"kind"`
	Comment     string        `json:"comment,omitempty"`
	RLSEnabled  bool          `json:"rls_enabled"`
	Columns     []*Column     `json:"columns"`
	PrimaryKey  *Constraint   `json:"primary_key,omitempty"`
	Uniques     []*Constraint `json:"uniques,omitempty"`
	ForeignKeys []*ForeignKey `json:"foreign_keys,omitempty"`
	Indexes     []*Index      `json:"indexes,omitempty"`
	Privileges  Privileges    `json:"privileges"`
}

func (*Table) Column 

func (t *Table) Column(name string) *Column

Column returns the column with the given name, or nil.

func (*Table) Deletable 

func (t *Table) Deletable() bool

Deletable reports whether generated mutations may DELETE from this relation.

func (*Table) IndexedColumns 

func (t *Table) IndexedColumns() map[string]bool

IndexedColumns returns the set of column names that are the leading column of at least one index (the filterable set under the indexed-only policy).

func (*Table) Insertable 

func (t *Table) Insertable() bool

Insertable reports whether generated mutations may INSERT into this relation.

func (*Table) Updatable 

func (t *Table) Updatable() bool

Updatable reports whether generated mutations may UPDATE this relation.

type Volatility 

type Volatility string

Volatility mirrors pg_proc.provolatile. 

const (
	VolatilityImmutable Volatility = "immutable"
	VolatilityStable    Volatility = "stable"
	VolatilityVolatile  Volatility = "volatile"
)

Source Files

View all Source files

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.