### Building Docs Locally

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/README.md

Install documentation dependencies and serve the documentation locally using `mkdocs`.

```bash
uv sync --group docs
uv run mkdocs serve   # http://localhost:8000
```

--------------------------------

### Contributing: Development Setup

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/README.md

Clone the repository and install dependencies using `uv`. Run tests using `pytest`, with options for mock or integration tests.

```bash
git clone https://github.com/viperadnan-git/supabase-orm
cd supabase-orm
uv sync --all-groups
uv run pytest                # mock suite (always runs)
```

--------------------------------

### Copy .env.example and fill credentials

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/tests/integration/README.md

Before running integration tests locally, copy the example environment file and fill in your Supabase project URL and service-role key. This file is automatically loaded by `python-dotenv`.

```bash
cp .env.example .env       # then fill in SUPABASE_TEST_URL / SUPABASE_TEST_KEY
```

--------------------------------

### Install supabase-orm

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/README.md

Use `uv` or `pip` to install the library. Requires Python 3.11+, supabase-py 2.30+, and pydantic 2.13+.

```bash
uv add supabase-orm
# or
pip install supabase-orm
```

--------------------------------

### Quick Start: Define Models and Query Data

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/README.md

Define Pydantic models that map to Supabase tables and use chain-style queries with filters and ordering. Requires `lifespan` context manager for async operations.

```python
from uuid import UUID
from typing import Annotated
from supabase_orm import SupabaseModel, Relation, lifespan


class Owner(SupabaseModel, table="owners"):
    id: UUID
    email: str
    is_active: bool


class Pet(SupabaseModel, table="pets"):
    id: UUID
    name: str
    species: str
    adopted: bool
    owner: Annotated[Owner, Relation(join="inner")]


async with lifespan(SUPABASE_URL, SUPABASE_KEY):
    # Chain-style query (sequential AND)
    cats = await Pet.query.eq("species", "cat").order_by("-created_at").limit(10).all()

    # Typed predicates (OR / NOT / boolean composition)
    rescues = await Pet.query.or_(
        Pet.f.species == "cat",
        (Pet.f.species == "dog") & (Pet.f.adopted == False),
    ).all()

    # Writes
    p = await Pet.create(name="Whiskers", species="cat", adopted=False)
    p.name = "Mr. Whiskers"
    await p.save()

    # Stream every matching row, any table size
    async for pet in Pet.query.eq("adopted", False).iter():
        await process(pet)

    # Bulk update / delete (guards block unfiltered ops)
    await Pet.query.eq("adopted", False).update(adopted=True)
```

--------------------------------

### Async Client Initialization and Shutdown

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/docs/api/client.md

Manually initialize and shut down the async Supabase client. Ensure `shutdown()` is called in a `finally` block to clean up resources.

```python
from supabase import acreate_client
from supabase_orm import init, shutdown

init(await acreate_client(SUPABASE_URL, SUPABASE_KEY))
try:
    rows = await Pet.query.all()
finally:
    await shutdown()
```

--------------------------------

### Configure CI to run integration tests

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/tests/integration/README.md

Set up GitHub Actions to run integration tests by storing Supabase credentials as repository secrets and using them as environment variables during the test execution.

```yaml
name: Run integration tests
  env:
    SUPABASE_TEST_URL: ${{ secrets.SUPABASE_TEST_URL }}
    SUPABASE_TEST_KEY: ${{ secrets.SUPABASE_TEST_KEY }}
  run: uv run pytest tests/integration -v
```

--------------------------------

### Running Integration Tests

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/README.md

Execute integration tests against a live Supabase project by using the `-m integration` flag with `pytest`.

```bash
uv run pytest -m integration       # live Supabase
```

--------------------------------

### Synchronous Client Initialization and Shutdown

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/docs/api/client.md

Manually initialize and shut down the synchronous Supabase client for use in scripts or background tasks. Ensure `shutdown()` is called in a `finally` block.

```python
from supabase import create_client
from supabase_orm.sync import init, shutdown

init(create_client(SUPABASE_URL, SUPABASE_KEY))
try:
    rows = Pet.query.all()
finally:
    shutdown()
```

--------------------------------

### Sync Mode Usage

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/README.md

Utilize the sync mirror of the ORM by importing from `supabase_orm.sync`. This mode removes the need for `await` and `async` keywords. Initialize with a Supabase client and optionally shut down when done.

```python
from supabase import create_client
from supabase_orm.sync import SupabaseModel, init, shutdown

class Pet(SupabaseModel, table="pets"):
    id: UUID
    name: str
    species: str

init(create_client(SUPABASE_URL, SUPABASE_KEY))

cats = Pet.query.eq("species", "cat").limit(10).all()
for p in Pet.query.eq("species", "cat").iter():
    process(p)

shutdown()  # optional — process exit drains pools anyway
```

--------------------------------

### Return modes

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/docs/api/debug.md

Explains the different return modes available in the supabase_orm library.

```APIDOC
## Return modes

::: supabase_orm.ReturnMode
```

--------------------------------

### Run integration tests locally with pytest

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/tests/integration/README.md

Execute the integration test suite using `uv` and `pytest`. This command specifically targets the integration tests located in the `tests/integration` directory.

```bash
uv run pytest tests/integration -v          # run just the integration suite
```

```bash
uv run pytest -m integration -v             # same, via marker
```

```bash
uv run pytest                               # default: integration is skipped
```

--------------------------------

### Async Client with FastAPI Lifespan

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/docs/api/client.md

Use the `lifespan` context manager for automatic client management within FastAPI applications. The ORM client is available for the duration of the `async with` block.

```python
from supabase_orm import lifespan

async with lifespan(SUPABASE_URL, SUPABASE_KEY):
    # the orm sees the client for the duration of this block
    rows = await Pet.query.all()
```

--------------------------------

### ExplainResult

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/docs/api/debug.md

Provides details on the ExplainResult functionality within the supabase_orm library.

```APIDOC
## ExplainResult

::: supabase_orm.ExplainResult
```

--------------------------------

### SupabaseORMDoesNotExist

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/docs/api/exceptions.md

Raised when a query is expected to return exactly one object, but no objects are found.

```APIDOC
## SupabaseORMDoesNotExist

### Description
This exception is raised when an operation that requires a single, existing record (e.g., fetching by ID) does not find any matching records in the database.

### Usage
Use this exception to handle cases where a specific record was expected but not found, preventing potential `None` or unexpected behavior downstream.
```

--------------------------------

### SupabaseORMUsageError

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/docs/api/exceptions.md

Raised for general usage errors or invalid configurations within the ORM.

```APIDOC
## SupabaseORMUsageError

### Description
This exception is a catch-all for various usage-related errors within the Supabase ORM. It can indicate incorrect method calls, invalid parameters, or configuration issues that do not fall into more specific exception categories.

### Usage
Useful for handling a broad range of user-induced errors or misconfigurations in the ORM's application.
```

--------------------------------

### Skip-block Directive for Sync Generation

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/README.md

Use the `# gen_sync: skip-block` and `# gen_sync: end-skip` directives to exclude specific code blocks from being generated in the sync mirror.

```python
# gen_sync: skip-block
async def test_async_only():
    ...
# gen_sync: end-skip
```

--------------------------------

### Custom filter operators and serializers

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/docs/api/debug.md

Details on registering custom filter operators and serializers for enhanced data manipulation.

```APIDOC
## Custom filter operators and serializers

::: supabase_orm.register_op

::: supabase_orm.register_serializer

::: supabase_orm.serialize
```

--------------------------------

### SupabaseORMError

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/docs/api/exceptions.md

The base exception class for all Supabase ORM-related errors.

```APIDOC
## SupabaseORMError

### Description
This is the base class for all custom exceptions raised by the Supabase ORM. It serves as a general indicator that an error occurred within the ORM's operations.

### Usage
Catching `SupabaseORMError` can be useful for handling any ORM-specific error in a general way.
```

--------------------------------

### SupabaseORMMultipleObjectsReturned

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/docs/api/exceptions.md

Raised when a query is expected to return exactly one object, but multiple objects are found.

```APIDOC
## SupabaseORMMultipleObjectsReturned

### Description
This exception is raised when an operation that expects a single, unique record (e.g., fetching by a unique identifier) returns more than one matching record. This indicates a potential data integrity issue or an incorrect query.

### Usage
Catch this exception to identify and handle situations where a query returns ambiguous results when a unique result was anticipated.
```

--------------------------------

### supabase_orm.rpc_maybe_one

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/docs/api/rpc.md

An RPC function that calls a Supabase function and returns at most one row.

```APIDOC
## supabase_orm.rpc_maybe_one

### Description
Calls a Supabase stored procedure and returns at most one result. Returns None if no rows are found.

### Method
`rpc_maybe_one(name: str, params: dict = None)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
user = supabase_orm.rpc_maybe_one("get_user_by_email", {"email": "test@example.com"})
```

### Response
#### Success Response (200)
- **result** (dict or None) - A dictionary representing the single row returned by the stored procedure, or None if no rows are found.

#### Response Example
```json
{
  "result": {"id": 456, "name": "David"}
}
```

Or:

```json
{
  "result": null
}
```
```

--------------------------------

### supabase_orm.rpc

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/docs/api/rpc.md

A general-purpose RPC function to call Supabase functions. It can return multiple rows.

```APIDOC
## supabase_orm.rpc

### Description
Calls a Supabase stored procedure and returns a list of results.

### Method
`rpc(name: str, params: dict = None)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
results = supabase_orm.rpc("get_all_users")
```

### Response
#### Success Response (200)
- **results** (list) - A list of dictionaries, where each dictionary represents a row returned by the stored procedure.

#### Response Example
```json
{
  "results": [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"}
  ]
}
```
```

--------------------------------

### supabase_orm.rpc_one

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/docs/api/rpc.md

An RPC function that calls a Supabase function and expects exactly one row in return.

```APIDOC
## supabase_orm.rpc_one

### Description
Calls a Supabase stored procedure and returns a single result. Raises an error if zero or more than one row is returned.

### Method
`rpc_one(name: str, params: dict = None)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
user = supabase_orm.rpc_one("get_user_by_id", {"user_id": 123})
```

### Response
#### Success Response (200)
- **result** (dict) - A dictionary representing the single row returned by the stored procedure.

#### Response Example
```json
{
  "result": {"id": 123, "name": "Charlie"}
}
```
```

--------------------------------

### supabase_orm.rpc_scalar

Source: https://github.com/viperadnan-git/supabase-orm/blob/main/docs/api/rpc.md

An RPC function that calls a Supabase function and expects a single scalar value in return.

```APIDOC
## supabase_orm.rpc_scalar

### Description
Calls a Supabase stored procedure and returns a single scalar value. Raises an error if zero or more than one column/row is returned.

### Method
`rpc_scalar(name: str, params: dict = None)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
count = supabase_orm.rpc_scalar("count_active_users")
```

### Response
#### Success Response (200)
- **result** (any) - The single scalar value returned by the stored procedure.

#### Response Example
```json
{
  "result": 100
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.