⚡ Kinetic SQL

A lightweight, type-safe, real-time SQL Engine for Node.js. The "Tailwind" of Database Clients.

Kinetic SQL is a next-gen Node.js client that wraps PostgreSQL, MySQL & SQLite with features that enable the developer to interact with databases seamlessly.

🚀 Experience the Live Demo: Real-Time Stock Simulator

📜 Features

Kinetic SQL turns your database into a reactive extension of your code.

• ✨ RPC Wrapper: Call your stored procedures and database functions just like native JavaScript methods.
• ⚡ Real-Time Subscriptions: Listen to INSERT, UPDATE, and DELETE events instantly.
• 🌍 Universal Fit: Built for Express, Fastify, and Vanilla JS, with a dedicated module for seamless NestJS integration out of the box.
• 🚀 NestJS Native: Drop-in KineticModule for zero-config integration with NestJS Framework.
• 🤖 Automatic Type Generation: It reads your schema and auto-generates type safety. You never have to manually write a TypeScript interface again.
• 🛡️ Type Safety: Full TypeScript support for schemas and configurations.
• ♻️️ Connection Pooling: Built-in management for high-scale apps.

📈 The Proof: Live Demo

To stress-test the real-time event mapping and zero-bloat architecture, we built a high-frequency Live Stock Market Simulator. It runs on a Vercel frontend and Render backend, handling hundreds of database ticks a minute with a 0-second cold start.

👉 View the Live Stock Simulator

🚀 Quick Start

1. Install

# For PostgreSQL:
npm install kinetic-sql drizzle-orm postgres

# For MySQL:
npm install kinetic-sql drizzle-orm mysql2 @rodrigogs/mysql-events

# For SQLite (Local Dev / Edge):
npm install kinetic-sql better-sqlite3

2. Initialize

import { KineticClient } from 'kinetic-sql';

/* PostgreSQL/MySQL Example */
/* Connects using your DATABASE_URL env var by default */
const db = await KineticClient.create({
  type: 'pg', // or 'mysql'
  connectionString: process.env.DATABASE_URL,
  realtimeEnabled: true
});

/* SQLite Example */
const db = await KineticClient.create({
  type: 'sqlite',
  filename: './dev.db'
});

3. Generate Types (The Magic)

Run this command in your terminal. It reads your DB and patches the library automatically.

# PostgreSQL (Default)
npx k-sql gen --connection "postgres://..."
OR
npx k-sql gen --type pg --host localhost --user postgres --db mydb

# MySQL
npx k-sql gen --type mysql --host localhost --user root --db mydb

# SQLite
npx k-sql gen --type sqlite --db ./dev.db

📚 Usage

🚀 NestJS Integration

Kinetic SQL exports a native NestJS module for zero-config setup. Using the library in your NestJS app is as simple as:

// app.module.ts
import { Module } from '@nestjs/common';
import { KineticModule } from 'kinetic-sql/nestjs';

@Module({
imports: [KineticModule.forRoot({
    type: 'sqlite', // or 'pg' | 'mysql'
    filename: './dev.db',
    debug: true, // 👈 Enable colorful logs
  }),],
})
export class AppModule {}

⚡Realtime Subscriptions

Listen to database events without setting up WebSockets.

Use the subscribe method to listen to any changes to the table you want to monitor. In the example below, we listen to changes on the tasks table.

/* 'tasks' is auto-completed! */
const sub = await db.subscribe('tasks', (event) => {
console.log(event.action); // 'INSERT' | 'UPDATE' | 'DELETE'
console.log(event.data.title); // Typed Reference!
});

// If you want to stop listening to the events, you can simply call:
await sub.unsubscribe();

🧠 RPC Wrapper: The Robust Magic Bridge ✨

Extend SQL with JavaScript OR Call stored procedures as native JS methods bridging the gap between your Backend and the Database.

Extend SQL with JavaScript: Why write complex SQL logic when you can just write JavaScript? Define a function in your Node.js app and call it inside your SQL queries. 😊

  Example:

/* Define a function in your app */
client.raw.function('calculate_tax', (price, taxRate) => {
  return price * (1 + taxRate);
});

/* Use it directly in SQL! */
const result = client.raw.prepare(`
  SELECT 
    symbol, 
    price, 
    calculate_tax(price, 0.18) as final_price 
  FROM stocks
`).all();

console.log(result);
/* Output: [{ symbol: 'KINETIC-AI', price: 150, final_price: 177 }, ...] */

Call Stored Procedures: Invoke complex database logic without writing raw SQL strings (Using Postgres for the examples below) ✨

  Example 1:

/* Calls the 'create_user' stored procedure safely along with auto-completion and type-safety! */
const { data, error } = await client.rpc('create_user', {
  username: 'kapil',
  role: 'admin'
});

  Example 2:

/* Calls the stored procedure 'add_todo' (Auto-completed!) */
const { data, error } = await db.rpc('add_todo',
    /* Param names are checked! */
    { title: "Build cool app",  user_id: 123 }
);

Standard Queries (via Drizzle) ✨

We expose the full power of Drizzle ORM under the hood.

import { sql, eq } from 'kinetic-sql';

const users = await db.orm
.select()
.from(sql`users`)
.where(eq(sql`id`, 1));

⚙️ Configuration

PostgreSQL

const db = await KineticClient.create({
type: 'pg',
host: 'localhost',
port: 5432,
user: 'postgres',
password: 'password',
database: 'mydb',
realtimeEnabled: true
});

MySQL

const db = await KineticClient.create({
type: 'mysql',
host: 'localhost',
port: 3306,
user: 'root',
password: 'password',
database: 'mydb',
realtimeEnabled: true // Requires Binary Logging enabled on server
});

SQLite

const db = await KineticClient.create({
  type: 'sqlite',
  filename: './dev.db' // Path to your file
});

MSSQL

Support for MSSQL is currently in developent and will be released soon 😊

⚠️ Requirements

• Node.js: 18+
• PostgreSQL: 12+ (Native LISTEN/NOTIFY used)
• MySQL: 5.7+ (Requires Binary Logging Enabled i.e. log_bin = ON for Realtime features)
• SQLite: 3+ (Bundled with better-sqlite3)

📄 License

• MIT – See LICENSE for details.

🐞 Bugs, Issues, and Feature Requests

Kinetic SQL is actively maintained. If you run into any issues, have feature requests, please feel free to open an issue on the GitHub repo:

👉 Kinetic SQL Feature Requests & Issue Tracker

If you found this library helpful in escaping ORM bloat, a ⭐️ on the repository is greatly appreciated!