sql-tson-sdk 🚀

Unified Bi-directional SQL $\leftrightarrow$ TSON (Token-Structured Object Notation) Converter & Query Generator SDK for LLMs & RAG Applications.

Cuts 50% of prompt input tokens and 50% of AI output generation tokens when communicating between SQL databases (PostgreSQL, MySQL, SQLite, MSSQL, Knex, Prisma, Drizzle) and AI models like Gemini, OpenAI GPT-4o, Claude, and Llama.

💡 Why sql-tson-sdk?

When building SQL-driven AI Agents or RAG pipelines:

1. Read Path Overhead: Sending raw SQL query rows formatted with JSON.stringify() duplicates column header strings across every record.
2. Write Path Cost & Latency: Forcing LLMs to reply in verbose JSON or raw SQL strings inflates output costs by 3x to 4x and doubles generation latency.

sql-tson-sdk provides a single unified SDK to handle both directions:

• sqlToTson(): Serializes SQL query rows into columnar TSON for prompt inputs.
• tsonToSqlInsert(): Converts LLM TSON responses into Parameterized SQL INSERT statements ($1, $2 for Postgres, ? for MySQL/SQLite).
• tsonToSqlUpdate(): Converts LLM TSON responses into Parameterized UPDATE statements.
• tsonToSqlWhere(): Converts LLM TSON filter responses into SQL WHERE clauses.

📊 Bi-Directional Token Savings Benchmark

| Operation | Standard JSON Format | TSON Format | Token Savings | Speedup | | :--- | :--- | :--- | :--- | :--- | | Read Path (Prompt Context) | ~14,500 tokens | ~6,700 tokens | 7,800 tokens saved | 53.7% Less Input Cost ⚡ | | Write Path (LLM Output) | ~5,800 tokens | ~2,350 tokens | 3,450 tokens saved | ~2.2x Faster Generation ⚡ |

📦 Installation

npm install sql-tson-sdk
# or
yarn add sql-tson-sdk
# or
pnpm add sql-tson-sdk

⚡ Quick Start

1. Read Path: SQL Query Rows $\rightarrow$ TSON (Prompt Context)

import { sqlToTson } from 'sql-tson-sdk';
import { Pool } from 'pg';

const pool = new Pool();
const { rows } = await pool.query('SELECT user_id, first_name, email, role FROM users WHERE status = $1', ['active']);

// Convert to TSON prompt context
const tsonPrompt = sqlToTson(rows, { trackSavings: true });

console.log(tsonPrompt);
/*
user_id: 101, 102
first_name: Abhi, Sarah
email: [email protected], [email protected]
role: Architect, AI Engineer
*/

2. Write Path: LLM TSON Response $\rightarrow$ Parameterized SQL INSERT

import { tsonToSqlInsert } from 'sql-tson-sdk';

const llmTsonOutput = `
first_name: Abhi, Sarah
last_name: Asok, Chen
email: [email protected], [email protected]
role: Architect, AI Engineer
`;

// Generate Parameterized Query for PostgreSQL
const query = tsonToSqlInsert(llmTsonOutput, {
  tableName: 'users',
  dialect: 'postgres',
  returning: true
});

console.log(query.text);
// INSERT INTO "users" ("first_name", "last_name", "email", "role") VALUES ($1, $2, $3, $4), ($5, $6, $7, $8) RETURNING *;

console.log(query.values);
// ['Abhi', 'Asok', '[email protected]', 'Architect', 'Sarah', 'Chen', '[email protected]', 'AI Engineer']

// Execute directly with pg pool!
await pool.query(query.text, query.values);

3. Generate Parameterized UPDATE Query

import { tsonToSqlUpdate } from 'sql-tson-sdk';

const updateTson = `
id: 101
status: completed
updated_at: 2026-08-27T16:55:00.000Z
`;

const updateQuery = tsonToSqlUpdate(updateTson, {
  tableName: 'users',
  whereColumns: ['id'],
  dialect: 'postgres'
});

console.log(updateQuery.text);
// UPDATE "users" SET "status" = $1, "updated_at" = $2 WHERE "id" = $3;

4. Interactive Terminal Demo

Run the interactive CLI demonstration:

npm run demo

Check cumulative token savings logged automatically in SAVINGS_TRACKER.json:

import { getGlobalSavingsTracker } from 'sql-tson-sdk';

const tracker = getGlobalSavingsTracker();
console.log(tracker.getStats());

🛠️ API Reference

| Function | Direction | Description | | :--- | :--- | :--- | | sqlToTson(sqlRows, options?) | SQL -> TSON | Converts SQL query rows/arrays to TSON prompt strings. | | tsonToSql(tsonStr, options?) | TSON -> SQL Rows | Parses TSON strings back into JS SQL row objects. | | tsonToSqlInsert(tsonStr, options?) | TSON -> INSERT | Generates parameterized SQL INSERT statements ($1, ?). | | tsonToSqlUpdate(tsonStr, options?) | TSON -> UPDATE | Generates parameterized SQL UPDATE statements. | | tsonToSqlWhere(tsonStr, options?) | TSON -> WHERE | Generates parameterized SQL WHERE filter clauses. |

👤 Author & Contact

Developed with ❤️ by Abhi Asok.

For business inquiries, collaboration, or support:

• 📧 Email: [email protected]
• 📞 Phone / WhatsApp: +91 9142125724
• 💼 LinkedIn: linkedin.com/in/abhi-asok-09439788
• 🐙 GitHub: github.com/AbhiArvension

📄 License

MIT © Abhi Asok