PuddySQL is a modular and extensible SQL toolkit for Node.js — designed to make dynamic queries, filters, pagination, and tag-based searches easy, safe, and powerful.
Built with composability in mind, each part of PuddySQL focuses on one job while integrating smoothly with the others. Whether you're working with SQLite or PostgreSQL, this package helps you build robust, readable, and scalable query logic.
npm install puddysql
- ✅ Safe, composable SQL queries with named methods
- 🔍 Powerful nested filters using JSON logic (AND/OR, operators, etc.)
- 🏷️ Built-in tag filtering engine for JSON/array-based fields
- 🔗 Dynamic JOIN builder with alias support
- 📃 Smart pagination with automatic counters
- 🧪 Strong input validation and type safety
To get started, please install the project dependencies. It is mandatory to run the build command afterward to ensure the module works correctly:
npm install npm run build:essentials
For API reference, check each module’s own documentation:
👉 See: docs/README.md
| Module | Description |
|---|---|
PuddySqlEngine |
Low-level query runner with DB abstraction |
PuddySqlInstance |
Manages databases and table bindings |
PuddySqlQuery |
High-level querying with filters and joins |
PuddySqlTags |
Parses tag filters into safe SQL conditions |
PuddySqlMigrator |
Version-based schema migration runner |
PuddySqlEvents |
Event name constants (Connection-Error, etc.) |
-
Node.js 18+ recommended
-
Works with:
- ✅ SQLite3
- ✅ PostgreSQL (via
pgadapter)
The PuddySql class is the main access point to all core features of the library.
You should not instantiate it directly — instead, use PuddySql.Instance.
Here's a quick overview of what's available:
| 📦 Static Property | 🔍 Description |
|---|---|
PuddySql.Instance |
🎮 Main SQL client class for managing databases (PostgreSQL or SQLite3) |
PuddySql.Query |
🧠 Query builder and smart search engine with advanced filtering |
PuddySql.Tags |
🏷️ Flexible tag system parser (with support for JSON arrays, boosts, etc.) |
PuddySql.Events |
🎯 Event name constants (Connection-Error, Migration-*) |
PuddySql.Migrator |
🚚 Version-based schema migration runner |
PuddySql.Utils |
🛠️ Useful utilities (object flattening, merge helpers, SQL formatters) |
PuddySql.pg |
🐘 PostgreSQL database engine (pg wrapper) |
PuddySql.sqlite3 |
📀 SQLite3 engine for local/in-memory usage (sqlite3 wrapper) |
Here’s how to get started using PuddySQL:
import path from 'path'; import { fileURLToPath } from 'url'; import PuddySql from 'puddysql'; const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); // 🎮 Create a new SQL instance const db = new PuddySql.Instance(); // 📡 Run queries (async () => { await db.initSqlite3(); // Insert a new user const table = await db.initTable({ name: 'tinytest', id: 'id' }, [ ['id', 'TEXT', 'PRIMARY KEY'], ['prompt', 'TEXT'], ['yay', 'BOOLEAN'] ]); console.log('Set'); console.log(await table.set('1', { prompt: 'pudding', yay: true })); console.log(await table.set('2', { prompt: 'cookie', yay: true })); console.log(await table.set('3', { prompt: 'brigadeiro', yay: true })); console.log(await table.set('4', { prompt: 'banana', yay: false })); console.log(await table.set('5', { prompt: 'chocolate', yay: true })); console.log('Get All'); console.log(await table.getAll()); // Find a user by ID console.log('Get'); const user = await table.get(1); console.log(user); // → { id: 1, prompt: 'pudding', yay: true } // Get a paginated list console.log('Search'); const data1 = await db.getTable('tinytest').search({ q: { group: 'AND', conditions: [{ column: 'prompt', value: 'pudding' }], }, }); const data2 = await table.search({ q: { group: 'OR', conditions: [ { column: 'prompt', value: 'pudding' }, { column: 'yay', value: false }, ], }, }); console.log(data1); console.log(data2); })();
PuddySQL ships with a small version-based migration runner:
const db = new PuddySql.Instance(); await db.initSqlite3(); const users = await db.initTable({ name: 'users', id: 'id' }, [ ['id', 'INTEGER', 'PRIMARY KEY'], ['name', 'TEXT'], ]); // Register migrations by version db.migrator.addMigration(1, async () => { await users.updateTable([['ADD', 'email', 'TEXT']]); }); // Run everything up to version 1 await db.startMigration(1);
See docs/PuddySqlMigrator.md for the full reference.
Feel free to fork, contribute, and create pull requests for improvements! Whether it's a bug fix or an additional feature, contributions are always welcome.
This project is licensed under the LGPL-3.0 License - see the LICENSE file for details.
🧠 Note: This documentation was written by ChatGPT, an AI assistant developed by OpenAI, based on the project structure and descriptions provided by the repository author.
If you find any inaccuracies or need improvements, feel free to contribute or open an issue!
Did you like this module? It’s part of the Tiny Essentials collection — a set of minimal yet powerful tools to make development easier. 👉 Click here to explore more Tiny Essentials modules
Made with tiny love!