Package Exports

kinetic-sql
kinetic-sql/nestjs

Readme

⚡ Kinetic SQL

The Type-Safe, Real-Time SQL Client for Node.js. The "Tailwind" of Database Clients.

Zero Config. Full Autocomplete. Realtime by default.

Kinetic SQL is a next-gen Node.js client that wraps PostgreSQL, MySQL & SQLite with a developer experience similar to Supabase, but for your own backend.

✨ Features

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

🔮 RPC Wrapper: Call Stored Procedures and define Native JS functions as if they were local methods.
⚡ Real-Time Subscriptions: Listen to INSERT, UPDATE, and DELETE events instantly.
🔌 NestJS Native: Drop-in KineticModule for zero-config integration.
🛡️ Type Safety: Full TypeScript support for schemas and configurations.
🔌 Connection Pooling: Built-in management for high-scale apps.

🚀 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.

EXAMPLES:

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. 😊

/* 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: './prisma/dev.db' // Path to your file
});

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

kinetic-sql