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 (live databases, DBML, DCTX, DrawDB, etc.) and writes them to various formats (GORM, Bun, JSON, YAML, SQL, etc.).

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 (dbml, dctx, drawdb, etc.) has its own pkg/readers/<format>/ and pkg/writers/<format>/ subdirectories
Use ReaderOptions and WriterOptions structs for configuration (file paths, connection strings, metadata)
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

Development Patterns

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.25.5
Uses Cobra for CLI, Viper for configuration

2.6 KiB Raw Permalink Blame History