pytest-neon 0.6.0__tar.gz → 2.0.0__tar.gz

{pytest_neon-0.6.0 → pytest_neon-2.0.0}/CLAUDE.md

@@ -13,7 +13,10 @@ This is a pytest plugin that provides isolated Neon database branches for integr
 - **Entry point**: `src/pytest_neon/plugin.py` - Contains all fixtures and pytest hooks
 - **Migration fixture**: `_neon_migration_branch` - Session-scoped, parent for all test branches
 - **User migration hook**: `neon_apply_migrations` - Session-scoped no-op, users override to run migrations
-- **Core fixture**: `neon_branch` - Creates branch (session-scoped), resets after each test (function-scoped wrapper), sets `DATABASE_URL`, yields `NeonBranch` dataclass
+- **Core fixtures**:
+  - `neon_branch_readwrite` - Function-scoped, resets after each test (recommended for write tests)
+  - `neon_branch_readonly` - Function-scoped, NO reset (recommended for read-only tests, faster)
+  - `neon_branch` - Deprecated alias for `neon_branch_readwrite`
 - **Shared fixture**: `neon_branch_shared` - Module-scoped, no reset between tests
 - **Convenience fixtures**: `neon_connection`, `neon_connection_psycopg`, `neon_engine` - Optional, require extras
 
@@ -28,7 +31,9 @@ This is a pytest plugin that provides isolated Neon database branches for integr
 - `_neon_migration_branch`: `scope="session"` - internal, parent for all test branches, migrations run here
 - `neon_apply_migrations`: `scope="session"` - user overrides to run migrations
 - `_neon_branch_for_reset`: `scope="session"` - internal, creates one branch per session from migration branch
-- `neon_branch`: `scope="function"` - wraps the above, resets branch after each test
+- `neon_branch_readwrite`: `scope="function"` - resets branch after each test (for write tests)
+- `neon_branch_readonly`: `scope="function"` - NO reset (for read-only tests, faster)
+- `neon_branch`: `scope="function"` - deprecated alias for `neon_branch_readwrite`
 - `neon_branch_shared`: `scope="module"` - one branch per test file, no reset
 - Connection fixtures: `scope="function"` (default) - fresh connection per test
 

{pytest_neon-0.6.0 → pytest_neon-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-neon
-Version: 0.6.0
+Version: 2.0.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
@@ -472,12 +517,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-0.6.0 → pytest_neon-2.0.0}/README.md

@@ -52,7 +52,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
 
@@ -60,6 +60,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:
@@ -70,33 +71,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.
 
@@ -162,19 +205,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.
 
@@ -390,7 +435,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
@@ -427,12 +472,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-0.6.0 → pytest_neon-2.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pytest-neon"
-version = "0.6.0"
+version = "2.0.0"
 description = "Pytest plugin for Neon database branch isolation in tests"
 readme = "README.md"
 license = "MIT"

{pytest_neon-0.6.0 → pytest_neon-2.0.0}/src/pytest_neon/__init__.py

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

{pytest_neon-0.6.0 → pytest_neon-2.0.0}/src/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
@@ -373,8 +379,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 +400,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")
@@ -538,16 +572,21 @@ def _neon_branch_for_reset(
 
 
 @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 +614,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 +632,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 +653,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-0.6.0 → pytest_neon-2.0.0}/tests/test_integration.py

@@ -69,16 +69,22 @@ pytestmark = pytest.mark.skipif(
 class TestRealBranchCreation:
     """Test actual branch creation against Neon API."""
 
-    def test_branch_is_created_and_accessible(self, neon_branch):
+    def test_branch_is_created_and_accessible(self, neon_branch_readwrite):
         """Test that a real branch is created and has valid connection info."""
-        assert neon_branch.branch_id.startswith("br-")
-        assert neon_branch.project_id == PROJECT_ID
-        assert "neon.tech" in neon_branch.host
-        assert neon_branch.connection_string.startswith("postgresql://")
+        assert neon_branch_readwrite.branch_id.startswith("br-")
+        assert neon_branch_readwrite.project_id == PROJECT_ID
+        assert "neon.tech" in neon_branch_readwrite.host
+        assert neon_branch_readwrite.connection_string.startswith("postgresql://")
 
-    def test_database_url_is_set(self, neon_branch):
+    def test_database_url_is_set(self, neon_branch_readwrite):
         """Test that DATABASE_URL environment variable is set."""
-        assert os.environ.get("DATABASE_URL") == neon_branch.connection_string
+        assert os.environ.get("DATABASE_URL") == neon_branch_readwrite.connection_string
+
+    def test_readonly_fixture_works(self, neon_branch_readonly):
+        """Test that readonly fixture provides valid connection info."""
+        assert neon_branch_readonly.branch_id.startswith("br-")
+        assert neon_branch_readonly.project_id == PROJECT_ID
+        assert neon_branch_readonly.connection_string.startswith("postgresql://")
 
 
 class TestMigrations:
@@ -159,7 +165,7 @@ def test_second_insert_after_reset(neon_branch):
 class TestRealDatabaseConnectivity:
     """Test actual database connectivity."""
 
-    def test_can_connect_and_query(self, neon_branch):
+    def test_can_connect_and_query(self, neon_branch_readwrite):
         """Test that we can actually connect to the created branch."""
         try:
             import psycopg
@@ -167,14 +173,14 @@ class TestRealDatabaseConnectivity:
             pytest.skip("psycopg not installed - run: pip install pytest-neon[psycopg]")
 
         with (
-            psycopg.connect(neon_branch.connection_string) as conn,
+            psycopg.connect(neon_branch_readwrite.connection_string) as conn,
             conn.cursor() as cur,
         ):
             cur.execute("SELECT 1 AS result")
             result = cur.fetchone()
             assert result[0] == 1
 
-    def test_can_create_and_query_table(self, neon_branch):
+    def test_can_create_and_query_table(self, neon_branch_readwrite):
         """Test that we can create tables and insert data."""
         try:
             import psycopg
@@ -182,7 +188,7 @@ class TestRealDatabaseConnectivity:
             pytest.skip("psycopg not installed - run: pip install pytest-neon[psycopg]")
 
         with (
-            psycopg.connect(neon_branch.connection_string) as conn,
+            psycopg.connect(neon_branch_readwrite.connection_string) as conn,
             conn.cursor() as cur,
         ):
             # Create a test table
@@ -207,6 +213,21 @@ class TestRealDatabaseConnectivity:
             result = cur.fetchone()
             assert result[0] == "test_value"
 
+    def test_readonly_can_query(self, neon_branch_readonly):
+        """Test that readonly fixture can execute queries."""
+        try:
+            import psycopg
+        except ImportError:
+            pytest.skip("psycopg not installed - run: pip install pytest-neon[psycopg]")
+
+        with (
+            psycopg.connect(neon_branch_readonly.connection_string) as conn,
+            conn.cursor() as cur,
+        ):
+            cur.execute("SELECT 1 AS result")
+            result = cur.fetchone()
+            assert result[0] == 1
+
 
 class TestSQLAlchemyPooledConnections:
     """Test SQLAlchemy connection pooling behavior with branch resets.
@@ -245,7 +266,7 @@ engine = create_engine(DATABASE_URL, pool_pre_ping=True) if DATABASE_URL else No
             test_sqlalchemy_reset="""
 from sqlalchemy import text
 
-def test_first_query(neon_branch):
+def test_first_query(neon_branch_readwrite):
     '''First test - creates pooled connection.'''
     from database import engine
     with engine.connect() as conn:
@@ -253,14 +274,14 @@ def test_first_query(neon_branch):
         assert result.scalar() == 1
     # Connection returned to pool
 
-def test_second_query_after_reset(neon_branch):
+def test_second_query_after_reset(neon_branch_readwrite):
     '''Second test - branch was reset, but pool_pre_ping handles it.'''
     from database import engine
     with engine.connect() as conn:
         result = conn.execute(text("SELECT 2"))
         assert result.scalar() == 2
 
-def test_third_query_after_another_reset(neon_branch):
+def test_third_query_after_another_reset(neon_branch_readwrite):
     '''Third test - still works thanks to pool_pre_ping.'''
     from database import engine
     with engine.connect() as conn:

pytest_neon-2.0.0/tests/test_readwrite_readonly_fixtures.py

@@ -0,0 +1,258 @@
+"""Tests for neon_branch_readwrite and neon_branch_readonly fixtures."""
+
+
+class TestReadwriteFixture:
+    """Test neon_branch_readwrite fixture behavior."""
+
+    def test_readwrite_resets_after_each_test(self, pytester):
+        """Verify that neon_branch_readwrite resets after each test."""
+        pytester.makeconftest(
+            """
+            import os
+            import pytest
+            from dataclasses import dataclass
+
+            reset_count = [0]
+
+            @dataclass
+            class FakeNeonBranch:
+                branch_id: str
+                project_id: str
+                connection_string: str
+                host: str
+                parent_id: str
+
+            @pytest.fixture(scope="session")
+            def _neon_branch_for_reset():
+                branch = FakeNeonBranch(
+                    branch_id="br-test",
+                    project_id="proj-test",
+                    connection_string="postgresql://test",
+                    host="test.neon.tech",
+                    parent_id="br-parent",
+                )
+                os.environ["DATABASE_URL"] = branch.connection_string
+                try:
+                    yield branch
+                finally:
+                    os.environ.pop("DATABASE_URL", None)
+
+            @pytest.fixture(scope="function")
+            def neon_branch_readwrite(_neon_branch_for_reset):
+                yield _neon_branch_for_reset
+                # Simulate reset
+                reset_count[0] += 1
+
+            def pytest_sessionfinish(session, exitstatus):
+                # Verify resets happened
+                assert reset_count[0] == 2, f"Expected 2 resets, got {reset_count[0]}"
+        """
+        )
+
+        pytester.makepyfile(
+            """
+            def test_first(neon_branch_readwrite):
+                assert neon_branch_readwrite.branch_id == "br-test"
+
+            def test_second(neon_branch_readwrite):
+                assert neon_branch_readwrite.branch_id == "br-test"
+        """
+        )
+
+        result = pytester.runpytest("-v")
+        result.assert_outcomes(passed=2)
+
+
+class TestReadonlyFixture:
+    """Test neon_branch_readonly fixture behavior."""
+
+    def test_readonly_does_not_reset(self, pytester):
+        """Verify that neon_branch_readonly does NOT reset after tests."""
+        pytester.makeconftest(
+            """
+            import os
+            import pytest
+            from dataclasses import dataclass
+
+            reset_count = [0]
+
+            @dataclass
+            class FakeNeonBranch:
+                branch_id: str
+                project_id: str
+                connection_string: str
+                host: str
+                parent_id: str
+
+            @pytest.fixture(scope="session")
+            def _neon_branch_for_reset():
+                branch = FakeNeonBranch(
+                    branch_id="br-test",
+                    project_id="proj-test",
+                    connection_string="postgresql://test",
+                    host="test.neon.tech",
+                    parent_id="br-parent",
+                )
+                os.environ["DATABASE_URL"] = branch.connection_string
+                try:
+                    yield branch
+                finally:
+                    os.environ.pop("DATABASE_URL", None)
+
+            @pytest.fixture(scope="function")
+            def neon_branch_readonly(_neon_branch_for_reset):
+                # No reset - just return the branch
+                return _neon_branch_for_reset
+
+            def pytest_sessionfinish(session, exitstatus):
+                # Verify NO resets happened
+                assert reset_count[0] == 0, f"Expected 0 resets, got {reset_count[0]}"
+        """
+        )
+
+        pytester.makepyfile(
+            """
+            def test_first(neon_branch_readonly):
+                assert neon_branch_readonly.branch_id == "br-test"
+
+            def test_second(neon_branch_readonly):
+                assert neon_branch_readonly.branch_id == "br-test"
+        """
+        )
+
+        result = pytester.runpytest("-v")
+        result.assert_outcomes(passed=2)
+
+
+class TestDeprecatedNeonBranch:
+    """Test that neon_branch emits deprecation warning."""
+
+    def test_neon_branch_emits_deprecation_warning(self, pytester):
+        """Verify that using neon_branch emits a deprecation warning."""
+        pytester.makeconftest(
+            """
+            import os
+            import pytest
+            from dataclasses import dataclass
+
+            @dataclass
+            class FakeNeonBranch:
+                branch_id: str
+                project_id: str
+                connection_string: str
+                host: str
+                parent_id: str
+
+            @pytest.fixture(scope="session")
+            def _neon_branch_for_reset():
+                branch = FakeNeonBranch(
+                    branch_id="br-test",
+                    project_id="proj-test",
+                    connection_string="postgresql://test",
+                    host="test.neon.tech",
+                    parent_id="br-parent",
+                )
+                os.environ["DATABASE_URL"] = branch.connection_string
+                try:
+                    yield branch
+                finally:
+                    os.environ.pop("DATABASE_URL", None)
+
+            @pytest.fixture(scope="function")
+            def neon_branch_readwrite(_neon_branch_for_reset):
+                yield _neon_branch_for_reset
+
+            @pytest.fixture(scope="function")
+            def neon_branch(neon_branch_readwrite):
+                import warnings
+                warnings.warn(
+                    "neon_branch is deprecated. Use neon_branch_readwrite or "
+                    "neon_branch_readonly instead.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+                yield neon_branch_readwrite
+        """
+        )
+
+        pytester.makepyfile(
+            """
+            def test_deprecated(neon_branch):
+                assert neon_branch.branch_id == "br-test"
+        """
+        )
+
+        result = pytester.runpytest("-v", "-W", "error::DeprecationWarning")
+        # Should error during fixture setup (deprecation warning treated as error)
+        result.assert_outcomes(errors=1)
+
+
+class TestFixtureUseTogether:
+    """Test using both fixtures in the same test session."""
+
+    def test_readwrite_and_readonly_can_coexist(self, pytester):
+        """Verify both fixtures can be used in the same test module."""
+        pytester.makeconftest(
+            """
+            import os
+            import pytest
+            from dataclasses import dataclass
+
+            reset_count = [0]
+
+            @dataclass
+            class FakeNeonBranch:
+                branch_id: str
+                project_id: str
+                connection_string: str
+                host: str
+                parent_id: str
+
+            @pytest.fixture(scope="session")
+            def _neon_branch_for_reset():
+                branch = FakeNeonBranch(
+                    branch_id="br-test",
+                    project_id="proj-test",
+                    connection_string="postgresql://test",
+                    host="test.neon.tech",
+                    parent_id="br-parent",
+                )
+                os.environ["DATABASE_URL"] = branch.connection_string
+                try:
+                    yield branch
+                finally:
+                    os.environ.pop("DATABASE_URL", None)
+
+            @pytest.fixture(scope="function")
+            def neon_branch_readwrite(_neon_branch_for_reset):
+                yield _neon_branch_for_reset
+                reset_count[0] += 1
+
+            @pytest.fixture(scope="function")
+            def neon_branch_readonly(_neon_branch_for_reset):
+                return _neon_branch_for_reset
+
+            def pytest_sessionfinish(session, exitstatus):
+                # Only readwrite tests should trigger reset
+                assert reset_count[0] == 1, f"Expected 1 reset, got {reset_count[0]}"
+        """
+        )
+
+        pytester.makepyfile(
+            """
+            def test_readonly_first(neon_branch_readonly):
+                '''Read-only test - no reset after.'''
+                assert neon_branch_readonly.branch_id == "br-test"
+
+            def test_readonly_second(neon_branch_readonly):
+                '''Another read-only test - still no reset.'''
+                assert neon_branch_readonly.branch_id == "br-test"
+
+            def test_readwrite(neon_branch_readwrite):
+                '''Read-write test - reset after this one.'''
+                assert neon_branch_readwrite.branch_id == "br-test"
+        """
+        )
+
+        result = pytester.runpytest("-v")
+        result.assert_outcomes(passed=3)

{pytest_neon-0.6.0 → pytest_neon-2.0.0}/tests/test_reset_behavior.py

@@ -1,5 +1,118 @@
 """Tests for branch reset behavior."""
 
+import pytest
+
+from pytest_neon.plugin import NeonBranch, _reset_branch_to_parent
+
+
+class TestResetRetryBehavior:
+    """Test that branch reset retries on transient failures."""
+
+    def test_reset_succeeds_after_transient_failures(self, mocker):
+        """Verify reset retries and succeeds after transient API errors."""
+        branch = NeonBranch(
+            branch_id="br-test",
+            project_id="proj-test",
+            connection_string="postgresql://test",
+            host="test.neon.tech",
+            parent_id="br-parent",
+        )
+
+        # Mock requests.post to fail twice, then succeed
+        mock_response = mocker.Mock()
+        mock_response.raise_for_status = mocker.Mock()
+
+        import requests
+
+        call_count = [0]
+
+        def mock_post(*args, **kwargs):
+            call_count[0] += 1
+            if call_count[0] < 3:
+                raise requests.RequestException("API rate limited")
+            return mock_response
+
+        mocker.patch("pytest_neon.plugin.requests.post", side_effect=mock_post)
+        mocker.patch("pytest_neon.plugin.time.sleep")  # Don't actually sleep
+
+        # Should succeed after retries
+        _reset_branch_to_parent(branch, "fake-api-key")
+
+        assert call_count[0] == 3  # 2 failures + 1 success
+
+    def test_reset_fails_after_max_retries(self, mocker):
+        """Verify reset raises after exhausting all retries."""
+        branch = NeonBranch(
+            branch_id="br-test",
+            project_id="proj-test",
+            connection_string="postgresql://test",
+            host="test.neon.tech",
+            parent_id="br-parent",
+        )
+
+        # Mock requests.post to always fail
+        import requests
+
+        mocker.patch(
+            "pytest_neon.plugin.requests.post",
+            side_effect=requests.RequestException("API error"),
+        )
+        mock_sleep = mocker.patch("pytest_neon.plugin.time.sleep")
+
+        # Should raise after max retries
+        with pytest.raises(requests.RequestException, match="API error"):
+            _reset_branch_to_parent(branch, "fake-api-key")
+
+        # Should have slept between retries (3 retries = 3 sleeps)
+        assert mock_sleep.call_count == 3
+
+    def test_reset_uses_exponential_backoff(self, mocker):
+        """Verify reset uses exponential backoff between retries."""
+        branch = NeonBranch(
+            branch_id="br-test",
+            project_id="proj-test",
+            connection_string="postgresql://test",
+            host="test.neon.tech",
+            parent_id="br-parent",
+        )
+
+        import requests
+
+        mocker.patch(
+            "pytest_neon.plugin.requests.post",
+            side_effect=requests.RequestException("API error"),
+        )
+        mock_sleep = mocker.patch("pytest_neon.plugin.time.sleep")
+
+        with pytest.raises(requests.RequestException):
+            _reset_branch_to_parent(branch, "fake-api-key")
+
+        # Check exponential backoff: 1s, 2s, 4s
+        sleep_calls = [call[0][0] for call in mock_sleep.call_args_list]
+        assert sleep_calls == [1, 2, 4]
+
+    def test_reset_no_retry_on_success(self, mocker):
+        """Verify reset doesn't retry when successful."""
+        branch = NeonBranch(
+            branch_id="br-test",
+            project_id="proj-test",
+            connection_string="postgresql://test",
+            host="test.neon.tech",
+            parent_id="br-parent",
+        )
+
+        mock_response = mocker.Mock()
+        mock_response.raise_for_status = mocker.Mock()
+        mock_post = mocker.patch(
+            "pytest_neon.plugin.requests.post", return_value=mock_response
+        )
+        mock_sleep = mocker.patch("pytest_neon.plugin.time.sleep")
+
+        _reset_branch_to_parent(branch, "fake-api-key")
+
+        assert mock_post.call_count == 1
+        assert mock_sleep.call_count == 0
+
 
 class TestResetBehavior:
     """Test that branch reset happens between tests."""

{pytest_neon-0.6.0 → pytest_neon-2.0.0}/uv.lock

@@ -1200,20 +1200,25 @@ wheels = [
 
 [[package]]
 name = "pytest-neon"
-version = "0.1.0"
+version = "1.0.0"
 source = { editable = "." }
 dependencies = [
     { name = "neon-api" },
     { name = "pytest", version = "8.4.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.10'" },
     { name = "pytest", version = "9.0.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.10'" },
+    { name = "requests" },
 ]
 
 [package.optional-dependencies]
 dev = [
     { name = "mypy" },
+    { name = "psycopg", version = "3.2.13", source = { registry = "https://pypi.org/simple" }, extra = ["binary"], marker = "python_full_version < '3.10'" },
+    { name = "psycopg", version = "3.3.2", source = { registry = "https://pypi.org/simple" }, extra = ["binary"], marker = "python_full_version >= '3.10'" },
+    { name = "psycopg2-binary" },
     { name = "pytest-cov" },
     { name = "pytest-mock" },
     { name = "ruff" },
+    { name = "sqlalchemy" },
 ]
 psycopg = [
     { name = "psycopg", version = "3.2.13", source = { registry = "https://pypi.org/simple" }, extra = ["binary"], marker = "python_full_version < '3.10'" },
@@ -1230,12 +1235,16 @@ sqlalchemy = [
 requires-dist = [
     { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.0" },
     { name = "neon-api", specifier = ">=0.1.0" },
+    { name = "psycopg", extras = ["binary"], marker = "extra == 'dev'", specifier = ">=3.1" },
     { name = "psycopg", extras = ["binary"], marker = "extra == 'psycopg'", specifier = ">=3.1" },
+    { name = "psycopg2-binary", marker = "extra == 'dev'", specifier = ">=2.9" },
     { name = "psycopg2-binary", marker = "extra == 'psycopg2'", specifier = ">=2.9" },
     { name = "pytest", specifier = ">=7.0" },
     { name = "pytest-cov", marker = "extra == 'dev'", specifier = ">=4.0" },
     { name = "pytest-mock", marker = "extra == 'dev'", specifier = ">=3.0" },
+    { name = "requests", specifier = ">=2.20" },
     { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.8" },
+    { name = "sqlalchemy", marker = "extra == 'dev'", specifier = ">=2.0" },
     { name = "sqlalchemy", marker = "extra == 'sqlalchemy'", specifier = ">=2.0" },
 ]
 provides-extras = ["psycopg2", "psycopg", "sqlalchemy", "dev"]