Replace py-pglite with testcontainers for Postgres testing

[phernandez]

Summary

• Switch from py-pglite to testcontainers-postgres for more reliable Postgres testing
• Use environment variable approach (BASIC_MEMORY_TEST_POSTGRES=1) instead of parameterized fixtures
• Add explicit justfile recipes: test-sqlite, test-postgres, test-unit-sqlite, test-unit-postgres, etc.
• Update CI to run SQLite and Postgres tests in parallel jobs
• Add isolated_home fixture for CLI tests to prevent reading user config
• Split Postgres DDL statements for asyncpg compatibility (requires separate execute calls)
• Add timeout workaround for FastMCP Client + asyncpg cleanup hang
• Update README.md and CLAUDE.md with current testing documentation

Test plan

• just test-sqlite passes locally
• just test-postgres passes locally (with timeout workaround for cleanup hang)
• CI runs SQLite tests on Ubuntu and Windows
• CI runs Postgres tests on Ubuntu (via testcontainers)

🤖 Generated with Claude Code

[github-actions]

Claude finished @phernandez's task in 1m 55s —— View job

---

PR Review: Replace py-pglite with testcontainers

I've completed a comprehensive review of this PR against the Basic Memory team checklist. Overall, this is a well-executed refactoring that addresses the problematic py-pglite dependency and improves the testing infrastructure. The changes are thoughtful and align with the project's architecture principles.

---

✅ Code Quality & Standards

Strengths:

• ✅ Follows Basic Memory's coding conventions in CLAUDE.md
• ✅ Python 3.12+ type annotations maintained throughout
• ✅ SQLAlchemy 2.0 best practices followed
• ✅ FastAPI and Typer conventions preserved
• ✅ 100-character line length limit maintained
• ✅ Clean removal of commented-out code

Observations:

• Good architectural decision: The environment variable approach (BASIC_MEMORY_TEST_POSTGRES=1) is cleaner than pytest parameterization and enables parallel CI execution
• Proper DDL handling: Splitting Postgres DDL statements for asyncpg compatibility shows attention to driver requirements (src/basic_memory/models/search.py:16-49)
• Type safety: Added Literal["sqlite", "postgres"] type hints for better type checking (test-int/conftest.py:88)

---

✅ Testing & Documentation

Strengths:

• ✅ Test structure preserved - unit tests remain fast with SQLite
• ✅ Comprehensive documentation updates in both README.md and CLAUDE.md
• ✅ Clear justfile recipes for different test combinations
• ✅ Session-scoped Postgres container for efficient resource usage

Observations:

• Isolated test environments: The isolated_home fixture (tests/cli/conftest.py:15-35) properly prevents tests from reading user config - excellent addition
• Test coverage maintained: Both unit and integration tests work with both backends
• Good documentation: CLAUDE.md explicitly mentions testcontainers and Docker requirement (line 37)

Minor Issue - Benchmark tests removed:

• ❌ test-int/test_sync_performance_benchmark.py was deleted (372 lines)
• The justfile still references this file at line 27: pytest test-int/test_sync_performance_benchmark.py
• Recommendation: Either restore the benchmark tests or remove the stale justfile reference

---

✅ Basic Memory Architecture

Strengths:

• ✅ Preserves local-first architecture principles
• ✅ Database abstraction maintained through repository pattern
• ✅ Proper use of factory pattern for backend selection (tests/conftest.py:388-396)
• ✅ No changes to MCP tool interface or behavior

Observations:

• Backend-aware repository creation: Good use of create_search_repository() factory function
• Consistent schema creation: Both SQLite and Postgres use the same DDL approach in tests
• Proper cleanup: NullPool for Postgres tests ensures proper isolation (tests/conftest.py:199)

---

✅ Security & Performance

Strengths:

• ✅ No hardcoded credentials
• ✅ Testcontainers handles Postgres lifecycle securely
• ✅ Proper async patterns maintained
• ✅ Good error handling throughout

Observations:

• Timeout workaround documented: The FastMCP Client + asyncpg cleanup hang is documented and handled (justfile:51-54)
• Resource cleanup: Proper engine disposal in both SQLite and Postgres paths

---

⚠️ Compatibility

Observations:

• ✅ Path handling uses proper Path comparisons
• ⚠️ Minor concern: The timeout command in justfile (line 54) uses Linux/Unix syntax - won't work on Windows
  • However, Postgres tests only run on Ubuntu in CI (test.yml:79), so this is acceptable
  • Windows developers can still run SQLite tests without issues

Dependency changes (pyproject.toml):

• ✅ Added testcontainers[postgres]>=4.0.0 to dev dependencies
• ✅ Added psycopg>=3.2.0 for testcontainers
• ⚠️ Concern: Added pytest-asyncio>=1.2.0 and psycopg==3.3.1 to production dependencies (lines 40-41)
  • These should likely be in [dependency-groups.dev] instead of [project.dependencies]
  • Production users don't need test dependencies

---

📋 Summary of Issues

Critical Issues

None

Medium Priority

1. Stale justfile reference: Remove or update benchmark test reference at line 27
2. Dependency placement: Move pytest-asyncio and psycopg from production to dev dependencies

Low Priority

1. CI tests still pending: Waiting for CI results to confirm both SQLite and Postgres test suites pass

---

🎯 Verdict

This PR represents a significant improvement over py-pglite and aligns well with the project's "Problem-Solving Guidance" in CLAUDE.md:

"When py-pglite caused cascading test failures, switching to testcontainers-postgres was the right call"

The refactoring is thorough, well-documented, and maintains architectural consistency. The few issues identified are minor and easily addressed.

Recommendation: ✅ Approve with minor changes

• Fix the dependency placement in pyproject.toml
• Remove stale benchmark reference in justfile
• Wait for CI to confirm all tests pass

---

What I Reviewed

• ✅ Test infrastructure (conftest.py files)
• ✅ CI/CD configuration (.github/workflows/test.yml)
• ✅ Core code changes (search.py, watch_service.py, relation_repository.py)
• ✅ Documentation (CLAUDE.md, README.md)
• ✅ Build configuration (justfile, pyproject.toml)
• ✅ Sample test files to verify patterns