Graft ORM

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

✨ Features

- 🎨 Graft 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 | Graft | Drizzle | Prisma |
|-----------|-------|---------|--------|
| Insert 1000 Users | 158ms | 224ms | 230ms |
| Complex Query x500 | 4071ms | 12500ms | 56322ms |
| Mixed Workload x1000 | 186ms | 1174ms | 10863ms |
| TOTAL | 6947ms | 17149ms | 71551ms |

🚀 Installation

``bash
npm install -g graft-orm
`

$3

Bun blocks postinstall scripts by default. After installation, run:

`bash
bun pm trust graft-orm
`

Or add to your package.json:
`json
{
"trustedDependencies": ["graft-orm"]
}
`

🏁 Quick Start

$3

`bash
graft init --postgresql # or --mysql, --sqlite
`

This creates:
`
your-project/
├── graft.config.json
├── .env
└── db/
├── schema/
│ └── schema.sql
└── queries/
└── users.sql
`

$3

`bash


.env file


DATABASE_URL=postgresql://user:password@localhost:5432/mydb
`

$3

db/schema/schema.sql
`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()
);
`

$3

db/queries/users.sql
`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;
`

$3

`bash
graft migrate "create users table"
`

$3

`bash
graft apply
`

$3

`bash
graft gen
`

Generated Types (graft_gen/index.d.ts)
`typescript
// Code generated by Graft. 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;
createUser(name: string, email: string): Promise;
listUsers(): Promise;
updateUser(id: number, name: string, email: string): Promise;
deleteUser(id: number): Promise;
}

export function New(db: any): Queries;
`

$3

index.ts
`typescript
import { Pool } from 'pg';
import { New } from './graft_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', 'alice@example.com');
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', 'alice.smith@example.com');
console.log('Updated user:', updated);

await pool.end();
}

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

📋 All Commands

$3

`bash


Launch Graft Studio (web-based database editor)

graft studio

Launch on custom port

graft studio --port 3000

Connect to any database directly

graft studio --db "postgresql://user:pass@localhost:5432/mydb"

Launch without opening browser

graft 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

$3

`bash


Initialize new project


graft init --postgresql
graft init --mysql
graft init --sqlite
`

$3

`bash


Create new migration

graft migrate "migration name"

Create empty migration

graft migrate "custom migration" --empty

Apply all pending migrations

graft apply

Apply with force (skip confirmations)

graft apply --force

Check migration status

graft status
`

$3

`bash


Generate type-safe code


graft gen
`

$3

`bash


Pull schema from existing database

graft pull

Pull with backup

graft pull --backup

Pull to custom file

graft pull --output custom-schema.sql
`

$3

`bash


Export as JSON (default)

graft export
graft export --json

Export as CSV

graft export --csv

Export as SQLite

graft export --sqlite
`

$3

`bash


Reset database (destructive!)

graft reset

Reset with force

graft reset --force

Execute raw SQL file

graft raw script.sql
graft raw migrations/seed.sql

Execute inline SQL query

graft raw -q "SELECT * FROM users WHERE active = true"
graft raw "SELECT COUNT(*) FROM orders"

Force file mode

graft raw --file queries/complex.sql
`

$3

`bash


Launch Graft Studio

graft studio

Show version

graft --version
graft -v

Show help

graft --help
graft --help
`

⚙️ Configuration

graft.config.json
`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,
"out": "graft_gen"
}
}
}
`

🎨 PostgreSQL ENUM Support

Schema with ENUMs
`sql
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
`sql
-- name: GetUsersByRole :many
SELECT id, name, role FROM users
WHERE role = $1;
`

Generated TypeScript
`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:

`bash
$ graft 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:
`bash
❌ Failed at migration: 20251103_bad_migration
Error: syntax error at or near "INVALID"
Transaction rolled back. Fix the error and run 'graft apply' again.
`

🛡️ Conflict Detection

Graft automatically detects schema conflicts:

`bash
⚠️ 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

$3


`bash
graft export --json
`
`json
{
"timestamp": "2025-11-03 16:30:00",
"version": "1.0",
"tables": {
"users": [
{"id": 1, "name": "Alice", "email": "alice@example.com"}
]
}
}
`

$3

`bash
graft export --csv
`
Creates directory with individual CSV files per table.

$3

`bash
graft export --sqlite
`
Creates portable .db file.

🎨 Graft Studio

Launch the visual database editor:

`bash
graft studio
`

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

Features:

$3

- 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

$3

- 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

- 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:

`bash


Execute SQL file

graft raw script.sql

Execute inline query

graft raw -q "SELECT * FROM users LIMIT 10"

Auto-detection (file if exists, otherwise query)

graft 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:
`bash
$ graft 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 │ alice@example.com │
│ 2 │ Bob │ bob@example.com │
│ 3 │ Charlie │ charlie@example.com │
└────┴────────────┴─────────────────────┘
`

🔧 Programmatic API

`javascript
const graft = require('graft-orm');

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

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

📚 Examples

Check out complete examples:
- TypeScript Example
- Go Example

🐛 Troubleshooting

$3

`bash
bun pm trust graft-orm
`

$3

`bash
npm install -g graft-orm --force
`

$3

Check your DATABASE_URL in .env file.

$3

Make sure port 5555 is not in use, or specify a different port:
`bash
graft studio --port 3000
``

📖 Documentation

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

🌟 Key Highlights

- Visual Database Editor: Manage your database visually with Graft 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

---