# LlamaIndex Readers Integration: Database
## Overview
Database Reader is a tool designed to query and load data from databases efficiently.
### Key features
- Accepts connection via `SQLDatabase`, SQLAlchemy `Engine`, full URI, or discrete credentials
- Optional `schema` selection (namespace)
- Column-level metadata mapping (`metadata_cols`) and text exclusion (`excluded_text_cols`)
- Custom `id_` generation function (`document_id`)
- Supports streaming (`lazy_load_data`) and async (`aload_data`)
### Installation
You can install Database Reader via pip:
```bash
pip install llama-index-readers-database
```
## Usage
```python
from llama_index.readers.database import DatabaseReader
# Initialize DatabaseReader with the SQL database connection details
reader = DatabaseReader(
sql_database="<SQLDatabase Object>", # Optional: SQLDatabase object
engine="<SQLAlchemy Engine Object>", # Optional: SQLAlchemy Engine object
uri="<Connection URI>", # Optional: Connection URI
scheme="<Scheme>", # Optional: Scheme
host="<Host>", # Optional: Host
port="<Port>", # Optional: Port
user="<Username>", # Optional: Username
password="<Password>", # Optional: Password
dbname="<Database Name>", # Optional: Database Name
)
# Load data from the database using a query
documents = reader.load_data(
query="<SQL Query>" # SQL query parameter to filter tables and rows
)
```
```python
# Initialize DatabaseReader with the SQL connection string and custom database schema
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)
# Async variant, added region to metadata
docs_async = await reader.aload_data(
query="SELECT * FROM warehouse.big_table", metadata_cols=["region"]
)
```
```python
# Advanced usage with custom named metadata columns, columns excluded from the `Document.text_resource`, and a dynamic `Document.id_` generated from row data and a fstring template
from llama_index.readers.database import DatabaseReader
reader_media = DatabaseReader(
uri="postgresql+psycopg2://user:pass@localhost:5432/mydb",
schema="media", # optional namespace
)
docs = reader_media.load_data(
query="SELECT id, title, body, updated_at FROM media.articles",
metadata_cols=[
("id", "article_id"),
"updated_at",
], # map / include in metadata
excluded_text_cols=["updated_at"], # omit from text
document_id=lambda row: f"media-articles-{row['id']}", # custom document id
)
```
This loader is designed to be used as a way to load data into
[LlamaIndex](https://github.com/run-llama/llama_index/tree/main/llama_index).
Raw data
{
"_id": null,
"home_page": null,
"name": "llama-index-readers-database",
"maintainer": "kevinqz",
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "aws rds, postgres, snowflake, sql",
"author": null,
"author_email": "Your Name <you@example.com>",
"download_url": "https://files.pythonhosted.org/packages/85/ac/e50316d32b0687806cb26a828a5feb27efaf8f121d3f248991cc4a7702aa/llama_index_readers_database-0.5.1.tar.gz",
"platform": null,
"description": "# LlamaIndex Readers Integration: Database\n\n## Overview\n\nDatabase Reader is a tool designed to query and load data from databases efficiently.\n\n### Key features\n\n- Accepts connection via `SQLDatabase`, SQLAlchemy `Engine`, full URI, or discrete credentials\n- Optional `schema` selection (namespace)\n- Column-level metadata mapping (`metadata_cols`) and text exclusion (`excluded_text_cols`)\n- Custom `id_` generation function (`document_id`)\n- Supports streaming (`lazy_load_data`) and async (`aload_data`)\n\n### Installation\n\nYou can install Database Reader via pip:\n\n```bash\npip install llama-index-readers-database\n```\n\n## Usage\n\n```python\nfrom llama_index.readers.database import DatabaseReader\n\n# Initialize DatabaseReader with the SQL database connection details\nreader = DatabaseReader(\n sql_database=\"<SQLDatabase Object>\", # Optional: SQLDatabase object\n engine=\"<SQLAlchemy Engine Object>\", # Optional: SQLAlchemy Engine object\n uri=\"<Connection URI>\", # Optional: Connection URI\n scheme=\"<Scheme>\", # Optional: Scheme\n host=\"<Host>\", # Optional: Host\n port=\"<Port>\", # Optional: Port\n user=\"<Username>\", # Optional: Username\n password=\"<Password>\", # Optional: Password\n dbname=\"<Database Name>\", # Optional: Database Name\n)\n\n# Load data from the database using a query\ndocuments = reader.load_data(\n query=\"<SQL Query>\" # SQL query parameter to filter tables and rows\n)\n```\n\n```python\n# Initialize DatabaseReader with the SQL connection string and custom database schema\nfrom llama_index.readers.database import DatabaseReader\n\nreader = DatabaseReader(\n uri=\"postgresql+psycopg2://user:pass@localhost:5432/mydb\",\n schema=\"warehouse\", # optional namespace\n)\n# Streaming variant, excluded id from text_resource\nfor doc in reader.lazy_load_data(\n query=\"SELECT * FROM warehouse.big_table\", excluded_text_cols={\"id\"}\n):\n process(doc)\n\n# Async variant, added region to metadata\ndocs_async = await reader.aload_data(\n query=\"SELECT * FROM warehouse.big_table\", metadata_cols=[\"region\"]\n)\n```\n\n```python\n# Advanced usage with custom named metadata columns, columns excluded from the `Document.text_resource`, and a dynamic `Document.id_` generated from row data and a fstring template\nfrom llama_index.readers.database import DatabaseReader\n\nreader_media = DatabaseReader(\n uri=\"postgresql+psycopg2://user:pass@localhost:5432/mydb\",\n schema=\"media\", # optional namespace\n)\n\ndocs = reader_media.load_data(\n query=\"SELECT id, title, body, updated_at FROM media.articles\",\n metadata_cols=[\n (\"id\", \"article_id\"),\n \"updated_at\",\n ], # map / include in metadata\n excluded_text_cols=[\"updated_at\"], # omit from text\n document_id=lambda row: f\"media-articles-{row['id']}\", # custom document id\n)\n```\n\nThis loader is designed to be used as a way to load data into\n[LlamaIndex](https://github.com/run-llama/llama_index/tree/main/llama_index).\n",
"bugtrack_url": null,
"license": null,
"summary": "llama-index readers database integration",
"version": "0.5.1",
"project_urls": null,
"split_keywords": [
"aws rds",
" postgres",
" snowflake",
" sql"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9c70318d7bf3f3897a3b88b6474377fed09a61e9a5352c02feb74834fcb56787",
"md5": "b4ccc12d679d88d004c286323ad9bba2",
"sha256": "fb96894a4894752a9fbfe62f2220e0e79912ccd8d05b447ea1079d22fda67955"
},
"downloads": -1,
"filename": "llama_index_readers_database-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b4ccc12d679d88d004c286323ad9bba2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 6422,
"upload_time": "2025-09-08T20:48:24",
"upload_time_iso_8601": "2025-09-08T20:48:24.601822Z",
"url": "https://files.pythonhosted.org/packages/9c/70/318d7bf3f3897a3b88b6474377fed09a61e9a5352c02feb74834fcb56787/llama_index_readers_database-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "85ace50316d32b0687806cb26a828a5feb27efaf8f121d3f248991cc4a7702aa",
"md5": "573f3a1963378b59823d78953c65792f",
"sha256": "f613102740dd30800327932d8f1ecf22aea93878d498271e79cb8f7afd7477ff"
},
"downloads": -1,
"filename": "llama_index_readers_database-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "573f3a1963378b59823d78953c65792f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 6728,
"upload_time": "2025-09-08T20:48:25",
"upload_time_iso_8601": "2025-09-08T20:48:25.322214Z",
"url": "https://files.pythonhosted.org/packages/85/ac/e50316d32b0687806cb26a828a5feb27efaf8f121d3f248991cc4a7702aa/llama_index_readers_database-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-08 20:48:25",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "llama-index-readers-database"
}
JSON