NaturalSQL TypeScript

Lightweight library to convert your SQL database schema into a vector database, so LLMs can use real table/column context to generate more accurate SQL from natural language.

Problem

Sometimes you want to interact with SQL databases through an LLM without pulling in large frameworks with many unrelated features.

Solution

NaturalSQL extracts your database schema, vectorizes it using a configurable backend (chroma or sqlite) and configurable embedding provider (local or gemini), then performs semantic retrieval to return relevant schema context for your LLM.

Installation

# Base package
npm i naturalsql

Install optional dependencies based on your configuration:

# Chroma + local embeddings
npm i chromadb @xenova/transformers

# SQLite + local embeddings
npm i better-sqlite3 @xenova/transformers

# SQLite + Gemini embeddings
npm i better-sqlite3 @google/generative-ai

# Chroma + Gemini embeddings
npm i chromadb @google/generative-ai

# PostgreSQL driver support
npm i pg

# MySQL driver support
npm i mysql2

# SQL Server driver support
npm i mssql

Node.js >=18 is required. For Gemini, this package uses @google/generative-ai. Use environment variables for API keys (for example, GEMINI_API_KEY), never hardcode secrets.

Supported SQL engines

• PostgreSQL
• MySQL
• SQL Server
• SQLite

Quick start

import { NaturalSQL } from "naturalsql";

// 1) Create an instance
const nsql = new NaturalSQL({
	dbUrl: "postgresql://user:password@localhost:5432/mydb",
	dbType: "postgresql"
});

// 2) Build vector DB from schema
const result = await nsql.buildVectorDb("./metadata_vdb");
console.log(`Indexed tables: ${result.indexedTables}`);
console.log(`From cache: ${result.fromCache}`);

// 3) Retrieve relevant tables for a question
const tables = await nsql.search("Show me sales from last month", {
	storagePath: "./metadata_vdb",
	limit: 3
});

// 4) Use returned tables as LLM context
for (const table of tables) {
	console.log(table);
}

Automatic cache

buildVectorDb() reuses existing vector storage when possible (same storage path + schema cache key), unless you pass forceReset: true.

Also, search() reuses the in-memory VectorManager instance for the same storagePath, reducing repeated initialization cost.

E2E examples

import { NaturalSQL } from "naturalsql";

// A) Chroma + local
const nsql = new NaturalSQL({
	dbUrl: "postgresql://user:pass@localhost:5432/mydb",
	dbType: "postgresql",
	vectorBackend: "chroma",
	embeddingProvider: "local",
	vectorDistanceThreshold: 0.35
});

await nsql.buildVectorDb("./metadata_vdb", { forceReset: false });
const tables = await nsql.search("sales for the last month", {
	storagePath: "./metadata_vdb",
	limit: 3
});
console.log(tables);

import { NaturalSQL } from "naturalsql";

// B) SQLite + Gemini
const nsql = new NaturalSQL({
	dbUrl: "sqlite:///./app.db",
	dbType: "sqlite",
	vectorBackend: "sqlite",
	embeddingProvider: "gemini",
	geminiApiKey: process.env.GEMINI_API_KEY,
	geminiEmbeddingModel: "text-embedding-004"
});

await nsql.buildVectorDb("./metadata_vdb_sqlite", { forceReset: false });
const tables = await nsql.search("users with recent purchases", {
	storagePath: "./metadata_vdb_sqlite",
	limit: 3
});
console.log(tables);

API

new NaturalSQL(options?)

Creates an instance with DB and embedding configuration.

| Parameter | Type | Default | Description | |---|---|---|---| | dbUrl | string \| null | null | Database connection URL | | dbType | string | "sqlite" | Engine: postgresql, mysql, sqlite, sqlserver | | normalizeEmbeddings | boolean | true | Normalize embedding vectors | | device | string | "cpu" | Embedding device: cpu or cuda | | vectorBackend | "chroma" \| "sqlite" | "sqlite" | Vector backend | | embeddingProvider | "local" \| "gemini" | "local" | Embedding provider | | geminiApiKey | string \| null | null | Required when embeddingProvider="gemini" | | geminiEmbeddingModel | string | "text-embedding-004" | Gemini embedding model | | vectorDistanceThreshold | number | 0.35 | Max distance threshold used by search() filtering |

Supported backend/provider combinations:

• chroma + local
• sqlite + local
• sqlite + gemini
• chroma + gemini

await nsql.buildVectorDb(storagePath, options?) -> BuildVectorDbResult

Connects to the DB, extracts schema, and indexes it in the configured vector backend.

storagePath is required.

| Options | Type | Default | Description | |---|---|---|---| | forceReset | boolean | false | Rebuild vector collection from scratch | | cacheKey | string | schema hash | Optional custom cache key |

Returns:

| Key | Type | Description | |---|---|---| | storagePath | string | Storage path used | | indexedTables | number | Number of indexed tables | | fromCache | boolean | true if existing vector store was reused |

await nsql.search(request, options?) -> string[]

Retrieves semantically relevant tables for a natural-language question.

| Parameter | Type | Default | Description | |---|---|---|---| | request | string | required | Natural-language question | | options.storagePath | string | "./metadata_vdb" | Vector storage path | | options.limit | number | 3 | Maximum number of tables to return |

buildPrompt(relevantTables, userQuestion) -> string

Helper function in naturalsql to create an LLM prompt from relevant schema tables and a user question.

import { buildPrompt } from "naturalsql";

const prompt = buildPrompt(tables, "Show me sales from last month");

Technical strategy

1. Connection: connects using native drivers (pg, mysql2, mssql) or SQLite support.
2. Schema extraction: uses metadata queries for PostgreSQL/MySQL/SQL Server or PRAGMA table_info for SQLite.
3. Vectorization: each table schema is transformed into a semantic document and indexed in configured backend (chroma or sqlite) with local or Gemini embeddings.
4. Retrieval: semantic nearest-neighbor search + vectorDistanceThreshold filtering.
5. Caching: vector index metadata cache + in-memory manager reuse to reduce repeated latency.

Development

npm run test
npm run typecheck
npm run build

License

Apache-2.0