entity-maker/README.md

Entity Maker

A command-line tool for generating SQLAlchemy entities from PostgreSQL database tables.

Features

• Connects to PostgreSQL database and introspects table structure
• Generates Python 3.13 code using SQLAlchemy
• Creates complete entity scaffolding including:
  • SQLAlchemy table definition
  • Dataclass model
  • Filter class
  • Load options
  • Repository
  • Manager
  • Factory (for testing)
  • Mapper
  • Enum types (if table uses PostgreSQL enums)

Installation

Build from source

Using Makefile (recommended):

# Build static binary (production-ready, fully portable)
make build

# Build with debug symbols (development)
make build-dev

# Install to /usr/local/bin
make install

# Clean build artifacts
make clean

# Verify binary has no dependencies
make verify-static

# Show all available targets
make help

Or using Go directly:

# Static binary (portable across all Linux x86-64 systems)
CGO_ENABLED=0 go build -ldflags "-s -w" -trimpath -o ./build/entity-maker ./cmd/entity-maker

# Development binary with debug symbols
go build -o entity-maker ./cmd/entity-maker

The static binary (make build) is fully portable and will run on any Linux x86-64 system without external dependencies.

Testing

Run tests using Makefile commands:

# Run all tests
make test

# Run tests with verbose output
make test-verbose

# Run tests with coverage summary
make test-coverage

# Generate HTML coverage report
make coverage
# Then open coverage.html in your browser

# Run only short/fast tests
make test-short

# Run benchmarks
make bench

Or using Go directly:

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Run specific package
go test ./internal/naming -v

# Generate coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Test Coverage:

• internal/naming: 97.1% ⭐
• internal/generator: 91.1% ⭐
• internal/config: 81.8%
• internal/prompt: 75.3%
• internal/database: 30.8%
• cmd/entity-maker: 0.0% (integration code - business logic tested in internal packages)

Usage

Interactive Mode

Run the application without arguments to use interactive prompts:

./entity-maker

The application will prompt you for:

• Database host (default: localhost)
• Database port (default: 5432)
• Database name (required)
• Database schema (default: public)
• Database user (default: postgres)
• Database password (default: postgres)
• Table name (required)
• Output directory (required)
• Entity name override (optional)

Command-Line Arguments

You can also provide parameters via command-line flags:

./entity-maker \
  -host localhost \
  -port 5432 \
  -db mydb \
  -schema public \
  -user postgres \
  -password secret \
  -table users \
  -output ./output \
  -entity User

Available Flags

• -host - Database host
• -port - Database port
• -db - Database name
• -schema - Database schema
• -user - Database user
• -password - Database password
• -table - Table name to generate entities from
• -output - Output directory path
• -entity - Entity name override (optional, defaults to singularized table name)

Configuration

The application saves your settings to ~/.config/entity-maker.toml for future use. When you run the application again, it will use these saved values as defaults.

Generated Files

For a table named users, the following files will be generated in output/user/:

• table.py - SQLAlchemy Table definition
• model.py - Dataclass model with type hints
• filter.py - Filter class for queries
• load_options.py - Relationship loading options
• repository.py - CRUD repository
• manager.py - Manager class
• factory.py - Factory for testing (uses factory_boy)
• mapper.py - SQLAlchemy mapper configuration
• enum.py - Enum types (only if table uses PostgreSQL enums)
• __init__.py - Package initialization

Example

Generate entities for the cashbag_conforms table:

./entity-maker -db mydb -table cashbag_conforms -output ./output

This will create files in ./output/cashbag_conform/:

• Entity name: CashbagConform
• Module name: cashbag_conform
• All supporting files

Requirements

• PostgreSQL database
• Go 1.21+ (for building)
• Python 3.13+ (for generated code)
• SQLAlchemy (for generated code)

Project Structure

entity-maker/
├── cmd/
│   └── entity-maker/     # Main application
├── internal/
│   ├── config/          # Configuration management
│   ├── database/        # Database connection and introspection
│   ├── generator/       # Code generators
│   ├── naming/          # Naming utilities (pluralization, case conversion)
│   └── prompt/          # Interactive CLI prompts
├── example/             # Example output files
├── CLAUDE.md           # Detailed specification
└── README.md           # This file

License

See LICENSE file for details.