pytest-neon 1.0.0__tar.gz → 2.1.0__tar.gz

{pytest_neon-1.0.0 → pytest_neon-2.1.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-1.0.0 → pytest_neon-2.1.0}/PKG-INFO

@@ -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-1.0.0 → pytest_neon-2.1.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
@@ -399,16 +444,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
 
@@ -427,12 +482,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-1.0.0 → pytest_neon-2.1.0}/pyproject.toml

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

{pytest_neon-1.0.0 → pytest_neon-2.1.0}/src/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",