fix: Replace raw SQL string interpolation with proper SQLAlchemy parameterized APIs in PostgresKVStore

[ColeMurray]

Summary

This PR improves the PostgresKVStore implementation by replacing raw SQL string interpolation with proper SQLAlchemy parameterized APIs. While unlikely to be exploitable in practice (since identifiers are lowercased during initialization), using SQLAlchemy's built-in constructs is better practice and eliminates any theoretical injection vectors.

Changes

1. Schema Creation (_create_schema_if_not_exists)

Before:

check_schema_statement = text(
    f"SELECT schema_name FROM information_schema.schemata WHERE schema_name = '{self.schema_name}'"
)
create_schema_statement = text(f"CREATE SCHEMA IF NOT EXISTS {self.schema_name}")

After:

from sqlalchemy.schema import CreateSchema
session.execute(CreateSchema(self.schema_name, if_not_exists=True))

2. Insert Operations (put_all / aput_all)

Before:

stmt = text(f"""
    INSERT INTO {self.schema_name}.{self._table_class.__tablename__} (key, namespace, value)
    VALUES {values_clause}
    ON CONFLICT (key, namespace)
    DO UPDATE SET value = EXCLUDED.value;
""")

After:

from sqlalchemy.dialects.postgresql import insert

stmt = insert(self._table_class).values(values_to_insert)
stmt = stmt.on_conflict_do_update(
    index_elements=["key", "namespace"],
    set_={"value": stmt.excluded.value},
)

Benefits

• Cleaner code: Uses SQLAlchemy's intended APIs instead of raw SQL text
• More maintainable: Easier to understand and audit
• Better type safety: SQLAlchemy handles identifier quoting automatically
• Fewer lines: Simplified logic in put_all and aput_all

Testing

Added 4 new tests to verify the implementation:

• test_schema_creation_uses_safe_api - Verifies CreateSchema usage
• test_put_all_uses_safe_insert - Verifies parameterized insert API
• test_aput_all_uses_safe_insert - Verifies async parameterized insert
• test_schema_name_with_special_characters - Tests edge cases with special characters

All tests pass (6/6). All pre-commit checks pass (ruff, mypy, codespell, formatting).

Code Changes

• Files changed: 2
• Lines added: +232 (including tests)
• Lines removed: -68

Modified Files

• llama_index/storage/kvstore/postgres/base.py
• tests/test_storage_kvstore_postgres.py

Breaking Changes

None - this is a drop-in replacement with full backward compatibility.