kinetic-sql

library3.0.4jsnpmunverified

Kinetic SQL is a lightweight, type-safe Node.js client for PostgreSQL, MySQL, and SQLite, offering real-time subscriptions to database changes (INSERT, UPDATE, DELETE) without WebSockets. Version 3.0.4 is current and stable, with monthly releases. It features automatic TypeScript type generation from your database schema, built-in connection pooling, and a middleware API. Key differentiators include zero-config real-time events, a native NestJS module (KineticModule), and an RPC wrapper for stored procedures. Unlike traditional ORMs, it focuses on real-time reactivity and simplicity.

database

npm install kinetic-sql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KINETIC-SQL

kinetic-sql

databasejavascriptv3.0.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

KineticClient

✓ import { KineticClient } from 'kinetic-sql'

✗ const KineticClient = require('kinetic-sql')

ESM-only package; CommonJS require will fail. Use dynamic import() if needed.

KineticModule

✓ import { KineticModule } from 'kinetic-sql/nestjs'

✗ import { KineticModule } from 'kinetic-sql'

KineticModule is exported from 'kinetic-sql/nestjs', not the main entry point.

SubscriptionEvent

✓ import { SubscriptionEvent } from 'kinetic-sql'

TypeScript type for subscription event payloads.

Shows how to initialize KineticClient with PostgreSQL, run a query, and subscribe to real-time table changes.

import { KineticClient } from 'kinetic-sql'; async function main() { const client = await KineticClient.create({ type: 'pg', connectionString: process.env.DATABASE_URL ?? 'postgres://user:pass@localhost:5432/mydb', realtimeEnabled: true, }); // Auto-generated types after running npx k-sql gen const users = await client.query('SELECT * FROM users'); console.log(users); // Subscribe to changes on the 'users' table const subscription = client.subscribe('users', (event) => { console.log('Change detected:', event); }); // Later: subscription.unsubscribe(); await client.close(); } main().catch(console.error);

Debug

Known issues

breakingv3.0.0 replaced the old 'createClient' factory with 'KineticClient.create'. Old code using 'createClient' will break.

fix

Replace 'createClient(options)' with 'await KineticClient.create(options)'.

affects: <3.0.0

deprecatedUsing 'type: 'postgres'' is deprecated; use 'type: 'pg'' instead.

fix

Change 'type: 'postgres'' to 'type: 'pg'' in configuration.

affects: >=3.0.0

gotchaReal-time subscriptions require 'realtimeEnabled: true' in the config, and for MySQL you must install '@rodrigogs/mysql-events' separately.

fix

Ensure 'realtimeEnabled: true' is set and optional MySQL dependency is installed.

affects: >=3.0.0

gotchaAutomatic type generation via 'npx k-sql gen' requires the database to be running and accessible. It overwrites local type files.

fix

Run 'npx k-sql gen' only when database schema is stable; commit the generated types to version control.

affects: >=3.0.0

Errors

Common errors & fixes

Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'kinetic-sql'

Package is ESM-only; using require() in CommonJS project.

fix

Switch to ESM (type: 'module' in package.json) or use dynamic import: const { KineticClient } = await import('kinetic-sql');

TypeError: kineticClient.query is not a function

Client not properly initialized with await, or using a wrong import (e.g., default import instead of named).

fix

Ensure 'const client = await KineticClient.create(...)' and use the named import { KineticClient }.

Error: Realtime subscriptions require 'realtimeEnabled: true' or missing driver

PostgreSQL requires 'realtimeEnabled: true'; MySQL requires both the flag and '@rodrigogs/mysql-events' installed.

fix

Set 'realtimeEnabled: true' in config for Postgres; for MySQL install the extra package and enable the flag.

Upgrade

Version history

3.0.4latest on npm

Audit

Dependencies

drizzle-ormrequiredRequired for schema generation and query building

postgresoptionalPostgreSQL driver (required for pg type)

mysql2optionalMySQL driver (required for mysql type)

@rodrigogs/mysql-eventsoptionalNeeded for MySQL real-time subscriptions

better-sqlite3optionalSQLite driver (required for sqlite type)

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/serial-committer/kinetic-sql ↗

packagekinetic-sql ↗

homepagehttps://github.com/serial-committer/kinetic-sql#readme ↗