PostgREST Client for Python

Warnings

• breaking The behavior of the `.schema()` method changed in version 1.0.0. It now persists only for the current query builder instance and does not affect subsequent queries on the client or other query builders.
  Fix: 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.
• breaking A 'minor breaking change' was noted for users integrating with `supabase_auth` around version 2.24.0. While not directly in the `postgrest` library itself, it indicates potential compatibility issues for Supabase users.
  Fix: 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.
• gotcha The library offers both `AsyncPostgrestClient` and `SyncPostgrestClient`. Mixing asynchronous and synchronous code incorrectly (e.g., calling `await` on a `SyncPostgrestClient` method or blocking an event loop with `SyncPostgrestClient` in an async context) will lead to errors or performance issues.
  Fix: 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).
• gotcha Responses from `execute()` contain the data in the `.data` attribute. Direct access to the response object might not yield the expected results if not correctly parsing the structure.
  Fix: 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.

Install

• pip install postgrest Latest Stable Release

Imports

• AsyncPostgrestClient

  from postgrest import AsyncPostgrestClient

  The primary asynchronous client for PostgREST interactions.
• SyncPostgrestClient

  from postgrest import SyncPostgrestClient

  The synchronous client for PostgREST interactions, useful in non-async contexts.

Quickstart

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.

import asyncio
import os
from postgrest import AsyncPostgrestClient

# Replace with your PostgREST URL and (optional) API key
POSTGREST_URL = os.environ.get('POSTGREST_URL', 'http://localhost:3000')
# BEARER_TOKEN = os.environ.get('POSTGREST_TOKEN', 'YOUR_API_KEY') # Optional, if authentication is required

async def main():
    # headers = {'Authorization': f'Bearer {BEARER_TOKEN}'} if BEARER_TOKEN else {}
    headers = {}

    async with AsyncPostgrestClient(POSTGREST_URL, headers=headers) as client:
        try:
            # Example: Insert data
            print('Inserting a new country...')
            insert_result = await client.from_('countries').insert({'name': 'Exampleland', 'capital': 'Example City'}).execute()
            print(f'Insert successful: {insert_result.data}')

            # Example: Read data
            print('Fetching countries...')
            response = await client.from_('countries').select('id', 'name', 'capital').limit(5).execute()
            print('Fetched countries:')
            for country in response.data:
                print(f"  ID: {country['id']}, Name: {country['name']}, Capital: {country['capital']}")

            # Example: Update data
            print('Updating Exampleland...')
            update_result = await client.from_('countries').update({'capital': 'New Example City'}).eq('name', 'Exampleland').execute()
            print(f'Update successful: {update_result.data}')
            
            # Example: Delete data
            print('Deleting Exampleland...')
            delete_result = await client.from_('countries').delete().eq('name', 'Exampleland').execute()
            print(f'Delete successful: {delete_result.data}')

        except Exception as e:
            print(f"An error occurred: {e}")

if __name__ == '__main__':
    asyncio.run(main())