Query Databases for LlamaIndex

The Database Reader queries and loads data from databases efficiently into LlamaIndex documents. It accepts a connection in several forms - an existing SQLDatabase object, a SQLAlchemy Engine, a full connection URI, or discrete credentials (host, port, user, password, database name) - so it fits into a project regardless of how the database connection is already managed. An optional schema parameter scopes queries to a specific namespace, such as targeting a warehouse or media schema within the same database.

Column handling is configurable: metadata_cols maps specific columns into document metadata (optionally renaming a column via a tuple like mapping id to article_id), while excluded_text_cols removes named columns from the document's text body even if they were selected by the query - useful for a column like updated_at that should be tracked as metadata but not embedded in the searchable text. A custom document_id function can generate each document's ID dynamically from its row data, for example an f-string template combining a table name and row ID.

Beyond the standard load_data, the reader supports lazy_load_data for streaming results one document at a time rather than loading everything into memory, and an async aload_data for non-blocking use in async code.

Use it when you need to turn the results of a SQL query into LlamaIndex documents - filtering with an arbitrary SELECT query, controlling which columns become metadata versus searchable text, and generating stable custom document IDs. Use lazy_load_data for large result sets where loading everything into memory at once would be wasteful, and aload_data when working inside an async application. Do not use it as a way to modify the database; it is a read-only loader built around SQL queries you supply.

load_data/lazy_load_data/aload_data run a SQL query and return matching rows as documents, with configurable connection method (SQLDatabase, Engine, URI, or discrete credentials), schema scoping, metadata column mapping, text-column exclusion, and custom document ID generation.

pip install llama-index-readers-database

from llama_index.readers.database import DatabaseReader

reader = DatabaseReader(
    uri="postgresql+psycopg2://user:pass@localhost:5432/mydb",
    schema="warehouse",  # optional namespace
)
### Streaming variant, excluded id from text_resource
for doc in reader.lazy_load_data(
    query="SELECT * FROM warehouse.big_table", excluded_text_cols={"id"}
):
    process(doc)

Requires database connection details in one of the supported forms (SQLDatabase object, SQLAlchemy Engine, connection URI, or discrete host/port/user/password/dbname).

Developers who need SQL query results loaded into LlamaIndex with fine control over which columns become metadata, which are excluded from text, and how document IDs are generated - including at scale via streaming or async loading.