152 lines
5.2 KiB
Markdown
152 lines
5.2 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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)
|
|
```
|
|
|
|
**Key architectural decisions:**
|
|
- Tables use **maps** for Columns, Constraints, Indexes, and Relationships (keyed by name for O(1) lookup)
|
|
- Schemas use **slices** for Tables (order matters for generation)
|
|
- All model types implement `SQLNamer` interface (returns lowercase SQL-safe names)
|
|
- Use `Init*` functions (e.g., `InitTable()`, `InitSchema()`) to create properly initialized models with empty maps/slices
|
|
|
|
**Model Views:**
|
|
- `flatview.go`: Provides denormalized views with fully qualified names (e.g., `database.schema.table.column`)
|
|
- `summaryview.go`: Lightweight summary views with counts and essential metadata
|
|
- Use `.ToFlatColumns()`, `.ToSummary()` methods to convert between views
|
|
|
|
### Reader/Writer Pattern (pkg/readers/, pkg/writers/)
|
|
|
|
All readers and writers implement consistent interfaces with three granularity levels:
|
|
|
|
```go
|
|
// Reader interface
|
|
type Reader interface {
|
|
ReadDatabase() (*models.Database, error)
|
|
ReadSchema() (*models.Schema, error)
|
|
ReadTable() (*models.Table, error)
|
|
}
|
|
|
|
// Writer interface
|
|
type Writer interface {
|
|
WriteDatabase(db *models.Database) error
|
|
WriteSchema(schema *models.Schema) error
|
|
WriteTable(table *models.Table) error
|
|
}
|
|
```
|
|
|
|
**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
|
|
|
|
### Adding a New Reader
|
|
|
|
1. Create `pkg/readers/<format>/` directory
|
|
2. Implement the `Reader` interface with all three methods
|
|
3. Create a `NewReader(options *readers.ReaderOptions)` constructor
|
|
4. Parse format-specific data into the canonical `models.Database` structure
|
|
5. Use `models.Init*()` functions to create properly initialized structs
|
|
|
|
### Adding a New Writer
|
|
|
|
1. Create `pkg/writers/<format>/` directory
|
|
2. Implement the `Writer` interface with all three methods
|
|
3. Create a `NewWriter(options *writers.WriterOptions)` constructor
|
|
4. Transform canonical models into format-specific output
|
|
5. Handle file writing or other I/O in the writer implementation
|
|
|
|
### Working with Models
|
|
|
|
```go
|
|
// Creating models - ALWAYS use Init functions
|
|
db := models.InitDatabase("mydb")
|
|
schema := models.InitSchema("public")
|
|
table := models.InitTable("users", "public")
|
|
column := models.InitColumn("id", "users", "public")
|
|
|
|
// Adding to parent structures
|
|
schema.Tables = append(schema.Tables, table)
|
|
table.Columns["id"] = column // Use map key access for columns
|
|
db.Schemas = append(db.Schemas, schema)
|
|
|
|
// Accessing primary keys and foreign keys
|
|
pk := table.GetPrimaryKey() // Returns *Column or nil
|
|
fks := table.GetForeignKeys() // Returns []*Constraint
|
|
```
|
|
|
|
## CLI Implementation Status
|
|
|
|
The CLI in `cmd/relspec/main.go` is currently a placeholder showing usage examples. It will be implemented using the Cobra framework (already in dependencies).
|
|
|
|
## 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
|