json

JSON Writer

Generates database schema definitions in JSON format.

Overview

The JSON Writer converts RelSpec's internal database model representation into JSON format, providing a complete, structured representation of the database schema.

Features

• Generates RelSpec's canonical JSON schema format
• Complete schema representation including:
  • Databases and schemas
  • Tables, columns, and data types
  • Constraints (PK, FK, unique, check)
  • Indexes
  • Relationships
  • Views and sequences
• Pretty-printed, human-readable output
• Suitable for version control
• Ideal interchange format

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/json"
)

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

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

CLI Examples

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

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

# Convert DBML to JSON
relspec --input dbml --in-file diagram.dbml --output json --out-file schema.json

Generated JSON Example

{
  "name": "myapp",
  "description": "",
  "database_type": "postgresql",
  "database_version": "",
  "source_format": "pgsql",
  "schemas": [
    {
      "name": "public",
      "description": "",
      "tables": [
        {
          "name": "users",
          "schema": "public",
          "description": "",
          "columns": {
            "id": {
              "name": "id",
              "table": "users",
              "schema": "public",
              "type": "bigint",
              "length": 0,
              "precision": 0,
              "scale": 0,
              "not_null": true,
              "is_primary_key": true,
              "auto_increment": true,
              "default": "",
              "sequence": 1
            },
            "username": {
              "name": "username",
              "table": "users",
              "schema": "public",
              "type": "varchar",
              "length": 50,
              "not_null": true,
              "is_primary_key": false,
              "auto_increment": false,
              "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"
            }
          },
          "relationships": {}
        },
        {
          "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 JSON format includes:

Database Level

• name - Database name
• description - Database description
• database_type - Database system type
• database_version - Version information
• source_format - Original source format
• schemas - Array of schema objects

Schema Level

• name - Schema name
• description - Schema description
• tables - Array of table objects
• views - Array of view objects
• sequences - Array of sequence objects

Table Level

• name - Table name
• schema - Schema name
• description - Table description
• columns - Map of column objects
• constraints - Map of constraint objects
• indexes - Map of index objects
• relationships - Map of relationship objects

Column Level

• name - Column name
• type - Data type
• length - Type length
• precision, scale - Numeric precision
• not_null - NOT NULL flag
• is_primary_key - Primary key flag
• auto_increment - Auto-increment flag
• default - Default value
• sequence - Column order

Constraint Level

• name - Constraint name
• type - Constraint type (PRIMARY KEY, FOREIGN KEY, UNIQUE, CHECK)
• columns - Constrained columns
• referenced_table, referenced_schema - FK references
• referenced_columns - Referenced columns
• on_delete, on_update - FK actions

Index Level

• name - Index name
• columns - Indexed columns
• unique - Unique flag
• type - Index type

Use Cases

• Version Control - Track schema changes in git
• Documentation - Human-readable schema documentation
• Interchange - Standard format for tool integration
• Backup - Schema backup without database access
• Testing - Test data for schema validation
• API - Schema information for APIs

Notes

• Output is pretty-printed with 2-space indentation
• Preserves all schema metadata
• Can be round-tripped (read and write) without loss
• Schema-agnostic format
• Ideal for automation and tooling