Implementation:Vibrantlabsai Ragas Text2SQL DB Utils

Knowledge Sources	Vibrantlabsai_Ragas
Domains	Text-to-SQL, Database Utilities, SQLite
Last Updated	2026-02-12 00:00 GMT

Overview

This module provides a simple SQLite database interface and convenience functions for executing SQL queries and retrieving schema information during text-to-SQL evaluations.

Description

The db_utils.py module implements the SQLiteDB class, which wraps Python's sqlite3 library to provide a safe, evaluation-friendly database interface. Key design decisions include:

Security -- Only SELECT queries are permitted. Any non-SELECT query is rejected before execution, preventing accidental data modification during evaluation runs.

SQL Normalization -- The _normalize_sql method applies several transformations to improve query compatibility with the BookSQL dataset:

• Replaces double quotes with single quotes for consistent string delimiters.
• Collapses whitespace for cleaner query formatting.
• Replaces date functions (current_date, now) with a fixed date (2022-06-01) since the BookSQL dataset contains historical financial data.
• Optionally converts the entire query to lowercase for case-insensitive string comparisons.

Connection Management -- The class supports both manual connection lifecycle (connect/disconnect) and lazy connection via execute_query (which auto-connects if needed). The default database path points to the BookSQL accounting SQLite database at BookSQL-files/BookSQL/accounting.sqlite.

Result Format -- All query results are returned as (bool, Union[pd.DataFrame, str]) tuples, where the boolean indicates success and the second element is either a pandas DataFrame of results or an error message string.

Two convenience functions provide automatic connection management:

• execute_sql -- Executes a single SQL query with auto-connect/disconnect.
• get_database_schema -- Retrieves the database schema (tables and views with their CREATE statements).

The module also includes a CLI interface supporting --query, --schema, and --tables commands for interactive database exploration.

Usage

Import this module when you need to execute SQL queries against a SQLite database during text-to-SQL evaluation workflows. Use the SQLiteDB class for persistent connections across multiple queries, or the execute_sql convenience function for one-off query execution.

Code Reference

Source Location

• Repository: Vibrantlabsai_Ragas
• File: examples/ragas_examples/text2sql/db_utils.py

Signature

class SQLiteDB:
    def __init__(self, db_path: Optional[str] = None) -> None
    def connect(self) -> Tuple[bool, str]
    def disconnect(self) -> None
    def execute_query(self, sql: str, replace_current_date: bool = True,
                      case_insensitive: bool = True) -> Tuple[bool, Union[pd.DataFrame, str]]
    def _normalize_sql(self, sql: str, replace_current_date: bool,
                       case_insensitive: bool) -> str
    def get_schema_info(self) -> Tuple[bool, Union[pd.DataFrame, str]]
    def get_table_names(self) -> Tuple[bool, Union[list, str]]

def execute_sql(sql: str, db_path: Optional[str] = None,
                replace_current_date: bool = True,
                case_insensitive: bool = True) -> Tuple[bool, Union[pd.DataFrame, str]]

def get_database_schema(db_path: Optional[str] = None) -> Tuple[bool, Union[pd.DataFrame, str]]

def main() -> None

Import

from ragas_examples.text2sql.db_utils import SQLiteDB, execute_sql, get_database_schema

I/O Contract

Inputs

SQLiteDB.__init__

Name	Type	Required	Description
db_path	Optional[str]	No	Path to SQLite database file; defaults to "BookSQL-files/BookSQL/accounting.sqlite"

SQLiteDB.execute_query

Name	Type	Required	Description
sql	str	Yes	SQL SELECT query to execute
replace_current_date	bool	No	Replace date functions with fixed date "2022-06-01" (default: True)
case_insensitive	bool	No	Convert query to lowercase for case-insensitive comparison (default: True)

execute_sql

Name	Type	Required	Description
sql	str	Yes	SQL SELECT query to execute
db_path	Optional[str]	No	Path to database file; uses BookSQL default if None
replace_current_date	bool	No	Replace date functions with fixed date (default: True)
case_insensitive	bool	No	Make string comparisons case-insensitive (default: True)

get_database_schema

Name	Type	Required	Description
db_path	Optional[str]	No	Path to database file; uses BookSQL default if None

Outputs

SQLiteDB.connect

Name	Type	Description
return	Tuple[bool, str]	(success flag, message string describing the connection result)

SQLiteDB.execute_query / execute_sql

Name	Type	Description
return	Tuple[bool, Union[DataFrame, str]]	(success flag, DataFrame of results on success or error message string on failure)

SQLiteDB.get_schema_info / get_database_schema

Name	Type	Description
return	Tuple[bool, Union[DataFrame, str]]	(success flag, DataFrame with name/type/sql columns on success or error message on failure)

SQLiteDB.get_table_names

Name	Type	Description
return	Tuple[bool, Union[list, str]]	(success flag, list of table name strings on success or error message on failure)

Usage Examples

Basic Query Execution

from db_utils import execute_sql

# Execute a query with automatic connection management
success, result = execute_sql("SELECT COUNT(*) FROM master_txn_table")
if success:
    print(f"Row count: {result.iloc[0, 0]}")
else:
    print(f"Error: {result}")

Using the SQLiteDB Class

from db_utils import SQLiteDB

db = SQLiteDB("BookSQL-files/BookSQL/accounting.sqlite")
success, msg = db.connect()

if success:
    # Get table names
    ok, tables = db.get_table_names()
    if ok:
        print(f"Tables: {tables}")

    # Execute a query
    ok, df = db.execute_query("SELECT * FROM master_txn_table LIMIT 5")
    if ok:
        print(df)

db.disconnect()

CLI Usage

# Execute a query
python db_utils.py --query "SELECT COUNT(*) FROM master_txn_table"

# Show database schema
python db_utils.py --schema

# List all tables
python db_utils.py --tables

# Use a custom database path
python db_utils.py --db /path/to/database.sqlite --tables

Related Pages

• Environment:Vibrantlabsai_Ragas_Python_3_9_Core_Environment