relspecgo/pkg/writers/yaml

YAML Writer

Generates database schema definitions in YAML format.

Overview

The YAML Writer converts RelSpec's internal database model representation into YAML format, providing a human-readable, structured representation of the database schema.

Features

• Generates RelSpec's canonical YAML schema format
• Human-readable alternative to JSON
• Complete schema representation including:
  • Databases and schemas
  • Tables, columns, and data types
  • Constraints (PK, FK, unique, check)
  • Indexes
  • Relationships
  • Views and sequences
• Supports comments
• Ideal for manual editing and configuration

Usage

Basic Example

package main

import (
    "git.warky.dev/wdevs/relspecgo/pkg/models"
    "git.warky.dev/wdevs/relspecgo/pkg/writers"
    "git.warky.dev/wdevs/relspecgo/pkg/writers/yaml"
)

func main() {
    options := &writers.WriterOptions{
        OutputPath: "schema.yaml",
    }

    writer := yaml.NewWriter(options)
    err := writer.WriteDatabase(db)
    if err != nil {
        panic(err)
    }
}

CLI Examples

# Export PostgreSQL database to YAML
relspec --input pgsql \
  --conn "postgres://localhost/mydb" \
  --output yaml \
  --out-file schema.yaml

# Convert GORM models to YAML
relspec --input gorm --in-file models.go --output yaml --out-file schema.yaml

# Convert JSON to YAML
relspec --input json --in-file schema.json --output yaml --out-file schema.yaml

Generated YAML Example

name: myapp
database_type: postgresql
source_format: pgsql
schemas:
  - name: public
    tables:
      - name: users
        schema: public
        columns:
          id:
            name: id
            table: users
            schema: public
            type: bigint
            not_null: true
            is_primary_key: true
            auto_increment: true
            sequence: 1
          username:
            name: username
            table: users
            schema: public
            type: varchar
            length: 50
            not_null: true
            sequence: 2
          email:
            name: email
            table: users
            schema: public
            type: varchar
            length: 100
            not_null: true
            sequence: 3
        constraints:
          pk_users:
            name: pk_users
            type: PRIMARY KEY
            table: users
            schema: public
            columns:
              - id
          uq_users_username:
            name: uq_users_username
            type: UNIQUE
            table: users
            schema: public
            columns:
              - username
        indexes:
          idx_users_email:
            name: idx_users_email
            table: users
            schema: public
            columns:
              - email
            unique: false
            type: btree

      - name: posts
        schema: public
        columns:
          id:
            name: id
            type: bigint
            not_null: true
            is_primary_key: true
            sequence: 1
          user_id:
            name: user_id
            type: bigint
            not_null: true
            sequence: 2
          title:
            name: title
            type: varchar
            length: 200
            not_null: true
            sequence: 3
          content:
            name: content
            type: text
            not_null: false
            sequence: 4
        constraints:
          fk_posts_user_id:
            name: fk_posts_user_id
            type: FOREIGN KEY
            table: posts
            schema: public
            columns:
              - user_id
            referenced_table: users
            referenced_schema: public
            referenced_columns:
              - id
            on_delete: CASCADE
            on_update: NO ACTION
        indexes:
          idx_posts_user_id:
            name: idx_posts_user_id
            columns:
              - user_id
            unique: false
            type: btree
    views: []
    sequences: []

Schema Structure

The YAML format mirrors the JSON structure with human-readable syntax:

• Database level: name, database_type, source_format, schemas
• Schema level: name, tables, views, sequences
• Table level: name, schema, columns, constraints, indexes
• Column level: name, type, length, not_null, etc.
• Constraint level: name, type, columns, foreign key details
• Index level: name, columns, unique, type

Advantages Over JSON

• More human-readable
• Easier to edit manually
• Supports comments
• Less verbose (no braces/brackets)
• Better for configuration files
• Natural indentation

Use Cases

• Configuration - Schema as configuration
• Documentation - Human-readable schema docs
• Version Control - Easier to read diffs
• Manual Editing - Easier to modify by hand
• Code Generation - Template-friendly format

Notes

• Output is properly indented (2 spaces)
• Preserves all schema metadata
• Can be round-tripped with YAML reader
• Compatible with YAML 1.2
• More readable than JSON for large schemas
• Ideal for documentation and manual workflows