llama-index-storage-docstore-postgres

0.5.0 verified Fri May 01 auth: no python

A LlamaIndex integration for storing document metadata (docstore) in PostgreSQL. Current version 0.5.0 requires Python >=3.10 and <4.0. Release cadence follows LlamaIndex's package updates.

pip install llama-index-storage-docstore-postgres

Common errors

error ModuleNotFoundError: No module named 'llama_index.storage.docstore.postgres' ↓

cause Wrong import path or missing subpackage installation.

fix

Install the subpackage: pip install llama-index-storage-docstore-postgres

error asyncpg.exceptions.InvalidAuthorizationSpecificationError: authentication method 10 not supported ↓

cause PostgreSQL server requires SCRAM-SHA-256 but asyncpg might not support it in older versions.

fix

Upgrade asyncpg: pip install --upgrade asyncpg. Alternatively, configure PostgreSQL to accept md5 passwords.

error sqlalchemy.exc.ArgumentError: Could not parse rfc1738 URL from string 'postgresql://...' ↓

cause Connection string missing driver prefix.

fix

Use postgresql+asyncpg://user:pass@host/db or postgresql+psycopg2://... depending on driver.

Warnings

deprecated The class `PostgresDocStore` is deprecated in favor of unified storage backends. Expect removal in future LlamaIndex versions. ↓

fix Migrate to `llama-index-storage-docstore-postgres` with new API or use `VectorStoreIndex` with PostgreSQL.

gotcha PostgresDocStore uses asyncpg by default, so you must use an async-compatible connection string (e.g., `postgresql+asyncpg://`). Sync drivers like `psycopg2` will fail. ↓

fix Use async driver prefix: `postgresql+asyncpg://...` or `postgresql+psycopg://...` if using psycopg3 async.

gotcha Table and schema names must exist or be auto-created; auto-creation may fail in restricted environments. ↓

fix Ensure the PostgreSQL user has CREATE TABLE privileges on the schema, or manually create the docstore table beforehand.

Imports

PostgresDocStore

wrong

from llama_index.storage.docstore import PostgresDocStore

correct

from llama_index.storage.docstore.postgres import PostgresDocStore

DocStore classes are in submodule, not directly in docstore

Quickstart

Initialize a PostgreSQL-backed document store using a connection URI.

import os
from llama_index.storage.docstore.postgres import PostgresDocStore

# Set up connection (use environment variables for safety)
connection_string = os.environ.get(
    "POSTGRES_CONNECTION_STRING",
    "postgresql+asyncpg://user:pass@localhost:5432/llamaindex"
)

docstore = PostgresDocStore.from_uri(
    connection_string=connection_string,
    table_name="docstore",  # optional
    schema_name="public"     # optional
)
print("PostgresDocStore created successfully")