relspecgo/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

RelSpec is a database relations specification tool that provides bidirectional conversion between various database schema formats. It reads database schemas from multiple sources and writes them to various formats.

Supported Readers: Bun, DBML, DCTX, DrawDB, Drizzle, GORM, GraphQL, JSON, PostgreSQL, Prisma, SQL Directory, SQLite, TypeORM, YAML

Supported Writers: Bun, DBML, DCTX, DrawDB, Drizzle, GORM, GraphQL, JSON, PostgreSQL, Prisma, SQL Exec, SQLite, Template, TypeORM, YAML

Build Commands

# Build the binary
make build              # Outputs to build/relspec
go build -o build/relspec ./cmd/relspec

# Run tests
make test              # Run all tests with race detection and coverage
go test ./...          # Run tests without coverage

# Run a single test
go test -run TestName ./pkg/readers/dbml

# Linting
make lint              # Requires golangci-lint installed

# Coverage report
make coverage          # Generates coverage.html

# Clean build artifacts
make clean

# Install binary
make install           # Installs to $GOPATH/bin

Architecture

Core Data Model (pkg/models/)

The central data structure is the Database model, which represents a complete database schema with this hierarchy:

Database
└── Schemas ([]Schema)
    └── Tables ([]Table)
        ├── Columns (map[string]Column)
        ├── Constraints (map[string]Constraint)
        ├── Indexes (map[string]Index)
        └── Relationships (map[string]Relationship)

Important patterns:

• Each format has its own pkg/readers/<format>/ and pkg/writers/<format>/ subdirectories
• Use ReaderOptions and WriterOptions structs for configuration (file paths, connection strings, metadata, flatten option)
• FlattenSchema option collapses multi-schema databases into a single schema for simplified output
• Schema reading typically returns the first schema when reading from Database
• Table reading typically returns the first table when reading from Schema

Transformation Layer (pkg/transform/)

The Transformer provides validation and normalization utilities. Note: validation methods are currently stubs (return nil) and need implementation when used.

Database-Specific Utilities (pkg/pgsql/)

Contains PostgreSQL-specific helpers:

• keywords.go: SQL reserved keywords validation
• datatypes.go: PostgreSQL data type mappings and conversions

Additional Utilities

• pkg/diff/: Schema difference detection and comparison
• pkg/inspector/: Schema inspection and analysis tools
• pkg/merge/: Schema merging capabilities
• pkg/reflectutil/: Reflection utilities for dynamic type handling
• pkg/ui/: Terminal UI components for interactive schema editing
• pkg/commontypes/: Shared type definitions

Development Patterns

• Each reader/writer is self-contained in its own subdirectory
• Options structs control behavior (file paths, connection strings, flatten schema, etc.)
• Live database connections supported for PostgreSQL and SQLite
• Template writer allows custom output formats

Testing

• Test files should be in the same package as the code they test
• Use table-driven tests for multiple test cases
• All tests run with race detection via make test
• Coverage reports available via make coverage

Module Information

• Module path: git.warky.dev/wdevs/relspecgo
• Go version: 1.24.0
• Uses Cobra for CLI
• Key dependencies: pgx/v5 (PostgreSQL), modernc.org/sqlite (SQLite), tview (TUI), Bun ORM