pytest-neon 1.0.0__py3-none-any.whl → 2.1.0__py3-none-any.whl

pytest_neon/__init__.py

@@ -9,7 +9,7 @@ from pytest_neon.plugin import (
     neon_engine,
 )
 
-__version__ = "1.0.0"
+__version__ = "2.1.0"
 __all__ = [
     "NeonBranch",
     "neon_branch",

pytest_neon/plugin.py

@@ -5,15 +5,17 @@ instant branching feature. Each test gets a clean database state via
 branch reset after each test.
 
 Main fixtures:
-    neon_branch: Primary fixture - one branch per session, reset after each test
-    neon_branch_shared: Shared branch without reset (fastest, no isolation)
+    neon_branch_readwrite: Read-write access with reset after each test (recommended)
+    neon_branch_readonly: Read-only access, no reset (fastest for read-only tests)
+    neon_branch: Deprecated alias for neon_branch_readwrite
+    neon_branch_shared: Shared branch without reset (module-scoped)
     neon_connection: psycopg2 connection (requires psycopg2 extra)
     neon_connection_psycopg: psycopg v3 connection (requires psycopg extra)
     neon_engine: SQLAlchemy engine (requires sqlalchemy extra)
 
 SQLAlchemy Users:
     If you create your own SQLAlchemy engine (not using neon_engine fixture),
-    you MUST use pool_pre_ping=True:
+    you MUST use pool_pre_ping=True when using neon_branch_readwrite:
 
         engine = create_engine(DATABASE_URL, pool_pre_ping=True)
 
@@ -21,6 +23,9 @@ SQLAlchemy Users:
     Without pool_pre_ping, SQLAlchemy may try to reuse dead pooled connections,
     causing "SSL connection has been closed unexpectedly" errors.
 
+    Note: pool_pre_ping is not required for neon_branch_readonly since no
+    resets occur.
+
 Configuration:
     Set NEON_API_KEY and NEON_PROJECT_ID environment variables, or use
     --neon-api-key and --neon-project-id CLI options.
@@ -33,6 +38,7 @@ from __future__ import annotations
 import contextlib
 import os
 import time
+import warnings
 from collections.abc import Generator
 from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
@@ -50,6 +56,17 @@ DEFAULT_BRANCH_EXPIRY_SECONDS = 600
 _MIGRATIONS_NOT_DEFINED = object()
 
 
+def _get_xdist_worker_id() -> str:
+    """
+    Get the pytest-xdist worker ID, or "main" if not running under xdist.
+
+    When running tests in parallel with pytest-xdist, each worker process
+    gets a unique ID (gw0, gw1, gw2, etc.). This is used to create separate
+    branches per worker to avoid database state pollution between parallel tests.
+    """
+    return os.environ.get("PYTEST_XDIST_WORKER", "main")
+
+
 def _get_schema_fingerprint(connection_string: str) -> tuple[tuple[Any, ...], ...]:
     """
     Get a fingerprint of the database schema for change detection.
@@ -373,8 +390,19 @@ def _create_neon_branch(
                 )
 
 
-def _reset_branch_to_parent(branch: NeonBranch, api_key: str) -> None:
-    """Reset a branch to its parent's state using the Neon API."""
+def _reset_branch_to_parent(
+    branch: NeonBranch, api_key: str, max_retries: int = 3
+) -> None:
+    """Reset a branch to its parent's state using the Neon API.
+
+    Uses exponential backoff retry logic to handle transient API errors
+    that can occur during parallel test execution.
+
+    Args:
+        branch: The branch to reset
+        api_key: Neon API key
+        max_retries: Maximum number of retry attempts (default: 3)
+    """
     if not branch.parent_id:
         raise RuntimeError(f"Branch {branch.branch_id} has no parent - cannot reset")
 
@@ -383,10 +411,27 @@ def _reset_branch_to_parent(branch: NeonBranch, api_key: str) -> None:
         "Authorization": f"Bearer {api_key}",
         "Content-Type": "application/json",
     }
-    response = requests.post(
-        url, headers=headers, json={"source_branch_id": branch.parent_id}, timeout=30
-    )
-    response.raise_for_status()
+
+    last_error: Exception | None = None
+    for attempt in range(max_retries + 1):
+        try:
+            response = requests.post(
+                url,
+                headers=headers,
+                json={"source_branch_id": branch.parent_id},
+                timeout=30,
+            )
+            response.raise_for_status()
+            return  # Success
+        except requests.RequestException as e:
+            last_error = e
+            if attempt < max_retries:
+                # Exponential backoff: 1s, 2s, 4s
+                wait_time = 2**attempt
+                time.sleep(wait_time)
+
+    # All retries exhausted
+    raise last_error  # type: ignore[misc]
 
 
 @pytest.fixture(scope="session")
@@ -493,6 +538,12 @@ def _neon_branch_for_reset(
     session, avoiding issues with Python's module caching (e.g., SQLAlchemy
     engines created at import time would otherwise point to stale branches).
 
+    Parallel Test Support (pytest-xdist):
+        When running tests in parallel with pytest-xdist, each worker gets its
+        own branch. This prevents database state pollution between tests running
+        concurrently on different workers. The worker ID is included in the
+        branch name suffix (e.g., "-test-gw0", "-test-gw1").
+
     Smart Migration Detection:
         This fixture implements a cost-optimization strategy:
 
@@ -524,30 +575,41 @@ def _neon_branch_for_reset(
         # Assume migrations changed something to be safe
         schema_changed = True
 
+    # Get worker ID for parallel test support
+    # Each xdist worker gets its own branch to avoid state pollution
+    worker_id = _get_xdist_worker_id()
+    branch_suffix = f"-test-{worker_id}"
+
     # Only create a child branch if migrations actually modified the schema
-    if schema_changed:
+    # OR if we're running under xdist (each worker needs its own branch)
+    if schema_changed or worker_id != "main":
         yield from _create_neon_branch(
             request,
             parent_branch_id_override=_neon_migration_branch.branch_id,
-            branch_name_suffix="-test",
+            branch_name_suffix=branch_suffix,
         )
     else:
-        # No schema changes - reuse the migration branch directly
+        # No schema changes and not parallel - reuse the migration branch directly
         # This saves creating an unnecessary branch
         yield _neon_migration_branch
 
 
 @pytest.fixture(scope="function")
-def neon_branch(
+def neon_branch_readwrite(
     request: pytest.FixtureRequest,
     _neon_branch_for_reset: NeonBranch,
 ) -> Generator[NeonBranch, None, None]:
     """
-    Provide an isolated Neon database branch for each test.
+    Provide a read-write Neon database branch with reset after each test.
+
+    This is the recommended fixture for tests that modify database state.
+    It creates one branch per test session, then resets it to the parent
+    branch's state after each test. This provides test isolation with
+    ~0.5s overhead per test.
 
-    This is the primary fixture for database testing. It creates one branch per
-    test session, then resets it to the parent branch's state after each test.
-    This provides test isolation with ~0.5s overhead per test.
+    Use this fixture when your tests INSERT, UPDATE, or DELETE data.
+    For read-only tests, use ``neon_branch_readonly`` instead for better
+    performance (no reset overhead).
 
     The branch is automatically deleted after all tests complete, unless
     --neon-keep-branches is specified. Branches also auto-expire after
@@ -575,11 +637,16 @@ def neon_branch(
 
     Example::
 
-        def test_database_operation(neon_branch):
+        def test_insert_user(neon_branch_readwrite):
             # DATABASE_URL is automatically set
             conn_string = os.environ["DATABASE_URL"]
             # or use directly
-            conn_string = neon_branch.connection_string
+            conn_string = neon_branch_readwrite.connection_string
+
+            # Insert data - branch will reset after this test
+            with psycopg.connect(conn_string) as conn:
+                conn.execute("INSERT INTO users (name) VALUES ('test')")
+                conn.commit()
     """
     config = request.config
     api_key = _get_config_value(config, "neon_api_key", "NEON_API_KEY", "neon_api_key")
@@ -588,8 +655,9 @@ def neon_branch(
     if not _neon_branch_for_reset.parent_id:
         pytest.fail(
             f"\n\nBranch {_neon_branch_for_reset.branch_id} has no parent. "
-            f"The neon_branch fixture requires a parent branch for reset.\n\n"
-            f"Use neon_branch_shared if you don't need reset, or specify "
+            f"The neon_branch_readwrite fixture requires a parent branch for "
+            f"reset.\n\n"
+            f"Use neon_branch_readonly if you don't need reset, or specify "
             f"a parent branch with --neon-parent-branch or NEON_PARENT_BRANCH_ID."
         )
 
@@ -608,6 +676,77 @@ def neon_branch(
             )
 
 
+@pytest.fixture(scope="function")
+def neon_branch_readonly(
+    _neon_branch_for_reset: NeonBranch,
+) -> NeonBranch:
+    """
+    Provide a read-only Neon database branch without reset.
+
+    This is the recommended fixture for tests that only read data (SELECT queries).
+    No branch reset occurs after each test, making it faster than
+    ``neon_branch_readwrite`` (~0.5s saved per test).
+
+    Use this fixture when your tests only perform SELECT queries and don't
+    modify database state. For tests that INSERT, UPDATE, or DELETE data,
+    use ``neon_branch_readwrite`` instead to ensure test isolation.
+
+    Warning:
+        If you accidentally write data using this fixture, subsequent tests
+        will see those modifications. The fixture does not enforce read-only
+        access at the database level - it simply skips the reset step.
+
+    The connection string is automatically set in the DATABASE_URL environment
+    variable (configurable via --neon-env-var).
+
+    Requires either:
+        - NEON_API_KEY and NEON_PROJECT_ID environment variables, or
+        - --neon-api-key and --neon-project-id command line options
+
+    Yields:
+        NeonBranch: Object with branch_id, project_id, connection_string, and host.
+
+    Example::
+
+        def test_query_users(neon_branch_readonly):
+            # DATABASE_URL is automatically set
+            conn_string = os.environ["DATABASE_URL"]
+
+            # Read-only query - no reset needed after this test
+            with psycopg.connect(conn_string) as conn:
+                result = conn.execute("SELECT * FROM users").fetchall()
+                assert len(result) > 0
+    """
+    return _neon_branch_for_reset
+
+
+@pytest.fixture(scope="function")
+def neon_branch(
+    request: pytest.FixtureRequest,
+    neon_branch_readwrite: NeonBranch,
+) -> Generator[NeonBranch, None, None]:
+    """
+    Deprecated: Use ``neon_branch_readwrite`` or ``neon_branch_readonly`` instead.
+
+    This fixture is an alias for ``neon_branch_readwrite`` and will be removed
+    in a future version. Please migrate to the explicit fixture names:
+
+    - ``neon_branch_readwrite``: For tests that modify data (INSERT/UPDATE/DELETE)
+    - ``neon_branch_readonly``: For tests that only read data (SELECT)
+
+    .. deprecated:: 1.1.0
+        Use ``neon_branch_readwrite`` for read-write access with reset,
+        or ``neon_branch_readonly`` for read-only access without reset.
+    """
+    warnings.warn(
+        "neon_branch is deprecated. Use neon_branch_readwrite (for tests that "
+        "modify data) or neon_branch_readonly (for read-only tests) instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    yield neon_branch_readwrite
+
+
 @pytest.fixture(scope="module")
 def neon_branch_shared(
     request: pytest.FixtureRequest,

{pytest_neon-1.0.0.dist-info → pytest_neon-2.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-neon
-Version: 1.0.0
+Version: 2.1.0
 Summary: Pytest plugin for Neon database branch isolation in tests
 Project-URL: Homepage, https://github.com/ZainRizvi/pytest-neon
 Project-URL: Repository, https://github.com/ZainRizvi/pytest-neon
@@ -97,7 +97,7 @@ export NEON_PROJECT_ID="your-project-id"
 2. Write tests:
 
 ```python
-def test_user_creation(neon_branch):
+def test_user_creation(neon_branch_readwrite):
     # DATABASE_URL is automatically set to the test branch
     import psycopg  # Your own install
 
@@ -105,6 +105,7 @@ def test_user_creation(neon_branch):
         with conn.cursor() as cur:
             cur.execute("INSERT INTO users (email) VALUES ('test@example.com')")
         conn.commit()
+    # Branch automatically resets after test - next test sees clean state
 ```
 
 3. Run tests:
@@ -115,33 +116,75 @@ pytest
 
 ## Fixtures
 
-### `neon_branch` (default, recommended)
+**Which fixture should I use?**
 
-The primary fixture for database testing. Creates one branch per test session, then resets it to the parent branch's state after each test. This provides test isolation with ~0.5s overhead per test.
+- **Use `neon_branch_readonly`** if your test only reads data (SELECT queries). This is the fastest option with no per-test overhead.
+- **Use `neon_branch_readwrite`** if your test modifies data (INSERT, UPDATE, DELETE). This resets the branch after each test for isolation.
 
-Returns a `NeonBranch` dataclass with:
+### `neon_branch_readonly` (recommended, fastest)
 
-- `branch_id`: The Neon branch ID
-- `project_id`: The Neon project ID
-- `connection_string`: Full PostgreSQL connection URI
-- `host`: The database host
-- `parent_id`: The parent branch ID (used for resets)
+**Use this fixture by default** if your tests don't need to write data. It provides the best performance by skipping the branch reset step (~0.5s saved per test), which also reduces API calls and avoids rate limiting issues.
+
+```python
+def test_query_users(neon_branch_readonly):
+    # DATABASE_URL is set automatically
+    import psycopg
+    with psycopg.connect(neon_branch_readonly.connection_string) as conn:
+        result = conn.execute("SELECT * FROM users").fetchall()
+        assert len(result) >= 0
+    # No reset after this test - fast!
+```
+
+**Use this when**:
+- Tests only perform SELECT queries
+- Tests don't modify database state
+- You want maximum performance
+
+**Warning**: If you accidentally write data using this fixture, subsequent tests will see those modifications. The fixture does not enforce read-only access at the database level.
+
+**Performance**: ~1.5s initial setup per session, **no per-test overhead**. For 10 read-only tests, expect only ~1.5s total overhead (vs ~6.5s with readwrite).
+
+### `neon_branch_readwrite` (for write tests)
+
+Use this fixture when your tests need to INSERT, UPDATE, or DELETE data. Creates one branch per test session, then resets it to the parent branch's state after each test. This provides test isolation with ~0.5s overhead per test.
 
 ```python
 import os
 
-def test_branch_info(neon_branch):
+def test_insert_user(neon_branch_readwrite):
     # DATABASE_URL is set automatically
-    assert os.environ["DATABASE_URL"] == neon_branch.connection_string
+    assert os.environ["DATABASE_URL"] == neon_branch_readwrite.connection_string
 
     # Use with any driver
     import psycopg
-    conn = psycopg.connect(neon_branch.connection_string)
+    with psycopg.connect(neon_branch_readwrite.connection_string) as conn:
+        conn.execute("INSERT INTO users (name) VALUES ('test')")
+        conn.commit()
+    # Branch resets after this test - changes won't affect other tests
 ```
 
-**Performance**: ~1.5s initial setup per session + ~0.5s reset per test. For 10 tests, expect ~6.5s total overhead.
+**Performance**: ~1.5s initial setup per session + ~0.5s reset per test. For 10 write tests, expect ~6.5s total overhead.
 
-### `neon_branch_shared` (fastest, no isolation)
+### `NeonBranch` dataclass
+
+Both fixtures return a `NeonBranch` dataclass with:
+
+- `branch_id`: The Neon branch ID
+- `project_id`: The Neon project ID
+- `connection_string`: Full PostgreSQL connection URI
+- `host`: The database host
+- `parent_id`: The parent branch ID (used for resets)
+
+### `neon_branch` (deprecated)
+
+> **Deprecated**: Use `neon_branch_readwrite` or `neon_branch_readonly` instead.
+
+This fixture is an alias for `neon_branch_readwrite` and will emit a deprecation warning. Migrate to the explicit fixture names for clarity:
+
+- `neon_branch_readwrite`: For tests that modify data (INSERT/UPDATE/DELETE)
+- `neon_branch_readonly`: For tests that only read data (SELECT)
+
+### `neon_branch_shared` (module-scoped, no isolation)
 
 Creates one branch per test module and shares it across all tests without resetting. This is the fastest option but tests can see each other's data modifications.
 
@@ -207,19 +250,21 @@ def test_query(neon_engine):
 
 ### Using Your Own SQLAlchemy Engine
 
-If you have a module-level SQLAlchemy engine (common pattern), you **must** use `pool_pre_ping=True`:
+If you have a module-level SQLAlchemy engine (common pattern) and use `neon_branch_readwrite`, you **must** use `pool_pre_ping=True`:
 
 ```python
 # database.py
 from sqlalchemy import create_engine
 from config import DATABASE_URL
 
-# pool_pre_ping=True is REQUIRED for pytest-neon
+# pool_pre_ping=True is REQUIRED when using neon_branch_readwrite
 # It verifies connections are alive before using them
 engine = create_engine(DATABASE_URL, pool_pre_ping=True)
 ```
 
-**Why?** After each test, pytest-neon resets the branch which terminates server-side connections. Without `pool_pre_ping`, SQLAlchemy may try to reuse a dead pooled connection, causing `SSL connection has been closed unexpectedly` errors.
+**Why?** After each test, `neon_branch_readwrite` resets the branch which terminates server-side connections. Without `pool_pre_ping`, SQLAlchemy may try to reuse a dead pooled connection, causing `SSL connection has been closed unexpectedly` errors.
+
+**Note**: If you only use `neon_branch_readonly`, `pool_pre_ping` is not required since no resets occur.
 
 This is also a best practice for any cloud database (Neon, RDS, etc.) where connections can be terminated externally.
 
@@ -435,7 +480,7 @@ Branches use copy-on-write storage, so you only pay for data that differs from t
 
 ### What Reset Does
 
-The `neon_branch` fixture uses Neon's branch restore API to reset database state after each test:
+The `neon_branch_readwrite` fixture uses Neon's branch restore API to reset database state after each test:
 
 - **Data changes are reverted**: All INSERT, UPDATE, DELETE operations are undone
 - **Schema changes are reverted**: CREATE TABLE, ALTER TABLE, DROP TABLE, etc. are undone
@@ -444,16 +489,26 @@ The `neon_branch` fixture uses Neon's branch restore API to reset database state
 
 This is similar to database transactions but at the branch level.
 
-## Limitations
+## Parallel Test Execution (pytest-xdist)
+
+This plugin supports parallel test execution with [pytest-xdist](https://pytest-xdist.readthedocs.io/). Each xdist worker automatically gets its own isolated branch.
 
-### Parallel Test Execution
+```bash
+# Run tests in parallel with 4 workers
+pip install pytest-xdist
+pytest -n 4
+```
 
-This plugin sets the `DATABASE_URL` environment variable, which is process-global. This means it is **not compatible with pytest-xdist** or other parallel test runners that run tests in the same process.
+**How it works:**
+- Each xdist worker (gw0, gw1, gw2, etc.) creates its own branch
+- Branches are named with the worker ID suffix (e.g., `-test-gw0`, `-test-gw1`)
+- Workers run tests in parallel without database state interference
+- All branches are cleaned up after the test session
 
-If you need parallel execution, you can:
-- Use `neon_branch.connection_string` directly instead of relying on `DATABASE_URL`
-- Run with `pytest-xdist --dist=loadfile` to keep modules in separate processes
-- Run tests serially (default pytest behavior)
+**Cost implications:**
+- Running with `-n 4` creates 4 branches (one per worker) plus the migration branch
+- Choose your parallelism level based on your Neon plan's branch limits
+- Each worker's branch is reset after each test using the fast reset operation (~0.5s)
 
 ## Troubleshooting
 
@@ -472,12 +527,12 @@ pip install pytest-neon[psycopg2]
 pip install pytest-neon[sqlalchemy]
 ```
 
-Or use the core `neon_branch` fixture with your own driver:
+Or use the core fixtures with your own driver:
 
 ```python
-def test_example(neon_branch):
+def test_example(neon_branch_readwrite):
     import my_preferred_driver
-    conn = my_preferred_driver.connect(neon_branch.connection_string)
+    conn = my_preferred_driver.connect(neon_branch_readwrite.connection_string)
 ```
 
 ### "Neon API key not configured"

pytest_neon-2.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pytest_neon/__init__.py,sha256=69SoGL2ciE38uvrXpEQPXiBFDkbWct7hl_k9MmswcSU,398
+pytest_neon/plugin.py,sha256=rb9CgOqle-sQHHoyFO5xDZ5wzrHx_4BLygiVywEYGbM,34949
+pytest_neon/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pytest_neon-2.1.0.dist-info/METADATA,sha256=ebdenaxT8v4GQeepZCglp04mb92iwJxp1PMnnS-9Nqs,18734
+pytest_neon-2.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+pytest_neon-2.1.0.dist-info/entry_points.txt,sha256=5U88Idj_G8-PSDb9VF3OwYFbGLHnGOo_GxgYvi0dtXw,37
+pytest_neon-2.1.0.dist-info/licenses/LICENSE,sha256=aKKp_Ex4WBHTByY4BhXJ181dzB_qYhi2pCUmZ7Spn_0,1067
+pytest_neon-2.1.0.dist-info/RECORD,,

pytest_neon-1.0.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-pytest_neon/__init__.py,sha256=6-QHwHgghlOfVqYOMZqlqYYCPPyzaqSlWF2fwgzS7Yo,398
-pytest_neon/plugin.py,sha256=6wcZe9E90y2kya4wM0ur9EtUhqWFUll_ebN4xgsogPk,29601
-pytest_neon/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pytest_neon-1.0.0.dist-info/METADATA,sha256=C0ZIKFJNBNr_n9yyhUvGgM8uLhKp5uZbYPb7wzKCF6M,16057
-pytest_neon-1.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-pytest_neon-1.0.0.dist-info/entry_points.txt,sha256=5U88Idj_G8-PSDb9VF3OwYFbGLHnGOo_GxgYvi0dtXw,37
-pytest_neon-1.0.0.dist-info/licenses/LICENSE,sha256=aKKp_Ex4WBHTByY4BhXJ181dzB_qYhi2pCUmZ7Spn_0,1067
-pytest_neon-1.0.0.dist-info/RECORD,,