text2sql-lite 0.4.0

Convert natural English to SQL (SQLite, Postgres, MySQL) with offline heuristics or optional LLM backends.

text2sql-lite

Source: github.com/sriramsreedhar/text2sql-lite

Turn short English requests into SQLite, PostgreSQL, or MySQL SQL using offline heuristics by default. You can optionally add OpenAI, Google Gemini, or Mistral via small install extras so translate() can call a model when you want broader coverage or when heuristics fail.

---

LLM (optional)

Install one provider you use, or all of them:

pip install "text2sql-lite[llm]"              # OpenAI + Gemini + Mistral (all SDKs)
pip install "text2sql-lite[llm_openai]"       # OpenAI only
pip install "text2sql-lite[llm_gemini]"      # Google Gemini only
pip install "text2sql-lite[llm_mistral]"     # Mistral only

How translate() uses an LLM

• Pass llm_client=<wrapper> (see below). If the heuristic parser cannot handle the phrase, the model is used instead of raising ValueError.
• Pass prefer_llm=True to call the model first; if the model fails (network error, etc.), the library falls back to heuristics when possible.

Set API keys the usual way (environment variables or your provider’s docs). Always review model-generated SQL before running it.

OpenAI

import os
from text2sql_lite import translate, Dialect, OpenAIChatClient
from text2sql_lite.schema import Table, Column, TableSchema

schema = TableSchema((Table("users", (Column("email"), Column("state"))),))
client = OpenAIChatClient(api_key=os.environ.get("OPENAI_API_KEY"), model="gpt-4o-mini")

result = translate(
    "emails of users in TX ordered by signup",
    dialect=Dialect.POSTGRES,
    schema=schema,
    llm_client=client,
)
print(result.sql)

Google Gemini

Uses the google-generativeai SDK (llm_gemini extra). Set GOOGLE_API_KEY or pass api_key= into the client.

import os
from text2sql_lite import translate, Dialect, GeminiChatClient
from text2sql_lite.schema import Table, Column, TableSchema

schema = TableSchema((Table("users", (Column("email"), Column("state"))),))
client = GeminiChatClient(api_key=os.environ.get("GOOGLE_API_KEY"), model="gemini-1.5-flash")

result = translate(
    "emails of users in TX ordered by signup",
    dialect=Dialect.POSTGRES,
    schema=schema,
    llm_client=client,
)
print(result.sql)

Mistral

import os
from text2sql_lite import translate, Dialect, MistralChatClient
from text2sql_lite.schema import Table, Column, TableSchema

schema = TableSchema((Table("users", (Column("email"), Column("state"))),))
client = MistralChatClient(api_key=os.environ.get("MISTRAL_API_KEY"), model="mistral-small-latest")

result = translate(
    "emails of users in TX ordered by signup",
    dialect=Dialect.POSTGRES,
    schema=schema,
    llm_client=client,
)
print(result.sql)

---

SQLite

Install — base package only (no extra dependencies):

pip install text2sql-lite

Generate SQL — use Dialect.SQLITE (backtick identifiers; LIKE for place-style filters):

from text2sql_lite import translate, Dialect
from text2sql_lite.schema import Table, Column, TableSchema

schema = TableSchema(
    (Table("users", (Column("id"), Column("email"), Column("state"))),),
)

result = translate(
    "show users from texas",
    dialect=Dialect.SQLITE,
    schema=schema,
)
print(result.sql)

Optional: load schema from a .db file — uses the standard library (sqlite3); no extra install:

from text2sql_lite.introspect import introspect_sqlite

schema = introspect_sqlite("/path/to/app.db")

---

PostgreSQL

Install — include the Postgres extra so schema introspection can use psycopg:

pip install "text2sql-lite[postgres]"

Generate SQL — use Dialect.POSTGRES (double-quoted identifiers when needed; ILIKE for place-style filters):

from text2sql_lite import translate, Dialect
from text2sql_lite.schema import Table, Column, TableSchema

schema = TableSchema(
    (Table("users", (Column("id"), Column("email"), Column("state"))),),
)

result = translate(
    "show users from texas",
    dialect=Dialect.POSTGRES,
    schema=schema,
)
print(result.sql)

Optional: load schema from a live database — pass a psycopg connection (v3):

import psycopg
from text2sql_lite.introspect import introspect_postgres

conn = psycopg.connect("postgresql://user:pass@localhost:5432/dbname")
schema = introspect_postgres(conn)
conn.close()

---

MySQL

Install — include the MySQL extra for PyMySQL (used by introspect_mysql):

pip install "text2sql-lite[mysql]"

Generate SQL — use Dialect.MYSQL (backtick identifiers; place-style filters use LOWER / LIKE / CONCAT):

from text2sql_lite import translate, Dialect
from text2sql_lite.schema import Table, Column, TableSchema

schema = TableSchema(
    (Table("users", (Column("id"), Column("email"), Column("state"))),),
)

result = translate(
    "show users from texas",
    dialect=Dialect.MYSQL,
    schema=schema,
)
print(result.sql)

Optional: load schema from a live database — pass a PyMySQL connection to the current database:

import pymysql
from text2sql_lite.introspect import introspect_mysql

conn = pymysql.connect(host="localhost", user="u", password="p", database="mydb")
schema = introspect_mysql(conn)
conn.close()

---

API highlights

• translate(...) — pattern-based English → SQL; raises ValueError if neither heuristics nor an LLM can handle the request (when no llm_client is passed). Use llm_client= and optionally prefer_llm=True.
• Dialect.SQLITE / Dialect.POSTGRES / Dialect.MYSQL — quoting and string matching tuned per engine.
• introspect_sqlite(path) — stdlib only; introspect_postgres(conn) — needs [postgres]; introspect_mysql(conn) — needs [mysql].

Limits

Heuristics cover a narrow set of shapes (list rows, optional “from <place>” filters, simple WHERE col op value, LIMIT). LLMs can handle richer language but may still hallucinate—always review generated SQL before execution.

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

License

text2sql-lite is licensed under the Apache License, Version 2.0 (SPDX: Apache-2.0). See the LICENSE file for the full text.

In short: you may use, modify, and distribute this software under the terms of the license, which includes an express patent grant from contributors and requires preserving notices and, when you distribute modified files, stating that you changed them. The software is provided “as is” without warranties.

Optional dependencies (LLM providers, database drivers) are separate packages under their own licenses; see each project’s documentation.