relspecgo/pkg/writers/yaml/README.md

# 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

```go
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

```bash
# 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

```yaml
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