Skip to content
internal/extractors/sql
Updated
On this page

Resolving selfdoc's directives against PostgreSQL DDL: the tables, views and types a schema declares, and the COMMENT ON statements documenting them.

#internal/extractors/sql

#internal/extractors/sql

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.

#Extractor

Go go
type Extractor struct

Extractor reads PostgreSQL DDL.

#New

Go go
func New() extractors.Extractor

New builds the SQL extractor.

#commentSet.Keys

Go go
func (c *commentSet) Keys() []commentKey { return c.keys }

Keys lists the documented objects in document order.

#Extractor.Detect

Go go
func (e *Extractor) Detect(string) bool { return false }

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

#Extractor.FileExtensions

Go go
func (e *Extractor) FileExtensions() []string { return []string{".sql"} }

FileExtensions is the one extension a DDL document carries.

#Extractor.ResolvePath

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

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

#Extractor.PublicSymbols

Go go
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.

#Extractor.SymbolDetails

Go go
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.

Search