sqldoc: init

Author: wilsonehusin

.envrc

@@ -0,0 +1 @@
+PATH_add bin

.gitignore

@@ -0,0 +1,23 @@
+# Output documentation
+schema.md
+schema/*
+
+# Development binaries
+bin/*
+!bin/.keep
+
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Go workspace file
+go.work

README.md

@@ -0,0 +1,11 @@
+# SQLDoc
+
+SQLDoc is a markdown documentation for SQL tables. Inspired by Rails ActiveRecord `schema.rb` and [drwl/annotaterb](https://github.com/drwl/annotaterb).
+
+## Why?
+
+Projects often manages their schema roll out through migrations (e.g. [golang-migrate/migrate](https://github.com/golang-migrate/migrate)). As a project matures, it's quite common to encounter several `ALTER TABLE` commands, which makes it difficult to have a near-instant idea of what the schema looks like.
+
+In Rails, `schema.rb` provides that insight, while extensions like [drwl/annotaterb](https://github.com/drwl/annotaterb) goes further to co-locate the schema documentation with the model definitions.
+
+SQLDoc makes it easy to look at Markdown documentation for SQL tables, which I prefer over running `psql -c "\d+ table_name"`.

bin/.keep

@@ -0,0 +1,88 @@
+package config
+
+import (
+	_ "embed"
+	"errors"
+	"os"
+
+	"gopkg.in/yaml.v3"
+)
+
+//go:embed example.yaml
+var example []byte
+
+var ErrDatabaseURLRequired = errors.New("no database URL found, specify in configuration or set DATABASE_URL environment variable")
+
+type Config struct {
+	Database      Database      `json:"database"`
+	Documentation Documentation `json:"documentation"`
+}
+
+type Database struct {
+	URL           string   `json:"url"`
+	Schemas       []string `json:"schemas"`
+	ExcludeTables []string `json:"exclude_tables" yaml:"exclude_tables"`
+}
+
+type Documentation struct {
+	Strategy  string `json:"strategy"`
+	Directory string `json:"directory"`
+	Filename  string `json:"filename"`
+	Stdout    bool   `json:"stdout"`
+}
+
+func Default() *Config {
+	return &Config{
+		Database: Database{
+			URL:           os.Getenv("DATABASE_URL"),
+			Schemas:       []string{"public"},
+			ExcludeTables: []string{},
+		},
+		Documentation: Documentation{
+			Strategy:  "unified",
+			Directory: ".",
+			Filename:  "schema.md",
+			Stdout:    true,
+		},
+	}
+}
+
+func Parse(data []byte) (*Config, error) {
+	config := Default()
+	if err := yaml.Unmarshal(data, config); err != nil {
+		return nil, err
+	}
+	return config, nil
+}
+
+func ParseFile(path string) (*Config, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	return Parse(data)
+}
+
+func Load(path string) (*Config, error) {
+	var conf *Config
+	if path == "" {
+		conf = Default()
+	} else {
+		var err error
+		conf, err = ParseFile(path)
+		if err != nil {
+			return nil, err
+		}
+	}
+	if dburl := os.Getenv("DATABASE_URL"); dburl != "" {
+		conf.Database.URL = dburl
+	}
+	if conf.Database.URL == "" {
+		return nil, ErrDatabaseURLRequired
+	}
+	return conf, nil
+}
+
+func WriteExample(path string) error {
+	return os.WriteFile(path, example, 0644)
+}

config/config.go

@@ -0,0 +1,22 @@
+# Example configuration file for sqldoc.
+# When the value is optional, the defaults shown below are used.
+
+database:
+  # Required: fallback to $DATABASE_URL value.
+  url: "postgres://user:password@localhost:5432/database_name"
+  # Optional: Schemas to be included in the documentation.
+  schemas: ["public"]
+  # Optional: Tables to be excluded from the documentation.
+  exclude_tables: [""]
+
+documentation:
+  # Documentation strategies:
+  # - unified: All tables are documented in a single file.
+  # - per_table: Each table is documented in a separate file.
+  strategy: unified
+  # Optional: Output directory for the documentation.
+  directory: "."
+  # Optional: Output filename for the documentation. Only used in "unified" strategy.
+  filename: "schema.md"
+  # Write the output to STDOUT as well.
+  stdout: true

config/example.yaml

@@ -0,0 +1,31 @@
+package db
+
+import (
+	"context"
+	"fmt"
+	"strings"
+)
+
+type Database interface {
+	Close() error
+
+	ListTables(ctx context.Context, schema string) ([]string, error)
+	ListColumns(ctx context.Context, schema, table string) ([]TableColumn, error)
+}
+
+type TableColumn struct {
+	Name     string
+	Type     string
+	Nullable bool
+	Default  string
+}
+
+func New(url string) (Database, error) {
+	protocol := strings.Split(url, "://")[0]
+	switch protocol {
+	case "postgres", "postgresql", "pgx":
+		return NewPostgres(url)
+	default:
+		return nil, fmt.Errorf("unsupported protocol: %s", protocol)
+	}
+}

db/db.go

@@ -0,0 +1,88 @@
+package db
+
+import (
+	"context"
+	"database/sql"
+	"strings"
+
+	_ "github.com/jackc/pgx/v5/stdlib"
+)
+
+type Postgres struct {
+	db *sql.DB
+}
+
+func NewPostgres(dsn string) (*Postgres, error) {
+	db, err := sql.Open("pgx", dsn)
+	if err != nil {
+		return nil, err
+	}
+	return &Postgres{db}, nil
+}
+
+func (p *Postgres) Close() error {
+	if p.db == nil {
+		return nil
+	}
+	if err := p.db.Close(); err != nil {
+		return err
+	}
+	p.db = nil
+	return nil
+}
+
+const pgListTables = `SELECT DISTINCT table_name FROM information_schema.tables WHERE table_schema = $1 ORDER BY table_name ASC`
+
+func (p *Postgres) ListTables(ctx context.Context, schema string) ([]string, error) {
+	rows, err := p.db.QueryContext(ctx, pgListTables, schema)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var tables []string
+	for rows.Next() {
+		var table string
+		if err := rows.Scan(&table); err != nil {
+			return nil, err
+		}
+		tables = append(tables, table)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return tables, nil
+}
+
+const pgListColumns = `SELECT column_name, data_type, is_nullable, column_default FROM information_schema.columns WHERE table_schema = $1 AND table_name = $2`
+
+func (p *Postgres) ListColumns(ctx context.Context, schema, table string) ([]TableColumn, error) {
+	rows, err := p.db.QueryContext(ctx, pgListColumns, schema, table)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var columns []TableColumn
+	for rows.Next() {
+		var c TableColumn
+		var nullable string
+		var defaultVal sql.NullString
+		if err := rows.Scan(&c.Name, &c.Type, &nullable, &defaultVal); err != nil {
+			return nil, err
+		}
+		c.Nullable = nullable == "YES"
+		if defaultVal.Valid {
+			c.Default = strings.TrimSpace(defaultVal.String)
+		}
+		columns = append(columns, c)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return columns, nil
+}

db/postgres.go

@@ -0,0 +1,39 @@
+module go.husin.dev/sqldoc
+
+go 1.22.2
+
+require (
+	github.com/charmbracelet/glamour v0.7.0
+	github.com/jackc/pgx/v5 v5.5.5
+	github.com/nao1215/markdown v0.0.8
+	gopkg.in/yaml.v3 v3.0.1
+)
+
+require (
+	github.com/alecthomas/chroma/v2 v2.8.0 // indirect
+	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
+	github.com/aymerick/douceur v0.2.0 // indirect
+	github.com/dlclark/regexp2 v1.4.0 // indirect
+	github.com/gorilla/css v1.0.0 // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a // indirect
+	github.com/jackc/puddle/v2 v2.2.1 // indirect
+	github.com/karrick/godirwalk v1.17.0 // indirect
+	github.com/kr/text v0.2.0 // indirect
+	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
+	github.com/mattn/go-isatty v0.0.18 // indirect
+	github.com/mattn/go-runewidth v0.0.14 // indirect
+	github.com/microcosm-cc/bluemonday v1.0.25 // indirect
+	github.com/muesli/reflow v0.3.0 // indirect
+	github.com/muesli/termenv v0.15.2 // indirect
+	github.com/olekukonko/tablewriter v0.0.5 // indirect
+	github.com/rivo/uniseg v0.2.0 // indirect
+	github.com/rogpeppe/go-internal v1.12.0 // indirect
+	github.com/yuin/goldmark v1.5.4 // indirect
+	github.com/yuin/goldmark-emoji v1.0.2 // indirect
+	golang.org/x/crypto v0.17.0 // indirect
+	golang.org/x/net v0.17.0 // indirect
+	golang.org/x/sync v0.1.0 // indirect
+	golang.org/x/sys v0.15.0 // indirect
+	golang.org/x/text v0.14.0 // indirect
+)