CH-ORM is an elegant, Eloquent-style ORM for ClickHouse, designed to make working with ClickHouse analytics as simple as working with regular databases.
## 🚀 Features - ✅ **Eloquent-style API** – Intuitive ORM for ClickHouse - ✅ **Built-in CLI** – `chorm migrations`, `chorm models`, `chorm seeders` - ✅ **Production-Ready** – Optimized for high-performance analytics - ✅ **Seamless Migrations** – Schema migrations similar to Laravel/Rails - ✅ **Modern TypeScript Support** – Strongly typed, DX-focused - ✅ **Connection Pooling** – Efficient connection management - ✅ **Query Builder** – Fluent, chainable query interface ## 📦 Installation ```bash # Using npm npm install @iarayan/ch-orm # Using yarn yarn add @iarayan/ch-orm # Using pnpm pnpm add @iarayan/ch-orm # Global installation (for CLI access from anywhere) npm install -g @iarayan/ch-orm ``` ## 🔍 Quick Start ### Connection Setup ```typescript import { Connection, Model } from "@iarayan/ch-orm"; // Create a connection const connection = new Connection({ host: "localhost", port: 8123, database: "default", username: "default", password: "", protocol: "http", // or "https" timeout: 30000, // connection timeout in ms debug: false, // set to true to log queries }); // Set the connection for all models Model.setConnection(connection); ``` ### Connection Pool (Recommended for Production) ```typescript import { ConnectionPool, Model } from "@iarayan/ch-orm"; // Create a connection pool const pool = new ConnectionPool( { host: "localhost", port: 8123, database: "default", username: "default", password: "", protocol: "http", }, { minConnections: 2, maxConnections: 10, idleTimeoutMillis: 60000, acquireTimeoutMillis: 30000, validateOnBorrow: true, } ); // Option 1: Use the pool for a specific operation const result = await pool.withConnection(async (connection) => { return await connection.query("SELECT * FROM users"); }); // Option 2: Set the pool for all models Model.setConnection(pool); ``` ### Environment Configuration CH-ORM will automatically load configuration from environment variables or a .env file: ``` CLICKHOUSE_HOST=localhost CLICKHOUSE_PORT=8123 CLICKHOUSE_DATABASE=default CLICKHOUSE_USERNAME=default CLICKHOUSE_PASSWORD= CLICKHOUSE_PROTOCOL=http CLICKHOUSE_DEBUG=false CLICKHOUSE_MIGRATIONS_PATH=./migrations CLICKHOUSE_MODELS_PATH=./models CLICKHOUSE_SEEDERS_PATH=./seeders ``` ### Defining Models ```typescript import { Model, Table, Column, PrimaryKey } from "@iarayan/ch-orm"; @Table("users") class User extends Model { @PrimaryKey() id: string; @Column() name: string; @Column() email: string; @Column({ type: "DateTime", defaultExpression: "now()" }) created_at: Date; } ``` ### Querying Data ```typescript // Find by primary key const user = await User.find("1234"); // Basic query builder const users = await User.query() .where("age", ">", 18) .orderBy("created_at", "DESC") .limit(10) .get(); // Raw queries with options const result = await connection.query( "SELECT * FROM users WHERE email = ?", ["user@example.com"], { format: "JSON", timeout_seconds: 30, max_rows_to_read: 1000, clickhouse_settings: { max_block_size: 100000, min_insert_block_size_rows: 1000, }, } ); ``` ### Creating Records ```typescript // Create and save in one step const user = await User.createAndSave({ name: "John Doe", email: "john@example.com", }); // Create instance first, then save const user = User.create({ name: "John Doe", email: "john@example.com", }); await user.save(); // Insert multiple records directly await User.insert([ { name: "John Doe", email: "john@example.com" }, { name: "Jane Smith", email: "jane@example.com" }, ]); // Insert with query options await User.createAndSave( { name: "John Doe", email: "john@example.com", }, { format: "JSON", timeout_seconds: 30, max_rows_to_read: 1000, clickhouse_settings: { max_block_size: 100000, min_insert_block_size_rows: 1000, }, } ); ``` ## 🔄 Migrations ```typescript import { Migration, Blueprint } from "@iarayan/ch-orm"; export default class CreateUsersTable extends Migration { public async up(): Promise