flashorm 2.0.8

A powerful, database-agnostic ORM with multi-database support and type-safe code generation

FlashORM

A powerful, database-agnostic migration CLI tool built in Go with multi-database support, visual database editor (FlashORM Studio), and type-safe code generation for JavaScript/TypeScript.

✨ Features

• 🎨 FlashORM Studio: Visual database editor with React-based schema visualization
• 🗃️ Multi-Database Support: PostgreSQL, MySQL, SQLite
• 🔄 Migration Management: Create, apply, and track migrations
• 🔒 Safe Migration System: Transaction-based execution with automatic rollback
• 📤 Smart Export System: Multiple formats (JSON, CSV, SQLite)
• 🔧 Type-Safe Code Generation: Generate fully typed JavaScript/TypeScript code
• ⚡ Blazing Fast: 2.5x faster than Drizzle, 10x faster than Prisma
• 💻 Raw SQL Execution: Execute SQL files or inline queries
• 🎯 Prisma-like Commands: Familiar CLI interface
• 🎨 Enum Support: Full PostgreSQL ENUM support

📊 Performance

Operation	FlashORM	Drizzle	Prisma
Insert 1000 Users	158ms	224ms	230ms
Insert 10 Cat + 5K Posts + 15K Comments	2410ms	3028ms	3977ms
Complex Query x500	4071ms	12500ms	56322ms
Mixed Workload x1000 (75% read, 25% write)	186ms	1174ms	10863ms
Stress Test Simple Query x2000	122ms	160ms	223ms
TOTAL	6947ms	17149ms	71551ms

🚀 Installation

pip install flashorm

🏁 Quick Start

1. Initialize Project

flash init --postgresql  # or --mysql, --sqlite

This creates:

your-project/
├── flash.config.json
├── .env
└── db/
    ├── schema/
    │   └── schema.sql
    └── queries/
        └── users.sql

2. Configure Database

# .env file
DATABASE_URL=postgresql://user:password@localhost:5432/mydb

3. Define Schema

db/schema/schema.sql

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
);

4. Write Queries

db/queries/users.sql

-- name: GetUser :one
SELECT id, name, email, created_at, updated_at FROM users
WHERE id = $1 LIMIT 1;

-- name: CreateUser :one
INSERT INTO users (name, email)
VALUES ($1, $2)
RETURNING id, name, email, created_at, updated_at;

-- name: ListUsers :many
SELECT id, name, email, created_at, updated_at FROM users
ORDER BY created_at DESC;

-- name: UpdateUser :one
UPDATE users
SET name = $2, email = $3, updated_at = NOW()
WHERE id = $1
RETURNING id, name, email, created_at, updated_at;

-- name: DeleteUser :exec
DELETE FROM users WHERE id = $1;

5. Create Migration

flash migrate "create users table"

6. Apply Migration

flash apply

7. Generate Type-Safe Code

flash gen

Generated Types (flash_gen/index.d.ts)

// Code generated by FlashORM. DO NOT EDIT.

export interface Users {
  id: number | null;
  name: string;
  email: string;
  created_at: Date;
  updated_at: Date;
}

export interface GetUserResult {
  id: number | null;
  name: string;
  email: string;
  created_at: Date;
  updated_at: Date;
}

export class Queries {
  constructor(db: any);

  getUser(id: number): Promise<GetUserResult | null>;
  createUser(name: string, email: string): Promise<Users | null>;
  listUsers(): Promise<Users[]>;
  updateUser(id: number, name: string, email: string): Promise<Users | null>;
  deleteUser(id: number): Promise<void>;
}

export function New(db: any): Queries;

8. Use in Your Code

index.ts

import { Pool } from 'pg';
import { New } from './flash_gen/database';

const DATABASE_URL = process.env.DATABASE_URL || 'postgresql://postgres:postgres@localhost:5432/mydb';

async function main() {
    const pool = new Pool({
        connectionString: DATABASE_URL,
    });
    
    const db = New(pool);
    
    // Create user - fully type-safe!
    const newUser = await db.createUser('Alice', '[e-mail]');
    console.log('New user:', newUser);
    
    // Get user by ID
    const user = await db.getUser(newUser.id);
    console.log('Found user:', user);
    
    // List all users
    const users = await db.listUsers();
    console.log('All users:', users);
    
    // Update user
    const updated = await db.updateUser(newUser.id, 'Alice Smith', '[e-mail]');
    console.log('Updated user:', updated);
    
    await pool.end();
}

main().catch((err) => {
    console.error('Error:', err);
    process.exit(1);
});

📋 All Commands

Visual Database Editor

# Launch FlashORM Studio (web-based database editor)
flash studio

# Launch on custom port
flash studio --port 3000

# Connect to any database directly
flash studio --db "postgresql://user:pass@localhost:5432/mydb"

# Launch without opening browser
flash studio --browser=false

Studio Features:

• 📊 Data Browser: View and edit table data with inline editing
• 💻 SQL Editor: Execute queries with CodeMirror syntax highlighting
• 🎨 Schema Visualization: Interactive database diagram with React + ReactFlow
• 📤 CSV Export: Export query results to CSV
• 🔍 Search & Filter: Search across all tables
• ⚡ Real-time Updates: See changes immediately

Project Setup

# Initialize new project
flash init --postgresql
flash init --mysql
flash init --sqlite

Migrations

# Create new migration
flash migrate "migration name"

# Create empty migration
flash migrate "custom migration" --empty

# Apply all pending migrations
flash apply

# Apply with force (skip confirmations)
flash apply --force

# Check migration status
flash status

Code Generation

# Generate type-safe code
flash gen

Schema Management

# Pull schema from existing database
flash pull

# Pull with backup
flash pull --backup

# Pull to custom file
flash pull --output custom-schema.sql

Database Export

# Export as JSON (default)
flash export
flash export --json

# Export as CSV
flash export --csv

# Export as SQLite
flash export --sqlite

Database Operations

# Reset database (destructive!)
flash reset

# Reset with force
flash reset --force

# Execute raw SQL file
flash raw script.sql
flash raw migrations/seed.sql

# Execute inline SQL query
flash raw -q "SELECT * FROM users WHERE active = true"
flash raw "SELECT COUNT(*) FROM orders"

# Force file mode
flash raw --file queries/complex.sql

Help & Info

# Launch FlashORM Studio
flash studio

# Show version
flash --version
flash -v

# Show help
flash --help
flash <command> --help

⚙️ Configuration

flash.config.json

{
  "version": "2",
  "schema_path": "db/schema/schema.sql",
  "queries": "db/queries/",
  "migrations_path": "db/migrations",
  "export_path": "db/export",
  "database": {
    "provider": "postgresql",
    "url_env": "DATABASE_URL"
  },
  "gen": {
    "js": {
      "enabled": true,
    }
  }
}

🎨 PostgreSQL ENUM Support

Schema with ENUMs

CREATE TYPE user_role AS ENUM ('admin', 'user', 'guest');

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    role user_role NOT NULL DEFAULT 'user'
);

Query with ENUM

-- name: GetUsersByRole :many
SELECT id, name, role FROM users
WHERE role = $1;

Generated TypeScript

export type UserRole = 'admin' | 'user' | 'guest';

export interface Users {
  id: number | null;
  name: string;
  role: UserRole;
}

🔒 Safe Migrations

Every migration runs in a transaction with automatic rollback on failure:

$ flash apply
📦 Applying 2 migration(s)...
  [1/2] 20251103_create_users
      ✅ Applied
  [2/2] 20251103_add_email_index
      ✅ Applied
✅ All migrations applied successfully

If a migration fails:

❌ Failed at migration: 20251103_bad_migration
   Error: syntax error at or near "INVALID"
   Transaction rolled back. Fix the error and run 'flash apply' again.

🛡️ Conflict Detection

FlashORM automatically detects schema conflicts:

⚠️  Migration conflicts detected:
  - Table 'users' already exists
  - Column 'email' conflicts with existing column

Reset database to resolve conflicts? (y/n): y
Create export before applying? (y/n): y
📦 Creating export...
✅ Export created successfully
🔄 Resetting database and applying all migrations...

📤 Export Formats

JSON Export

flash export --json

{
  "timestamp": "2025-11-03 16:30:00",
  "version": "1.0",
  "tables": {
    "users": [
      {"id": 1, "name": "Alice", "email": "[e-mail]"}
    ]
  }
}

CSV Export

flash export --csv

Creates directory with individual CSV files per table.

SQLite Export

flash export --sqlite

Creates portable .db file.

🎨 FlashORM Studio

Launch the visual database editor:

flash studio

Open http://localhost:5555 (or your custom port)

Features:

1. Data Browser (/)

• View all tables in sidebar
• Click any table to view/edit data
• Double-click cells for inline editing
• Add/delete rows with intuitive modals
• Pagination (50 rows per page)
• Search across tables
• Foreign key hints

2. SQL Editor (/sql)

• Execute custom SQL queries
• CodeMirror editor with syntax highlighting
• Press Ctrl+Enter to run queries
• Export results to CSV
• Resizable split-pane interface
• Query history

3. Schema Visualization (/schema)

• Interactive database diagram
• React + ReactFlow rendering
• Automatic layout with Dagre algorithm
• Drag and drop tables
• Zoom and pan controls
• Foreign key relationship arrows
• MiniMap for navigation

Tech Stack:

• Backend: Go Fiber v2.52.9
• Frontend: React 18.2.0, ReactFlow 12.8.4, CodeMirror 5.65.2
• All assets embedded in single binary

💻 Raw SQL Execution

Execute SQL files or inline queries:

# Execute SQL file
flash raw script.sql

# Execute inline query
flash raw -q "SELECT * FROM users LIMIT 10"

# Auto-detection (file if exists, otherwise query)
flash raw "SELECT COUNT(*) FROM orders"

Features:

• ✅ Beautiful table output for SELECT queries
• ✅ Multi-statement execution
• ✅ Transaction support
• ✅ Auto-detection of file vs query
• ✅ Formatted error messages

Example Output:

$ flash raw -q "SELECT id, name, email FROM users LIMIT 3"

🎯 Database: postgresql

⚡ Executing query...
✅ Query executed successfully
📊 3 row(s) returned

┌────┬────────────┬─────────────────────┐
│ id │ name       │ email               │
├────┼────────────┼─────────────────────┤
│ 1  │ Alice      │ [e-mail]   │
│ 2  │ Bob        │ [e-mail]     │
│ 3  │ Charlie    │ [e-mail] │
└────┴────────────┴─────────────────────┘

🔧 Programmatic API

const flash = require('flashorm');

// Execute commands
flash.exec('status');
flash.exec('migrate "add users"');
flash.exec('apply');
flash.exec('studio'); // Launch Studio

// Get binary path
const binaryPath = flash.getBinaryPath();

📚 Examples

Check out complete examples:

• TypeScript Example
• Go Example

🐛 Troubleshooting

Bun Postinstall Blocked

bun pm trust flashorm

Binary Not Found

npm install -g flashorm --force

Database Connection Failed

Check your DATABASE_URL in .env file.

Studio Not Loading

Make sure port 5555 is not in use, or specify a different port:

flash studio --port 3000

📖 Documentation

• Full Documentation
• How It Works
• Technology Stack
• Contributing

🌟 Key Highlights

• Visual Database Editor: Manage your database visually with FlashORM Studio
• Raw SQL Support: Execute SQL files or queries directly from CLI
• Type-Safe: Full TypeScript support with generated types
• Fast: 2.5x-10x faster than popular ORMs
• Multi-DB: PostgreSQL, MySQL, and SQLite support
• Zero Config: Works out of the box with sensible defaults

📄 License

MIT License - see LICENSE

---