sql-tson 🚀

High-Performance SQL to Token-Structured Object Notation (TSON) Converter & Parser for LLMs.

Reduce your LLM token consumption by 30% to 60% when feeding SQL query results (PostgreSQL, MySQL, SQLite, Knex, Prisma, Drizzle) into AI models like Gemini, OpenAI GPT-4o, Claude, and Llama.

💡 Why sql-tson?

When querying relational SQL databases for Retrieval-Augmented Generation (RAG) or AI Agents:

• ❌ Repeated Column Headers: Standard JSON duplicates column names ("user_id", "email", "created_at") on EVERY single row.
• ❌ SQL Type Overhead: BigInts, Decimals, Timestamptz, and UUIDs introduce extra formatting noise.
• ❌ High Costs: Wasting 50% of your context window on column key names inflates LLM API bills.

sql-tson eliminates key repetition by formatting SQL row arrays into TSON columnar layout, cutting input prompt tokens by half!

📊 Token Savings Benchmark

| SQL Query Output | Standard JSON Tokens | TSON Format Tokens | Token Savings | Savings % | | :--- | :--- | :--- | :--- | :--- | | 10 SQL Rows (10 cols) | ~1,450 tokens | ~670 tokens | 780 tokens | 53.7% ⚡ | | 50 SQL Rows (10 cols) | ~7,200 tokens | ~2,950 tokens | 4,250 tokens | 59.0% ⚡ | | 200 SQL Rows (10 cols) | ~28,500 tokens | ~11,200 tokens | 17,300 tokens | 60.7% ⚡ |

📦 Installation

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

⚡ Quick Start

1. SQL Query Results $\rightarrow$ TSON (Prompt Context)

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

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

// Convert to TSON (and log to SAVINGS_TRACKER.json)
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
created_at: 2026-08-27T15:45:00.000Z, 2026-08-27T15:46:12.000Z
*/

2. TSON AI Response $\rightarrow$ SQL Row Objects

import { tsonToSql } from 'sql-tson';

const tsonLlmOutput = `
first_name: Elena, David
last_name: Rostova, Kim
email: [email protected], [email protected]
role: Security Lead, DevOps Lead
`;

const rows = tsonToSql(tsonLlmOutput);
console.log(rows);
// [ { first_name: 'Elena', last_name: 'Rostova', ... }, { first_name: 'David', ... } ]

3. Generate Parameterized SQL INSERT Queries

import { tsonToSqlInsert } from 'sql-tson';

const tsonLlmOutput = `
first_name: Elena, David
email: [email protected], [email protected]
`;

// Generates parameterized query for PostgreSQL, MySQL, or SQLite
const query = tsonToSqlInsert(tsonLlmOutput, {
  tableName: 'users',
  dialect: 'postgres'
});

console.log(query.text);
// INSERT INTO "users" ("first_name", "email") VALUES ($1, $2), ($3, $4);

console.log(query.values);
// ['Elena', '[email protected]', 'David', '[email protected]']

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

4. Live Terminal Test & Demo

Run the interactive CLI test suite:

npm run demo

🛠️ API Reference

sqlToTson(sqlRows, options?)

Converts SQL query results into TSON.

Options (SqlTsonOptions)

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | style | 'tabular' \| 'compact' | 'tabular' | 'tabular' for indented headers; 'compact' for pipe-delimited single lines. | | omitColumns | string[] | [] | Columns to exclude (e.g. ['password_hash']). | | includeColumns | string[] | undefined | Exclusive columns to include. | | formatDates | 'iso' \| 'timestamp' \| 'raw' | 'iso' | Date/Timestamptz formatting style. | | bigIntFormat | 'number' \| 'string' | 'number' | Casts BigInt/Decimal values. | | trackSavings | boolean | false | Automatically updates SAVINGS_TRACKER.json. |

tsonToSqlInsert(tsonString, options?)

Generates a parameterized SQL INSERT statement ($1, $2 for Postgres, ? for MySQL/SQLite).

👤 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