The `postgrest` library provides an ORM-like interface for interacting with PostgREST APIs from Python. It supports both synchronous and asynchronous operations, allowing developers to easily query, insert, update, and delete data, as well as call stored procedures. The library is actively maintained, currently at version 2.28.3, and has a consistent release cadence with frequent updates.
pip install postgrestVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to initialize an `AsyncPostgrestClient`, perform basic CRUD (Create, Read, Update, Delete) operations, and call `execute()` to send requests. It assumes a running PostgREST server accessible at `POSTGREST_URL` with a 'countries' table. The example also shows how to optionally include authentication headers.
If upgrading from pre-1.0.0, ensure that you explicitly call `.schema()` for each query chain where a specific schema is needed, or instantiate a new client for each schema. Review your codebase for `.schema()` usage patterns.
If experiencing issues with `supabase_auth` after upgrading `postgrest` to versions >=2.24.0, consider locking your `postgrest` dependency to a compatible version (e.g., 2.23.x) or consult Supabase documentation for updated integration patterns.
Use `AsyncPostgrestClient` within `async` functions with `await` and `async with`. Use `SyncPostgrestClient` in regular, non-async Python code. Do not mix them directly without proper async bridge patterns (e.g., `asyncio.to_thread` for sync calls in async code).
Always access the query results via `response.data` after a successful `execute()` call. Implement proper error handling (e.g., `try...except` blocks) to catch `PostgrestAPIError` or other exceptions raised by failed requests.
Verify that the `POSTGREST_URL` used to initialize the client (e.g., `AsyncPostgrestClient` or `SyncPostgrestClient`) is correct and points to a valid, running, and publicly accessible PostgREST instance. Check network connectivity, firewall rules, and ensure the PostgREST server is operational and listening on the specified port.
Verify the `url` and any necessary connection `headers` (e.g., `apikey`) provided to the `PostgrestClient` constructor. Ensure the Postgrest server is running and accessible from where the client code is executed (check network connectivity, firewall rules, and server status).
Verify that your `url` and `headers` (if using JWT) parameters are correct, including the database host, port, username, and password. Ensure the PostgREST server (and underlying PostgreSQL database) is running and accessible from where the Python client is executed. Check PostgreSQL's `pg_hba.conf` for client authentication rules.
Access the `data` attribute of the `APIResponse` object directly to get the list of dictionaries. If you expect a single row, use `.single().execute()` to get a dictionary, or access the first element of the list `response.data[0]`.
```python
from postgrest import PostgrestClient
async def fetch_data(client: PostgrestClient):
response = await client.from_("mytable").select("*").execute()
# Correct way to access the data:
records = response.data # records is a list of dictionaries
print(records)
# If expecting a single record and using .single():
# single_record_response = await client.from_("mytable").select("*").eq("id", 1).single().execute()
# record = single_record_response.data # record is a dictionary
# print(record)
```Install the `postgrest-py` package using pip: ```bash pip install postgrest-py ``` Ensure you are installing it into the correct Python environment (e.g., your virtual environment) and that your script is running with that environment's Python interpreter. If you are importing `postgrest`, ensure the package name is correct in your `import` statement.
Examine the `code` and `message` within the `APIError` to understand the specific problem. Common fixes include: * Correcting the table or function name in your query. * Ensuring the PostgREST server's schema cache is up-to-date (which might require a server restart if the database schema changed). * Checking the PostgREST server logs for more detailed error information. * Verifying that the request body for insert/update operations is valid JSON and matches the table schema.
Ensure that you are correctly chaining methods in your query and terminating with an execution method. For instance, if you intend to execute a query, you must call `.execute()` at the end of the chain.
```python
from postgrest import PostgrestClient
async def query_users(client: PostgrestClient):
# Incorrect: Trying to call the select object
# users = await client.from_("users").select("*")()
# Correct: Chain methods and call .execute()
users_response = await client.from_("users").select("*").eq("status", "active").order("id").execute()
active_users = users_response.data
print(active_users)
```