Skip to content
BranchesTags

Repository files navigation

⚡ Flash ORM

Go Version License: MIT Release npm version PyPI version

📗 Go Guide • 📘 TypeScript Guide • 📙 Python Guide • 🦀 Rust Guide • 📋 Release Notes

image

A powerful, database-agnostic ORM built in Go with multi-database support and type-safe code generation for Go, JavaScript/TypeScript, Python, Kotlin, Java, and Rust.

✨ Features

  • 🗃️ Multi-Database Support: PostgreSQL, MySQL, SQLite, ScyllaDB/Cassandra, ClickHouse (full ORM)
  • 🔄 Migration Management: Create, apply, and track migrations with transaction safety
  • 📤 Smart Export System: JSON, CSV, SQLite formats
  • 🔧 Code Generation: Type-safe code for Go, TypeScript/JavaScript, Python, Kotlin, Java, and Rust
  • 🎯 Typed JSON Columns: @json annotations generate typed classes for JSONB with auto-serialization
  • 🔄 Smart Migrations: Auto-detects column/table renames (preserves data), generates reversible down migrations
  • 🌱 Database Seeding: Generate realistic fake data for development
  • ⚡ Blazing Fast: Outperforms Drizzle and Prisma in benchmarks
  • 📊 FlashORM Studio: Visual database management for SQL, MongoDB, and Redis

📊 Performance

Operation FlashORM Drizzle Prisma
Insert 1000 Users 149ms 224ms 230ms
Complex Query x500 3156ms 12500ms 56322ms
Mixed Workload x1000 186ms 1174ms 10863ms
TOTAL 5980ms 17149ms 71510ms

2.8x faster than Drizzle, 11.9x faster than Prisma

🚀 Installation

Direct installer by platform

Linux

curl -fsSL https://lumos-labs-hq.github.io/flash/install.sh | bash

macOS

curl -fsSL https://lumos-labs-hq.github.io/flash/install.sh | bash

Windows PowerShell

irm https://lumos-labs-hq.github.io/flash/install.ps1 | iex

Package manager alternatives

# NPM (Node.js/TypeScript)
npm install -g flashorm

# Python
pip install flashorm

# Go
go install github.com/Lumos-Labs-HQ/flash@latest

🏁 Quick Start

# 1. Initialize project (auto-detects Go/Node/Python/Kotlin/Java/Rust)
flash init --postgresql  # or --mysql, --sqlite, --scylla, --clickhouse

# 2. Set database URL
export DATABASE_URL="postgres://user:pass@localhost:5432/mydb"

# 3. Create and apply migrations
flash migrate "create users table"
flash apply

# 4. Generate type-safe code
flash gen

📋 Commands

Command Description
flash init Initialize project
flash migrate <name> Create migration
flash apply Apply migrations
flash down Rollback migration
flash status Show status
flash pull Extract schema from database
flash studio Launch visual editor
flash export Export database
flash seed Seed with fake data
flash gen Generate type-safe code
flash gen -f Force regenerate (skip cache)
flash gen --db <name> Generate for specific database
flash dblist List all configured databases
flash issues File a validated bug/feature report to the Flash repo
flash update Update plugins and flash binary
flash uninstall Remove flash and ~/.flash

🤖 AI Agent Support (FLASH.md)

When you run flash init, FlashORM generates a FLASH.md file in your project root. This file is a complete, self-contained reference designed for AI coding agents (Cursor, Copilot, Kiro, etc.) — so they can drive FlashORM correctly without guessing.

FLASH.md contains:

  • The exact database/provider for this project
  • Query parameter style ($1 vs ?) for your database
  • Complete schema and query examples from your scaffolding
  • All annotations: @cache, @json, @required
  • Supported databases table with parameter styles
  • Caching annotation syntax with examples in all 6 languages
  • Typed JSON column examples in all 6 languages
  • How to file bugs via flash issues

Keep FLASH.md committed — agents on any machine can read it.

🐛 flash issues

File a structured bug report or feature request directly to the Flash GitHub repo:

# Bug report
flash issues \
  -k bug \
  -t "gen: short description of the problem" \
  -b "What were you doing and what did Flash do" \
  --repro "1. flash init --postgresql  2. flash gen  3. ..." \
  --expected "What should have happened" \
  --actual "What happened, including the exact error"

# Feature request
flash issues -k feature -t "codegen: add X support" -b "Description"

# Preview without submitting
flash issues -k bug -t "..." -b "..." --print

# Submit without confirm prompt
flash issues -k bug -t "..." -b "..." --repro "..." -y
Flag Description
-k Kind: bug (default), feature, question, docs
-t Title (required, must be descriptive)
-b Body (required)
--repro Reproduction steps (required for bugs)
--expected Expected behavior
--actual Actual behavior / error text
--print Compose and print without submitting
-y Skip confirmation prompt

The command validates the report before filing — it rejects empty titles, vague bodies, and bug reports missing reproduction steps.

🗄️ Multi-Database Support

Configure multiple databases in one project:

[[databases]]
name = "main"
provider = "postgresql"
url_env = "DATABASE_URL"
schema_dir = "db/main/schema"
queries = "db/main/queries/"
migrations_path = "db/main/migrations"
default = true

[databases.gen.kotlin]
enabled = true
package = "com.example.main.flashgen"

[[databases]]
name = "analytics"
provider = "clickhouse"
url_env = "ANALYTICS_URL"
schema_dir = "db/analytics/schema"
queries = "db/analytics/queries/"

[databases.gen.go]
enabled = true
out = "gen/analytics"

All commands support --db <name>: flash gen --db main, flash apply --db analytics, flash studio --db main

🗄️ Database Support

Database ORM Support Studio
PostgreSQL ✅ Full ✅ SQL Studio
MySQL ✅ Full ✅ SQL Studio
SQLite ✅ Full ✅ SQL Studio
ScyllaDB / Cassandra ✅ Full(not yet for Rust ) ✅ SQL Studio
ClickHouse ✅ Beta ✅ SQL Studio
MongoDB ❌ ✅ Visual Management
Redis ❌ ✅ Visual Management

🔧 Code Generation

FlashORM generates type-safe query code from your SQL files. Auto-detects project type on flash init.

Go

[gen.go]
enabled = true
out = "flash_gen"
driver = "pgx"  # or "database/sql" (default)

TypeScript / JavaScript

[gen.js]
enabled = true
out = "flash_gen"
driver = "pg"  # pg | postgres | mysql2 | better-sqlite3 | bun:sqlite

Python

[gen.python]
enabled = true
out = "flash_gen"
async = true
driver = "asyncpg"  # asyncpg | psycopg3 | pymysql | aiosqlite | sqlite3

Kotlin

[gen.kotlin]
enabled = true
out = "src/main/kotlin/com/example/db/flashgen"
package = "com.example.db.flashgen"
driver = "jdbc"  # jdbc (default) | exposed | r2dbc

Generates: Models.kt, UsersQueries.kt, Queries.kt (unified entry point)

val q = Queries.newq(conn)
val user = q.getUser(42)           // Users?
val posts = q.getPostsByUser(42)   // List<GetPostsByUserRow>

Java

[gen.java]
enabled = true
out = "src/main/java/com/example/db/flashgen"
package = "com.example.db.flashgen"
driver = "jdbc"  # jdbc (default) | jooq | hibernate

Generates: Users.java, UsersQueries.java, Queries.java (unified entry point)

var q = Queries.newq(conn);
Users user = q.getUser(42);                          // Users
List<GetPostsByUserRow> posts = q.getPostsByUser(42); // List<GetPostsByUserRow>

Rust

[gen.rust]
enabled = true
out = "src/flash_gen"
driver = "sqlx"  # sqlx (default)

Generates: mod.rs, models.rs, db.rs, users.rs (per-query-file modules)

let queries = Queries::new(pool);
let user = queries.get_user(1).await?;               // Users
let posts = queries.list_posts_by_user(1).await?;    // Vec<GetPostsByUserRow>

Features:

  • Async by default using sqlx
  • #[derive(FromRow)] on all model structs
  • query_scalar for single-column results, query_as for structs
  • PostgreSQL, MySQL, SQLite support
  • Proper Option<T> for nullable columns

🎯 Typed JSON Columns

Generate typed classes for JSONB columns with auto-serialization. No manual JSON parsing needed.

Inline Definition

-- name: GetUser :one
-- @json settings {"theme": "string", "language": "string", "font_size": "int"}
-- @json metadata {"level": "int", "badges": "string[]", "xp_points": "int"}
SELECT id, name, settings, metadata FROM users WHERE id = $1;

Import from File

-- name: GetUser :one
-- @json import user_settings.json as settings
SELECT id, name, settings FROM users WHERE id = $1;

db/json/user_settings.json:

{
   "theme": "string",
   "language": "string",
   "font_size": "int",
   "notifications": "boolean"
}

Config:

json_path = "db/json"

Supported Types

string · int · float · boolean · string[] · int[] · float[] · boolean[] · any

Generated Output

All fields are nullable. Unmentioned JSON fields accessible via .raw / .get("key").

// Auto-generated:
data class Settings(
    val theme: String?,
    val language: String?,
    val fontSize: Int?,
    val raw: JsonObject? = null
) {
    fun toJson(): String
    fun get(key: String): String?  // access any field not in the definition
    companion object { fun fromJson(json: String?): Settings? }
}

// Usage — everything is typed:
val user = queries.getUser(id)
val theme = user?.settings?.theme           // String?
val extra = user?.settings?.get("custom")   // access unmentioned fields

Works with SELECT, INSERT, UPDATE, and RETURNING. All 6 languages supported.

🔧 Configuration

version = "2"
schema_dir = "db/schema"
queries = "db/queries/"
migrations_path = "db/migrations"
json_path = "db/json"     # optional: directory for @json import files
env_path = "config/.env"   # optional: custom .env file path

[database]
provider = "postgresql"
url_env = "DATABASE_URL"

[gen.go]
enabled = true

📊 FlashORM Studio

SQL Studio (PostgreSQL, MySQL, SQLite, ScyllaDB, ClickHouse)

flash studio
flash studio "postgres://user:pass@localhost:5432/mydb"
flash studio "scylla://localhost:9042/keyspace"
flash studio "clickhouse://localhost:9000"

Features: Schema designer, data browser, relationship visualization, auto-migration creation

MongoDB Studio

flash studio "mongodb://localhost:27017/mydb"
flash studio "mongodb+srv://user:pass@cluster.mongodb.net/mydb"

Redis Studio

flash studio "redis://localhost:6379"
flash studio "redis://:password@localhost:6379"

🌱 Database Seeding

flash seed                                    # seed all tables
flash seed --count 100                        # custom count
flash seed users:100 posts:500 comments:1000  # per-table counts
flash seed --truncate --force                 # truncate and reseed

📤 Export System

flash export           # JSON (default)
flash export --csv     # CSV files per table
flash export --sqlite  # Portable SQLite file

🛠️ Advanced Usage

flash apply --force        # Production deployment
flash reset --force        # Reset database (development)
flash pull                 # Extract schema from existing database
flash raw "SELECT COUNT(*) FROM users;"
flash raw db/seed.sql      # Execute SQL file (supports comment blocks)

📚 Documentation

🤝 Contributing

git clone https://github.com/Lumos-Labs-HQ/flash.git
cd flash
make dev-setup
make build-all

📄 License

MIT License - see LICENSE file for details.

Built with ❤️ by Lumos Labs

About

A powerful, database-agnostic ORM built in Go with multi-database support and type-safe code generation for Go, JS/TS, Python, Java, Kotlin and Rust

lumos-labs-hq.github.io/flash/

Topics

bunjscassandradatabaseexpressjsgolangjavakotlinmysqlnodejsormpostgrespostgresqlpythonrustscylladbsqlitetursotypescipt

Resources

Readme
MIT license

Contributing

Contributing
Activity
Custom properties

Stars

33 stars

Watchers

0 watching

Forks

6 forks
Report repository

Releases

Packages

Used by

Contributors

Languages