sql

Documentation

Overview

Package sql resolves selfdoc's directives against PostgreSQL DDL.

No database connection is required: the DDL document is read with patterns. The four directives it serves are ref, prose-desc, table-schema and table-config.

Never auto-detected

Detection always answers false. A .sql file in a repository says nothing about what the repository is -- a Python service, a Go binary and a Terraform module can all carry one -- so a SQL source path is declared in selfdoc.json and never inferred.

What the document says about itself

The documentation of a schema is its COMMENT ON statements, and they are the only prose a DDL document carries: a table's description, a column's, a view's, a type's and a function's each come from one, in either string spelling SQL offers -- single-quoted with ” for an embedded quote, or dollar-quoted with an optional tag. A comment set to NULL removes a comment rather than being one.

Comments are stripped before anything reads the document's structure, with string literals kept whole, so a -- inside a literal is not mistaken for the start of a comment.

Index

• func New() extractors.Extractor
• type Extractor
  • func (e *Extractor) Detect(string) bool
  • func (e *Extractor) FileExtensions() []string
  • func (e *Extractor) PublicSymbols(file string) ([]string, error)
  • func (e *Extractor) ResolvePath(pathArg string, sourcePaths []string, baseDir string) string
  • func (e *Extractor) SymbolDetails(file, symbol string) (*extractors.SymbolDetails, error)

Functions

func New

func New() extractors.Extractor

New builds the SQL extractor.

Types

type Extractor

type Extractor struct {
	extractors.Base
}

Extractor reads PostgreSQL DDL.

func (*Extractor) Detect

func (e *Extractor) Detect(string) bool

Detect always reports false: SQL is declared in selfdoc.json, never auto-detected.

func (*Extractor) FileExtensions

func (e *Extractor) FileExtensions() []string

FileExtensions is the one extension a DDL document carries.

func (*Extractor) PublicSymbols

func (e *Extractor) PublicSymbols(file string) ([]string, error)

PublicSymbols lists the objects a DDL document creates: its tables, views, types and functions, by their unqualified names.

func (*Extractor) ResolvePath

func (e *Extractor) ResolvePath(pathArg string, sourcePaths []string, baseDir string) string

ResolvePath resolves a directive's path argument to a SQL file or directory.

func (*Extractor) SymbolDetails

func (e *Extractor) SymbolDetails(file, symbol string) (*extractors.SymbolDetails, error)

SymbolDetails reports what a DDL document says about one function's parameters and return type. A table, a view and a type answer nothing, and so does a name the document does not create.