[Bug]: Unable to Close Persistent Client

[tnorlund]

What happened?

What happened: SQLite file locking issues causing corruption
What you expected: A close() method or context manager support
Current workaround: The fragile GC-based approach you're using
Proposed solution: Adding proper resource management

I'm using AWS's S3 to quickly move chroma DBs around. I'm corrupting the SQLite db while attempting to upload to S3. Here's my workaround thus far.

import os
import tempfile
import shutil
import boto3
import chromadb
from pathlib import Path

def lambda_handler(event, context):
    """AWS Lambda handler that creates ChromaDB delta and uploads to S3."""
    temp_dir = tempfile.mkdtemp()
    bucket = "my-chromadb-bucket"

    try:
        # Create ChromaDB client and collection
        chroma_client = chromadb.PersistentClient(path=temp_dir)
        collection = chroma_client.get_or_create_collection("words")

        # Add some embeddings
        collection.upsert(
            ids=["word_1", "word_2"],
            embeddings=[[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]],
            documents=["hello", "world"],
            metadatas=[{"pos": 1}, {"pos": 2}]
        )

        # PROBLEM: ChromaDB client is still open, SQLite files are locked
        # No close() method available: chroma_client.close()  # ❌ AttributeError

        # Try to upload SQLite files to S3
        s3_client = boto3.client("s3")
        persist_path = Path(temp_dir)

        for file_path in persist_path.rglob("*"):
            if file_path.is_file():
                s3_key = f"snapshots/{file_path.name}"
                # ❌ This fails or uploads corrupted files because SQLite is locked
                s3_client.upload_file(str(file_path), bucket, s3_key)
                # Error: "unable to open database file" or corrupted database

        # Even setting client to None doesn't help immediately
        chroma_client = None  # SQLite connections still open!

        # Files may still be locked here, causing corruption when uploaded

    finally:
        # Cleanup
        shutil.rmtree(temp_dir, ignore_errors=True)

Versions

Versions: ChromaDB >=1.3.3, Python 3.12.0, macOS/Linux

Relevant log output

[tnorlund]

I've implemented a workaround that solves the SQLite file locking issue. Here's what I did:

1. File Polling Instead of Fixed Delays: Instead of using time.sleep() with a fixed delay, I implemented file polling that waits only as long as necessary (up to a max timeout). Files typically unlock immediately (< 50ms), so this is much more efficient.

2. Proper Resource Cleanup: The solution clears collection caches, clears client references, forces garbage collection, and then polls for file unlock status.

Here's the core function:

def close_chromadb_client(
    client: Any,
    collection_name: Optional[str] = None,
    persist_directory: Optional[str] = None,
    max_wait: float = 0.5,
    operation: Optional[str] = None,
) -> None:
    """
    Properly close ChromaDB client using file polling instead of fixed delays.

    NOTE: ChromaDB's PersistentClient doesn't expose a close() method, so we use
    a workaround: clear references, force garbage collection, and poll for file
    unlock status.
    """
    if client is None:
        return

    try:
        # Clear collections cache (for wrapper classes)
        if hasattr(client, '_collections'):
            client._collections.clear()

        # Clear the underlying client reference
        if hasattr(client, '_client') and client._client is not None:
            client._client = None

        # Force garbage collection to ensure SQLite connections are closed
        import gc
        gc.collect()
        gc.collect()  # Second pass for circular references

        # Use file polling instead of fixed delay
        if persist_directory:
            wait_for_chromadb_files_unlocked(
                persist_directory,
                max_wait=max_wait,  # Default 0.5s (optimized from 2.0s)
                collection_name=collection_name,
                operation=operation,
            )
        else:
            time.sleep(0.05)  # Minimal fallback delay

    except Exception as e:
        logger.warning("Error closing ChromaDB client (non-critical)", error=str(e))

The file polling function:

def wait_for_file_unlock(
    file_path: str,
    max_wait: float = 0.5,
    check_interval: float = 0.01,  # 10ms polling interval
) -> bool:
    """Wait for a file to be unlocked by polling, with timeout."""
    start_time = time.time()

    while time.time() - start_time < max_wait:
        try:
            # Try to open file exclusively to check if it's unlocked
            with open(file_path, 'r+b') as f:
                f.flush()
            return True  # File is unlocked!
        except (IOError, PermissionError, OSError):
            # File still locked, wait and retry
            time.sleep(check_interval)

    return False  # Timeout

Usage Pattern

# Process ChromaDB operations
chroma_client = chromadb.PersistentClient(path=temp_dir)
collection = chroma_client.get_collection("words")
# ... do work ...

# CRITICAL: Close client BEFORE uploading/copying
close_chromadb_client(chroma_client, collection_name="words", persist_directory=temp_dir)
chroma_client = None

# Now safe to upload/copy SQLite files
s3_client.upload_file(str(file_path), bucket, s3_key)

Results

Fixed: SQLite file corruption when uploading to S3
Fixed: "unable to open database file" errors
Fixed: "Too many open files" errors

What ChromaDB Should Do

Ideal solution (requires ChromaDB changes):

# Option 1: Context manager support
with chromadb.PersistentClient(path=temp_dir) as client:
    collection = client.get_collection("words")
    # ... do work ...
# Client automatically closed here

# Option 2: Explicit close() method
client = chromadb.PersistentClient(path=temp_dir)
# ... do work ...
client.close()  # Properly closes SQLite connections