Claude Cursor opencode Skill

pytest-databases

Use when working with pytest_databases, Docker DB fixtures, PostgreSQL/pgvector/ParadeDB, MySQL/MariaDB, Oracle/SQL Server, CockroachDB, MongoDB, Redis/Valkey, BigQuery/Spanner, MinIO, or RustFS. Not for mocked DBs.

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download litestar-org-litestar-skills-skills_pytest-databases-669a363.zip · 11 KB

Install

skills CLI npx skills add https://github.com/litestar-org/litestar-skills/tree/main/skills/pytest-databases
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install litestar-org-litestar-skills@llmmart
Git git clone https://github.com/litestar-org/litestar-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole litestar-org/litestar-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

pytest-databases

pytest-databases provides session-scoped, container-backed service fixtures. This guidance targets the immutable v0.19.0 tag. Load only the plugin modules the test suite uses. Consume a ready client fixture where one exists; otherwise connect with the client already used by the project.

Code Style Rules

  • Keep database I/O consistent with the project driver. The package's PostgreSQL connection fixtures use synchronous psycopg; do not await their methods.
  • Type service fixtures with the service class from the same plugin module.
  • Prefer ready client fixtures when provided. For service-only plugins, build the project's existing client from the service object's host, port, and credentials.
  • Keep plugin declarations in the nearest conftest.py; do not load every backend globally.

Quick Reference

Install and enable

pip install "pytest-databases[postgres]"

In conftest.py:

pytest_plugins = ["pytest_databases.docker.postgres"]

The core pytest_databases pytest entry point supplies docker_client and docker_service. Each database module supplies its own fixtures.

Choose the fixture shape

Need Use
A ready psycopg connection postgres_connection, a versioned PostgreSQL-family connection, or cockroachdb_connection
A ready vendor client bigquery_client, spanner_connection, mongodb_connection, an Oracle connection, a GizmoSQL connection, or an Azure Blob container client
Service coordinates for the project's own client The backend's *_service fixture
A specific PostgreSQL-family release Matching *_NN_service, *_NN_connection, and *_NN_port fixtures
Parallel worker isolation The backend's exact *_xdist_isolation_level fixture from xdist.md

See reference.md for the exact plugin, service, and ready-client matrix. Do not infer a *_connection fixture from a *_service fixture's name.


References Index

Official References

Shared Styleguide Baseline

Files (litestar-skills)
  • references
    • config.md 2.3 KB
      Loading…
    • databases.md 4 KB
      Loading…
    • reference.md 9.2 KB
      Loading…
    • troubleshooting.md 3 KB
      Loading…
    • xdist.md 3.6 KB
      Loading…
  • SKILL.md 8.1 KB
    ---
    name: pytest-databases
    description: "Use when working with pytest_databases, Docker DB fixtures, PostgreSQL/pgvector/ParadeDB, MySQL/MariaDB, Oracle/SQL Server, CockroachDB, MongoDB, Redis/Valkey, BigQuery/Spanner, MinIO, or RustFS. Not for mocked DBs."
    ---
    
    # pytest-databases
    
    `pytest-databases` provides session-scoped, container-backed service fixtures.
    This guidance targets the immutable `v0.19.0` tag. Load only the plugin modules
    the test suite uses. Consume a ready client fixture where one exists; otherwise
    connect with the client already used by the project.
    
    ## Code Style Rules
    
    - Keep database I/O consistent with the project driver. The package's
      PostgreSQL connection fixtures use synchronous `psycopg`; do not `await`
      their methods.
    - Type service fixtures with the service class from the same plugin module.
    - Prefer ready client fixtures when provided. For service-only plugins, build
      the project's existing client from the service object's host, port, and
      credentials.
    - Keep plugin declarations in the nearest `conftest.py`; do not load every
      backend globally.
    
    ## Quick Reference
    
    ### Install and enable
    
    ```bash
    pip install "pytest-databases[postgres]"
    ```
    
    In `conftest.py`:
    
    ```python
    pytest_plugins = ["pytest_databases.docker.postgres"]
    ```
    
    The core `pytest_databases` pytest entry point supplies `docker_client` and
    `docker_service`. Each database module supplies its own fixtures.
    
    ### Choose the fixture shape
    
    | Need | Use |
    | --- | --- |
    | A ready `psycopg` connection | `postgres_connection`, a versioned PostgreSQL-family connection, or `cockroachdb_connection` |
    | A ready vendor client | `bigquery_client`, `spanner_connection`, `mongodb_connection`, an Oracle connection, a GizmoSQL connection, or an Azure Blob container client |
    | Service coordinates for the project's own client | The backend's `*_service` fixture |
    | A specific PostgreSQL-family release | Matching `*_NN_service`, `*_NN_connection`, and `*_NN_port` fixtures |
    | Parallel worker isolation | The backend's exact `*_xdist_isolation_level` fixture from [xdist.md](references/xdist.md) |
    
    See [reference.md](references/reference.md) for the exact plugin, service, and
    ready-client matrix. Do not infer a `*_connection` fixture from a
    `*_service` fixture's name.
    
    <workflow>
    
    ## Workflow
    
    1. Install the extra matching the selected backend. Backends with no bundled
       Python client, such as MySQL, MariaDB, SQL Server, and YugabyteDB, expose
       service fixtures and expect the project to supply its own driver.
    2. Add only the required `pytest_databases.docker.<module>` entries to
       `pytest_plugins`.
    3. Prefer a ready client fixture listed in
       [reference.md](references/reference.md). Otherwise construct the project's
       existing client from the typed service fixture.
    4. Override session-scoped configuration fixtures in `conftest.py`. Use
       environment variables only where 0.19.0 explicitly reads them; see
       [config.md](references/config.md).
    5. For `pytest-xdist`, keep the default `"database"` isolation when the service
       supports logical namespaces. Override the backend's exact isolation fixture
       to `"server"` when each worker needs its own container.
    6. Run the focused integration tests against a Docker-compatible daemon.
    
    </workflow>
    
    <guardrails>
    
    ## Guardrails
    
    - **Connection fixtures vs service fixtures**: Ready-client fixtures
      (`*_connection`, `*_client`) exist for PostgreSQL-family, CockroachDB,
      Oracle, GizmoSQL, BigQuery, Spanner, MongoDB, and Azure Blob. Service-only
      backends (MySQL, MariaDB, SQL Server, YugabyteDB, Dolt, Redis, Dragonfly,
      KeyDB, Valkey, Elasticsearch, MinIO, and RustFS) export `*_service` fixtures
      but no ready client fixture. Note that `redis`, `valkey`, and `elastic_search`
      still import their Python client package at module load time for readiness
      checks, whereas `mysql`, `mariadb`, `mssql`, `yugabyte`, `dolt`, `minio`, and
      `rustfs` require no Python client dependency to start the service.
    - **Avoid broken alias fixtures in `v0.19.0`**:
      `elasticsearch_service` requests an undefined `elasticsearch8_service` fixture
      (missing underscore) — request `elasticsearch_8_service` or
      `elasticsearch_7_service` directly. `oracle_startup_connection` requests an
      undefined `oracle_23ai_startup_connection` fixture — request
      `oracle_23ai_connection` or `oracle_18c_connection` instead.
    - **Use exact `pytest_databases.docker.*` module names.** AlloyDB Omni,
      pgvector, and ParadeDB live in `pytest_databases.docker.postgres` (not
      `alloydb`); Azurite / Azure Blob lives in `pytest_databases.docker.azure_blob`
      (not `azurite`, with `AzureBlobService`, `azure_blob_container_client`, and
      `azure_blob_async_container_client`); Elasticsearch lives in
      `pytest_databases.docker.elastic_search` (not `elasticsearch` or
      `ElasticSearch`); Dragonfly and KeyDB live in `pytest_databases.docker.redis`.
    - **Keep synchronous fixtures synchronous.** `postgres_connection` is a
      `psycopg.Connection`; call `execute()` directly.
    - **Do not assume every backend uses the same xdist fixture name.** Azure Blob
      uses `azure_blob_xdist_isolation_level`; most others use
      `xdist_<backend>_isolation_level`.
    - **Do not pass custom `pytest` CLI flags.** Version `0.19.0` registers no
      `pytest_addoption` flags; configure services via session-scoped fixture
      overrides or the environment variables in [config.md](references/config.md).
    - **Do not hand-roll container teardown.** The package owns labelled container
      lifecycle through `docker_service`.
    - **Do not pin a host port without a reason.** Dynamic ports avoid conflicts.
      Use the 0.19.0 PostgreSQL-family `*_port` fixture or matching environment
      variable only when a rootless/container-network constraint requires it
      (`redis_port`, `dragonfly_port`, `keydb_port`, and `valkey_port` only read
      `*_service.port`).
    
    </guardrails>
    
    <validation>
    
    ## Validation Checkpoint
    
    - [ ] Installed version is `pytest-databases>=0.19.0`.
    - [ ] `pytest_plugins` names an existing module from
          [reference.md](references/reference.md).
    - [ ] Every requested fixture exists in that module's 0.19.0 fixture row.
    - [ ] Service-only backends use the project's own client rather than a
          fabricated `*_connection` fixture.
    - [ ] PostgreSQL connection examples use synchronous `psycopg` calls.
    - [ ] Configuration uses an actual fixture or environment variable from
          [config.md](references/config.md).
    - [ ] Xdist overrides use the backend's exact isolation-fixture name.
    - [ ] Container-backed tests run against a Docker-compatible daemon.
    
    </validation>
    
    <example>
    
    ## Example: synchronous PostgreSQL connection
    
    ```python
    import psycopg
    
    pytest_plugins = ["pytest_databases.docker.postgres"]
    
    
    def test_postgres_is_ready(
        postgres_connection: psycopg.Connection,
    ) -> None:
        row = postgres_connection.execute("SELECT 1").fetchone()
    
        assert row == (1,)
    ```
    
    `postgres_connection` is a synchronous `psycopg.Connection`. Use an async
    driver only by constructing it separately from `postgres_service`.
    
    </example>
    
    ---
    
    ## References Index
    
    - [Supported database patterns](references/databases.md) — ready-client and
      service-only examples.
    - [Complete fixture matrix](references/reference.md) — exact 0.19.0 modules,
      classes, service fixtures, and client/provider fixtures.
    - [Xdist parallel testing](references/xdist.md) — supported isolation fixture
      names and helper functions.
    - [Configuration](references/config.md) — fixture overrides and environment
      variables implemented by 0.19.0.
    - [Troubleshooting](references/troubleshooting.md) — runtime, plugin, client,
      and port failures.
    
    - [Litestar testing](../litestar-testing/SKILL.md) — integrate container-backed
      services with Litestar test clients and dependency overrides.
    
    ## Official References
    
    - <https://pypi.org/project/pytest-databases/0.19.0/>
    - <https://github.com/litestar-org/pytest-databases/tree/v0.19.0>
    - <https://github.com/litestar-org/pytest-databases/tree/v0.19.0/src/pytest_databases/docker>
    - <https://github.com/litestar-org/pytest-databases/tree/v0.19.0/tests>
    
    ## Shared Styleguide Baseline
    
    - [General Principles](../litestar-styleguide/references/general.md)
    - [Testing](../litestar-styleguide/references/testing.md)
    - [Python](../litestar-styleguide/references/python.md)
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.