Savvi Studio

Codegen CLI Reference

Purpose: Complete reference for all codegen CLI commands and options
Last Updated: 2024-11-28

Command Overview

The codegen CLI generates type-safe TypeScript wrappers for PostgreSQL functions.

Base Command: pnpm db:codegen [options]

Command Options

--schema

Syntax: --schema <name>

Generate code for specific schema(s) only.

# Single schema
pnpm db:codegen --schema graph

# Multiple schemas
pnpm db:codegen --schema graph --schema auth

Default: All configured schemas

--verbose

Syntax: --verbose or -v

Enable detailed logging including SQL queries and file operations.

pnpm db:codegen --verbose

Output shows:

  • Introspection queries executed
  • Types discovered and processed
  • Files being written
  • Dependency resolution steps

When to use:

  • Debugging generation issues
  • Understanding what's being generated
  • Verifying schema is being processed

--check

Syntax: --check

Verify generated code is up-to-date without writing files.

pnpm db:codegen --check

Exit codes:

  • 0: Generated code is current
  • 1: Generated code is outdated or missing

When to use:

  • CI/CD pipelines
  • Pre-commit hooks
  • Verification scripts

--force

Syntax: --force or -f

Force regeneration even if files appear up-to-date.

pnpm db:codegen --force

When to use:

  • Cache issues
  • Suspected stale generation
  • After codegen system updates
  • Troubleshooting type mismatches

--dry-run

Syntax: --dry-run

Show what would be generated without writing files.

pnpm db:codegen --dry-run

Output:

  • Lists schemas to be processed
  • Shows files that would be created/updated
  • Displays any errors that would occur

When to use:

  • Preview changes before generation
  • Verify configuration
  • Troubleshooting without modifying files

--cache

Syntax: --cache

Enable caching for faster subsequent runs.

pnpm db:codegen --cache

Behavior:

  • Caches introspection results
  • Skips unchanged types
  • Faster for large schemas

When to use:

  • Large projects with many types
  • Development iteration
  • CI/CD optimization

Note: Use --force to bypass cache if needed.

--parallel

Syntax: --parallel or -p

Process schemas in parallel for faster generation.

pnpm db:codegen --parallel

When to use:

  • Multiple independent schemas
  • Faster CI/CD builds
  • Large projects

Note: May increase memory usage.

Configuration

Database Connection

Codegen uses standard PostgreSQL environment variables:

# .env.development
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=savvi_dev
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres

Schema Configuration

Configured in package.json or codegen config:

{
  "codegen": {
    "schemas": ["audit", "auth", "graph", "studio"],
    "output": "src/__generated__"
  }
}

Exit Codes

Code Meaning Common Causes
0 Success Generation completed
1 Error Database connection, SQL errors, type issues
2 Outdated --check found differences

Performance

Generation Time

Typical generation times:

Project Size Time Command
Small (1-2 schemas, <50 functions) <1s pnpm db:codegen
Medium (3-4 schemas, 50-200 functions) 1-3s pnpm db:codegen
Large (5+ schemas, 200+ functions) 3-10s pnpm db:codegen --parallel

Optimization Tips

  1. Use --schema for single schema work
  2. Enable --cache for large projects
  3. Use --parallel for multiple schemas
  4. Run selectively - not every file save

Quick Reference Card

Task Command
Generate all pnpm db:codegen
Generate one schema pnpm db:codegen --schema <name>
Debug pnpm db:codegen --verbose
CI check pnpm db:codegen --check
Force regen pnpm db:codegen --force
Preview pnpm db:codegen --dry-run
Fast (parallel) pnpm db:codegen --parallel
Fast (cached) pnpm db:codegen --cache

Examples

For detailed command examples and workflows, see:

This is the single source of truth for all codegen CLI commands. For usage examples, see the linked documentation.