schemaforge-cli

SchemaForge

A production-quality visual database schema designer for developers.

Quick Start

npx schemaforge-cli

This builds the app (if needed) and serves it at http://localhost:4173, opening your browser automatically. All data is stored locally in the browser — no backend, no account, no AI APIs.

CLI Options

npx schemaforge-cli                # Build and serve on port 4173
npx schemaforge-cli --port 8080    # Use a custom port
npx schemaforge-cli --dev          # Dev mode with hot reload
npx schemaforge-cli --help         # Show help

From Source

git clone https://github.com/rostislaw9/schema-forge.git
cd schema-forge
pnpm install
pnpm dev      # development with hot reload
pnpm build    # production build to dist/
pnpm preview  # preview the production build

What It Does

SchemaForge lets developers visually model database schemas on an interactive canvas and export them to multiple targets:

• PostgreSQL SQL (DDL with tables, constraints, indexes, enums, comments)
• MongoDB shell commands (JSON Schema validators with relation-derived ObjectId references + index creation)
• Prisma schema (datasource, generator, models, enums, relations, composite unique constraints)
• TypeORM entity classes (TypeScript decorators for columns, PKs, relations, indexes, check constraints, generated columns, comments)

The app is local-first, requires no AI APIs, and uses no paid services. All state persists to localStorage. Projects can be exported/imported as JSON.

Features

Core

• Visual canvas — drag entities, connect fields with relations
• Dialect-aware — PostgreSQL (tables) or MongoDB (collections) with automatic type and property conversion when switching
• Field-to-field relations — drag from a field's right handle to another field's left handle to create FK references
• Relation kinds — one-to-one, one-to-many, many-to-many, embedded (MongoDB only)
• Referential actions — ON DELETE / ON UPDATE (CASCADE, SET NULL, SET DEFAULT, RESTRICT, NO ACTION) for PostgreSQL
• Compatibility warnings — real-time validation with severity levels (info/warning/error) grouped by export target, click-to-select. Warnings target the appropriate exporters (e.g. "no fields" appears under all tabs, "no primary key" under SQL-style exporters only)
• Sample projects — SaaS billing system (PostgreSQL, 8 entities) and blog/CMS platform (MongoDB, 5 collections with ObjectId references, many-to-many via ObjectId arrays, and array fields)
• Project JSON import/export — share and persist projects as files
• Automatic fit view — canvas auto-fits when loading a project or sample

PostgreSQL-specific

• Primary keys — inline and composite
• Unique constraints — inline (per-field) and composite (multi-field)
• CHECK constraints — per-field check expressions
• Generated columns — GENERATED ALWAYS AS ... STORED
• Table & column comments — COMMENT ON TABLE / COMMENT ON COLUMN
• Index methods — btree (default), gin, gist, brin, hash
• Partial indexes — WHERE clause filtering
• Index sort orders — ASC/DESC per field
• Array types — type[] syntax for array columns
• Enums — CREATE TYPE ... AS ENUM (data model only, no UI editor yet)
• DROP IF EXISTS — safe re-runnable DDL output

MongoDB-specific

• JSON Schema validators — db.createCollection() with $jsonSchema
• Relation-derived reference fields — one-to-one/one-to-many generate { target }_id as objectId, many-to-many generates { target }_ids as array of objectId, embedded generates nested object
• Automatic ObjectId indexes — single reference fields get createIndex() automatically (skips fields already indexed)
• BSON type mapping — full mapping from internal types to BSON types
• Embedded objects — isEmbedded toggle for nested document fields
• Validation level/action — configurable strict/error validation

Tech Stack

• React + TypeScript (strict mode)
• Vite (dev server and bundler)
• React Flow (visual schema canvas)
• Zustand (client state with localStorage persistence)
• Zod (runtime validation for types and imports)
• Tailwind CSS (styling, Catppuccin Mocha dark theme)
• Vitest (unit tests)
• ESLint (linting with typescript-eslint flat config)
• Prettier (code formatting)

Development

Prerequisites

• Node.js 18+
• pnpm 9+ (enable via corepack enable or npm install -g pnpm)

Setup

git clone https://github.com/rostislaw9/schema-forge.git
cd schema-forge
pnpm install

Scripts

Command	Description
pnpm dev	Start the Vite dev server
pnpm build	Type-check and build for production
pnpm preview	Preview the production build
pnpm typecheck	Run TypeScript type checking
pnpm test	Run unit tests once
pnpm test:watch	Run unit tests in watch mode
pnpm lint	Run ESLint
pnpm lint:fix	Run ESLint and auto-fix issues
pnpm format	Format all files with Prettier
pnpm format:check	Check formatting without writing

Before submitting changes, verify all checks pass:

pnpm typecheck && pnpm lint && pnpm format:check && pnpm test && pnpm build

Architecture

src/
  types/
    schema.ts              # Internal domain model types + Zod schemas
    schema.test.ts
  store/
    projectStore.ts        # Zustand store with localStorage persistence
    projectStore.test.ts
  lib/
    id.ts                  # ID generation helper
    typePresets.ts         # PostgreSQL/MongoDB type presets
    validation.ts          # Field/entity name validation helpers
    validation.test.ts
    warnings.ts            # Compatibility warning engine (multi-target)
    warnings.test.ts
    sampleProject.ts       # Sample project generators (PostgreSQL + MongoDB)
    sampleProject.test.ts
  exporters/
    postgres.ts            # PostgreSQL DDL exporter
    postgres.test.ts
    prisma.ts              # Prisma schema exporter
    prisma.test.ts
    mongodb.ts             # MongoDB shell command exporter (with relations)
    mongodb.test.ts
    typeorm.ts             # TypeORM entity class exporter
    typeorm.test.ts
  components/
    Sidebar.tsx            # Dialect selector, entity list, project actions
    SchemaCanvas.tsx       # React Flow canvas with field-to-field handles
    EntityNode.tsx         # Custom React Flow node with per-field handles
    Inspector.tsx          # Entity/field/relation/index editor
    FieldEditor.tsx        # Reusable field property editor
    ExportPanel.tsx        # Tabbed export preview with warnings
  App.tsx                  # Root layout
  main.tsx                 # Entry point
  index.css                # Tailwind + global styles

Key Design Decisions

• Pure exporter functions — each exporter takes a Project and returns a string. No side effects, fully testable.
• Dialect-aware everything — field types, field properties (PK/unique vs array/embedded), relation kinds, index options, and export tabs all adapt to the selected dialect. Switching dialects converts existing data automatically and clears dialect-specific properties (e.g. PG index methods, CHECK expressions, referential actions are cleared when switching to MongoDB; embedded flags are cleared when switching to PostgreSQL).
• Field-to-field relations — relations are always between specific fields, not just entities. Drag from a field's right handle to another field's left handle. The FK column and referenced column are derived from the selected fields.
• Multi-target warnings — each warning lists the export targets it applies to, so a single "no fields" warning surfaces under PostgreSQL, Prisma, MongoDB, and TypeORM tabs without duplication.
• Zod validation on import — project JSON is validated against the Zod schema before loading, preventing corrupt or invalid data.

Supported Exports

Export	PostgreSQL	MongoDB	Features
PostgreSQL	Yes	—	Full DDL with all PG features
Prisma	Yes	Yes	Models, enums, relations, composite unique
TypeORM	Yes	—	Entity classes with all PG features
MongoDB	—	Yes	Validators with ObjectId refs + indexes

Exporter Feature Matrix

Feature	PostgreSQL	MongoDB	Prisma	TypeORM
Tables/collections	Yes	Yes	Yes	Yes
Primary keys	Yes	—	Yes	Yes
Unique constraints	Yes	—	Yes	Yes
Composite unique	Yes	—	Yes	Yes
Foreign keys / relations	Yes	Refs	Yes	Yes
Referential actions	Yes	—	—	—
CHECK constraints	Yes	—	—	Yes
Generated columns	Yes	—	—	Yes
Comments	Yes	—	—	Yes
Index methods	Yes	—	—	Yes
Partial indexes (WHERE)	Yes	—	—	Yes
Index sort orders	Yes	—	Yes	—
Array types	Yes	Yes	Yes	Yes
Embedded objects	—	Yes	—	—
Enums	Yes	—	Yes	—

Testing

The project has 205 unit tests across 9 test files:

• schema.test.ts — Zod schema validation (8 tests)
• projectStore.test.ts — store actions: entities, fields, relations, indexes, unique constraints, dialect conversion, array round-trip (37 tests)
• validation.test.ts — name validation helpers (21 tests)
• warnings.test.ts — compatibility warning engine, multi-target grouping, many_to_many awareness (17 tests)
• sampleProject.test.ts — both sample projects (PostgreSQL + MongoDB), generation and JSON round-trip (29 tests)
• postgres.test.ts — PostgreSQL DDL exporter: all PG features (23 tests)
• prisma.test.ts — Prisma schema exporter (16 tests)
• mongodb.test.ts — MongoDB exporter: validators, relations, indexes (23 tests)
• typeorm.test.ts — TypeORM exporter: all PG features (31 tests)

Deployment

The app is a static SPA built with Vite. Deploy the dist/ directory to any static host:

Vercel

pnpm build
# Deploy dist/ via Vercel CLI or connect the repo

Netlify

pnpm build
# Publish directory: dist
# Build command: pnpm build

Any static host

pnpm build
# Upload the contents of dist/ to your web server

Known Limitations

• No undo/redo support
• No multi-user collaboration
• No direct database connection — export only
• Mobile/tablet layout is not optimized (desktop-first)
• No enum editor UI (enums exist in the data model but have no editor)
• Prisma exporter does not handle embedded relations for MongoDB
• MongoDB exporter does not support TTL, sparse, text, or geospatial indexes
• MongoDB exporter does not support capped or timeseries collection options

Future Improvements

• Undo/redo history
• Enum editor UI
• MongoDB TTL, sparse, text, and geospatial index options
• MongoDB capped and timeseries collection options
• Prisma embedded relation support for MongoDB
• Direct database connection for schema import
• Schema diff visualization
• More export targets (Knex, Sequelize, Drizzle)
• Collaborative editing via WebSocket

No AI Integrations

SchemaForge does not use any AI APIs, paid services, or external intelligence. All logic is local and deterministic.

License

MIT