{"library":"postgrest","title":"PostgREST Client for Python","description":"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.","status":"active","version":"2.28.3","language":"en","source_language":"en","source_url":"https://github.com/supabase/postgrest-py","tags":["PostgreSQL","PostgREST","ORM","database","async","REST client","Supabase"],"install":[{"cmd":"pip install postgrest","lang":"bash","label":"Latest Stable Release"}],"dependencies":[{"reason":"HTTP client for making requests to PostgREST.","package":"httpx","optional":false},{"reason":"Used for handling deprecated features.","package":"deprecation","optional":false},{"reason":"Used for data validation and modeling.","package":"pydantic","optional":false},{"reason":"Provides StrEnum for Python versions <3.11.","package":"strenum","optional":false}],"imports":[{"note":"The primary asynchronous client for PostgREST interactions.","symbol":"AsyncPostgrestClient","correct":"from postgrest import AsyncPostgrestClient"},{"note":"The synchronous client for PostgREST interactions, useful in non-async contexts.","symbol":"SyncPostgrestClient","correct":"from postgrest import SyncPostgrestClient"}],"quickstart":{"code":"import asyncio\nimport os\nfrom postgrest import AsyncPostgrestClient\n\n# Replace with your PostgREST URL and (optional) API key\nPOSTGREST_URL = os.environ.get('POSTGREST_URL', 'http://localhost:3000')\n# BEARER_TOKEN = os.environ.get('POSTGREST_TOKEN', 'YOUR_API_KEY') # Optional, if authentication is required\n\nasync def main():\n    # headers = {'Authorization': f'Bearer {BEARER_TOKEN}'} if BEARER_TOKEN else {}\n    headers = {}\n\n    async with AsyncPostgrestClient(POSTGREST_URL, headers=headers) as client:\n        try:\n            # Example: Insert data\n            print('Inserting a new country...')\n            insert_result = await client.from_('countries').insert({'name': 'Exampleland', 'capital': 'Example City'}).execute()\n            print(f'Insert successful: {insert_result.data}')\n\n            # Example: Read data\n            print('Fetching countries...')\n            response = await client.from_('countries').select('id', 'name', 'capital').limit(5).execute()\n            print('Fetched countries:')\n            for country in response.data:\n                print(f\"  ID: {country['id']}, Name: {country['name']}, Capital: {country['capital']}\")\n\n            # Example: Update data\n            print('Updating Exampleland...')\n            update_result = await client.from_('countries').update({'capital': 'New Example City'}).eq('name', 'Exampleland').execute()\n            print(f'Update successful: {update_result.data}')\n            \n            # Example: Delete data\n            print('Deleting Exampleland...')\n            delete_result = await client.from_('countries').delete().eq('name', 'Exampleland').execute()\n            print(f'Delete successful: {delete_result.data}')\n\n        except Exception as e:\n            print(f\"An error occurred: {e}\")\n\nif __name__ == '__main__':\n    asyncio.run(main())","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.24.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}