Skip to content
Prev Previous commit
Next Next commit
Update Async explainer after review
  • Loading branch information
dishaprakash authored Apr 17, 2025
commit c0a8ccda923f40749504e3681b26999d9a437e3c
14 changes: 7 additions & 7 deletions Async explainer.md
Original file line number Diff line number Diff line change
@@ -1,26 +1,26 @@
# Design Rationale: Mixed Interface PGVectorStore
# Design Overview for `PGVectorStore`

This document outlines the design choices behind the PGVectorStore integration for LangChain, focusing on its dual interface that supports both synchronous and asynchronous usage patterns.
This document outlines the design choices behind the PGVectorStore integration for LangChain, focusing on how an async PostgreSQL driver can supports both synchronous and asynchronous usage.

## Motivation: Performance through Asynchronicity

Database interactions are often I/O-bound, making asynchronous programming crucial for performance.

- **Non-Blocking Operations:** Asynchronous code prevents the application from stalling while waiting for database responses, improving throughput and responsiveness.
- **Asynchronous Foundation (`asyncio` and Drivers):** Built upon Python's `asyncio`, the integration is designed to work with asynchronous PostgreSQL drivers to handle database operations efficiently. While compatible drivers are supported, the `asyncpg` driver is specifically recommended due to its high performance in concurrent scenarios. You can explore its benefits ([link](https://magic.io/blog/asyncpg-1m-rows-from-postgres-to-python/)) and performance benchmarks ([link](https://fernandoarteaga.dev/blog/psycopg-vs-asyncpg/)) for more details.
- **Non-Blocking Operations:** Asynchronous code prevents the application from stalling while waiting for database responses, improving throughput and responsiveness.
- **Asynchronous Foundation (`asyncio` and Drivers):** Built upon Python's `asyncio` library, the integration is designed to work with asynchronous PostgreSQL drivers to handle database operations efficiently. While compatible drivers are supported, the `asyncpg` driver is specifically recommended due to its high performance in concurrent scenarios. You can explore its benefits ([link](https://magic.io/blog/asyncpg-1m-rows-from-postgres-to-python/)) and performance benchmarks ([link](https://fernandoarteaga.dev/blog/psycopg-vs-asyncpg/)) for more details.

This foundation ensures the core database interactions are fast and scalable.
This native async foundation ensures the core database interactions are fast and scalable.

## The Two-Class Approach: Enabling a Mixed Interface

To cater to different application architectures while maintaining performance, we provide two classes:

1. **`AsyncPGVectorStore` (Core Asynchronous Implementation):**
* This class contains the pure `async/await` logic for all database operations using `asyncpg`.
* This class contains the pure `async/await` logic for all database operations.
* It's designed for **direct use within asynchronous applications**. Users working in an `asyncio` environment can `await` its methods for maximum efficiency and direct control within the event loop.
* It represents the fundamental, non-blocking way of interacting with the database.

2. **`PGVectorStore` (Synchronous Interface / Asynchronous Internals):**
2. **`PGVectorStore` (Mixed Sync/Async API ):**
* This class provides both asynchronous & synchronous APIs.
* When one of its methods is called, it internally invokes the corresponding `async` method from `AsyncPGVectorStore`.
* It **manages the execution of this underlying asynchronous logic**, handling the necessary `asyncio` event loop interactions (e.g., starting/running the coroutine) behind the scenes.
Expand Down