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

{pytest_neon-0.5.0 → pytest_neon-0.6.0}/.github/workflows/release.yml

@@ -23,6 +23,29 @@ jobs:
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Check CI status
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+        run: |
+          SHA=$(git rev-parse HEAD)
+          echo "Checking CI status for commit: $SHA"
+
+          # Get check runs excluding this release workflow
+          FAILED=$(gh api "repos/$REPO/commits/$SHA/check-runs" \
+            --jq '[.check_runs[] | select(.name != "release") | select(.conclusion != "success" and .conclusion != "skipped")] | length')
+
+          if [ "$FAILED" != "0" ]; then
+            echo "❌ CI checks have not passed on this commit"
+            echo ""
+            echo "Check runs:"
+            gh api "repos/$REPO/commits/$SHA/check-runs" \
+              --jq '.check_runs[] | select(.name != "release") | "  - \(.name): \(.conclusion // .status)"'
+            exit 1
+          fi
+
+          echo "✅ All CI checks passed"
+
       - name: Set up Python
         uses: actions/setup-python@v5
         with:

{pytest_neon-0.5.0 → pytest_neon-0.6.0}/.github/workflows/tests.yml

@@ -3,8 +3,18 @@ name: Tests
 on:
   push:
     branches: [main]
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - ".github/workflows/tests.yml"
   pull_request:
     branches: [main]
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - ".github/workflows/tests.yml"
 
 jobs:
   test:
@@ -25,7 +35,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev,psycopg]"
+          pip install -e ".[dev]"
 
       - name: Run unit tests
         run: pytest tests/ --ignore=tests/test_integration.py -v
@@ -46,7 +56,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev,psycopg]"
+          pip install -e ".[dev]"
 
       - name: Run integration tests
         env:

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

@@ -13,7 +13,7 @@ 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 (module-scoped), resets after each test (function-scoped wrapper), sets `DATABASE_URL`, yields `NeonBranch` dataclass
+- **Core fixture**: `neon_branch` - Creates branch (session-scoped), resets after each test (function-scoped wrapper), sets `DATABASE_URL`, yields `NeonBranch` dataclass
 - **Shared fixture**: `neon_branch_shared` - Module-scoped, no reset between tests
 - **Convenience fixtures**: `neon_connection`, `neon_connection_psycopg`, `neon_engine` - Optional, require extras
 
@@ -27,7 +27,7 @@ This is a pytest plugin that provides isolated Neon database branches for integr
 ### Fixture Scopes
 - `_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="module"` - internal, creates one branch per test file from migration branch
+- `_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_shared`: `scope="module"` - one branch per test file, no reset
 - Connection fixtures: `scope="function"` (default) - fresh connection per test
@@ -35,15 +35,43 @@ This is a pytest plugin that provides isolated Neon database branches for integr
 ### Environment Variable Handling
 The `_create_neon_branch` function sets `DATABASE_URL` (or configured env var) during the fixture lifecycle and restores the original value in the finally block. This is critical for not polluting other tests.
 
+### Smart Migration Detection (Cost Optimization)
+The plugin avoids creating unnecessary branches through a two-layer detection strategy:
+
+1. **Sentinel detection**: If `neon_apply_migrations` is not overridden, it returns `_MIGRATIONS_NOT_DEFINED` sentinel. No child branch is created.
+
+2. **Schema fingerprint comparison**: If migrations are defined, the plugin captures `information_schema.columns` before migrations run and compares after. Only creates a child branch if the schema actually changed.
+
+**Design philosophy**: Users who define a migration fixture but rarely have actual pending migrations shouldn't pay for an extra branch every test run. The schema fingerprint approach detects actual changes, not just "migration code ran."
+
+**Implementation notes**:
+- Pre-migration fingerprint is captured in `_neon_migration_branch` and stored on `request.config`
+- Post-migration comparison happens in `_neon_branch_for_reset`
+- Falls back to assuming changes if no psycopg/psycopg2 is available for fingerprinting
+- Only checks schema (tables, columns), not data - this is intentional since seeding is not the use case
+
 ### Error Messages
 Convenience fixtures use `pytest.fail()` with detailed, formatted error messages when dependencies are missing. Keep this pattern - users need clear guidance on how to fix import errors.
 
+## Documentation
+
+Important help text should be documented in BOTH:
+1. **README.md** - Full user-facing documentation
+2. **Module/fixture docstrings** - So `help(pytest_neon)` shows useful info
+
+The module docstring in `plugin.py` should include key usage notes (like the SQLAlchemy `pool_pre_ping=True` requirement). Keep docstrings and README in sync.
+
 ## Commit Messages
 - Do NOT add Claude attribution or Co-Authored-By lines
 - Keep commits clean and descriptive
 
 ## Testing
 
+Run tests with:
+```bash
+uv run pytest tests/ -v
+```
+
 Tests in `tests/` use `pytester` for testing pytest plugins. The plugin itself can be tested without a real Neon connection by mocking `NeonAPI`.
 
 ## Publishing

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

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: pytest-neon
-Version: 0.5.0
+Version: 0.6.0
 Summary: Pytest plugin for Neon database branch isolation in tests
-Project-URL: Homepage, https://github.com/zain/pytest-neon
-Project-URL: Repository, https://github.com/zain/pytest-neon
-Project-URL: Issues, https://github.com/zain/pytest-neon/issues
+Project-URL: Homepage, https://github.com/ZainRizvi/pytest-neon
+Project-URL: Repository, https://github.com/ZainRizvi/pytest-neon
+Project-URL: Issues, https://github.com/ZainRizvi/pytest-neon/issues
 Author: Zain Rizvi
 License-Expression: MIT
 License-File: LICENSE
@@ -29,9 +29,12 @@ Requires-Dist: pytest>=7.0
 Requires-Dist: requests>=2.20
 Provides-Extra: dev
 Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: psycopg2-binary>=2.9; extra == 'dev'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest-mock>=3.0; extra == 'dev'
 Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: sqlalchemy>=2.0; extra == 'dev'
 Provides-Extra: psycopg
 Requires-Dist: psycopg[binary]>=3.1; extra == 'psycopg'
 Provides-Extra: psycopg2
@@ -42,6 +45,8 @@ Description-Content-Type: text/markdown
 
 # pytest-neon
 
+[![Tests](https://github.com/ZainRizvi/pytest-neon/actions/workflows/tests.yml/badge.svg)](https://github.com/ZainRizvi/pytest-neon/actions/workflows/tests.yml)
+
 Pytest plugin for [Neon](https://neon.tech) database branch isolation in tests.
 
 Each test gets its own isolated database state via Neon's instant branching and reset features. Branches are automatically cleaned up after tests complete.
@@ -112,7 +117,7 @@ pytest
 
 ### `neon_branch` (default, recommended)
 
-The primary fixture for database testing. Creates one branch per test module, then resets it to the parent branch's state after each test. This provides test isolation with ~0.5s overhead per test.
+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.
 
 Returns a `NeonBranch` dataclass with:
 
@@ -134,7 +139,7 @@ def test_branch_info(neon_branch):
     conn = psycopg.connect(neon_branch.connection_string)
 ```
 
-**Performance**: ~1.5s initial setup per module + ~0.5s reset per test. For a module with 10 tests, expect ~6.5s total overhead.
+**Performance**: ~1.5s initial setup per session + ~0.5s reset per test. For 10 tests, expect ~6.5s total overhead.
 
 ### `neon_branch_shared` (fastest, no isolation)
 
@@ -200,22 +205,65 @@ def test_query(neon_engine):
         assert result.scalar() == 1
 ```
 
+### Using Your Own SQLAlchemy Engine
+
+If you have a module-level SQLAlchemy engine (common pattern), 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
+# 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.
+
+This is also a best practice for any cloud database (Neon, RDS, etc.) where connections can be terminated externally.
+
 ## Migrations
 
 pytest-neon supports running migrations once before tests, with all test resets preserving the migrated state.
 
+### Smart Migration Detection
+
+The plugin automatically detects whether migrations actually modified the database schema. This optimization:
+
+- **Saves Neon costs**: No extra branch created when migrations don't change anything
+- **Saves branch slots**: Neon projects have branch limits; this avoids wasting them
+- **Zero configuration**: Works automatically with any migration tool
+
+**When a second branch is created:**
+- Only when `neon_apply_migrations` is overridden AND the schema actually changes
+
+**When only one branch is used:**
+- If you don't override `neon_apply_migrations` (no migrations defined)
+- If your migrations are already applied (schema unchanged)
+
+The detection works by comparing a fingerprint of `information_schema.columns` before and after migrations run.
+
 ### How It Works
 
-When you override the `neon_apply_migrations` fixture, the plugin uses a two-branch architecture:
+When migrations actually modify the schema, the plugin uses a two-branch architecture:
 
 ```
 Parent Branch (your configured parent)
     └── Migration Branch (session-scoped)
             │   ↑ migrations run here ONCE
-            └── Test Branch (module-scoped)
+            └── Test Branch (session-scoped)
                     ↑ resets to migration branch after each test
 ```
 
+When no schema changes occur, the plugin uses a single-branch architecture:
+
+```
+Parent Branch (your configured parent)
+    └── Migration/Test Branch (session-scoped)
+            ↑ resets to parent after each test
+```
+
 This means:
 - Migrations run **once per test session** (not per test or per module)
 - Each test reset restores to the **post-migration state**
@@ -376,11 +424,11 @@ jobs:
 
 ## How It Works
 
-1. Before each test module, the plugin creates a new Neon branch from your parent branch
+1. At the start of the test session, the plugin creates a new Neon branch from your parent branch
 2. `DATABASE_URL` is set to point to the new branch
 3. Tests run against this isolated branch with full access to your schema and data
 4. After each test, the branch is reset to its parent state (~0.5s)
-5. After all tests in the module complete, the branch is deleted
+5. After all tests complete, the branch is deleted
 6. As a safety net, branches auto-expire after 10 minutes even if cleanup fails
 
 Branches use copy-on-write storage, so you only pay for data that differs from the parent branch.
@@ -440,6 +488,18 @@ Set the `NEON_API_KEY` environment variable or use the `--neon-api-key` CLI opti
 
 Set the `NEON_PROJECT_ID` environment variable or use the `--neon-project-id` CLI option.
 
+### "SSL connection has been closed unexpectedly" (SQLAlchemy)
+
+This happens when SQLAlchemy tries to reuse a pooled connection after a branch reset. The reset terminates server-side connections, but SQLAlchemy's pool doesn't know.
+
+**Fix:** Add `pool_pre_ping=True` to your engine:
+
+```python
+engine = create_engine(DATABASE_URL, pool_pre_ping=True)
+```
+
+This makes SQLAlchemy verify connections before using them, automatically discarding stale ones.
+
 ## License
 
 MIT

{pytest_neon-0.5.0 → pytest_neon-0.6.0}/README.md

@@ -1,5 +1,7 @@
 # pytest-neon
 
+[![Tests](https://github.com/ZainRizvi/pytest-neon/actions/workflows/tests.yml/badge.svg)](https://github.com/ZainRizvi/pytest-neon/actions/workflows/tests.yml)
+
 Pytest plugin for [Neon](https://neon.tech) database branch isolation in tests.
 
 Each test gets its own isolated database state via Neon's instant branching and reset features. Branches are automatically cleaned up after tests complete.
@@ -70,7 +72,7 @@ pytest
 
 ### `neon_branch` (default, recommended)
 
-The primary fixture for database testing. Creates one branch per test module, then resets it to the parent branch's state after each test. This provides test isolation with ~0.5s overhead per test.
+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.
 
 Returns a `NeonBranch` dataclass with:
 
@@ -92,7 +94,7 @@ def test_branch_info(neon_branch):
     conn = psycopg.connect(neon_branch.connection_string)
 ```
 
-**Performance**: ~1.5s initial setup per module + ~0.5s reset per test. For a module with 10 tests, expect ~6.5s total overhead.
+**Performance**: ~1.5s initial setup per session + ~0.5s reset per test. For 10 tests, expect ~6.5s total overhead.
 
 ### `neon_branch_shared` (fastest, no isolation)
 
@@ -158,22 +160,65 @@ def test_query(neon_engine):
         assert result.scalar() == 1
 ```
 
+### Using Your Own SQLAlchemy Engine
+
+If you have a module-level SQLAlchemy engine (common pattern), 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
+# 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.
+
+This is also a best practice for any cloud database (Neon, RDS, etc.) where connections can be terminated externally.
+
 ## Migrations
 
 pytest-neon supports running migrations once before tests, with all test resets preserving the migrated state.
 
+### Smart Migration Detection
+
+The plugin automatically detects whether migrations actually modified the database schema. This optimization:
+
+- **Saves Neon costs**: No extra branch created when migrations don't change anything
+- **Saves branch slots**: Neon projects have branch limits; this avoids wasting them
+- **Zero configuration**: Works automatically with any migration tool
+
+**When a second branch is created:**
+- Only when `neon_apply_migrations` is overridden AND the schema actually changes
+
+**When only one branch is used:**
+- If you don't override `neon_apply_migrations` (no migrations defined)
+- If your migrations are already applied (schema unchanged)
+
+The detection works by comparing a fingerprint of `information_schema.columns` before and after migrations run.
+
 ### How It Works
 
-When you override the `neon_apply_migrations` fixture, the plugin uses a two-branch architecture:
+When migrations actually modify the schema, the plugin uses a two-branch architecture:
 
 ```
 Parent Branch (your configured parent)
     └── Migration Branch (session-scoped)
             │   ↑ migrations run here ONCE
-            └── Test Branch (module-scoped)
+            └── Test Branch (session-scoped)
                     ↑ resets to migration branch after each test
 ```
 
+When no schema changes occur, the plugin uses a single-branch architecture:
+
+```
+Parent Branch (your configured parent)
+    └── Migration/Test Branch (session-scoped)
+            ↑ resets to parent after each test
+```
+
 This means:
 - Migrations run **once per test session** (not per test or per module)
 - Each test reset restores to the **post-migration state**
@@ -334,11 +379,11 @@ jobs:
 
 ## How It Works
 
-1. Before each test module, the plugin creates a new Neon branch from your parent branch
+1. At the start of the test session, the plugin creates a new Neon branch from your parent branch
 2. `DATABASE_URL` is set to point to the new branch
 3. Tests run against this isolated branch with full access to your schema and data
 4. After each test, the branch is reset to its parent state (~0.5s)
-5. After all tests in the module complete, the branch is deleted
+5. After all tests complete, the branch is deleted
 6. As a safety net, branches auto-expire after 10 minutes even if cleanup fails
 
 Branches use copy-on-write storage, so you only pay for data that differs from the parent branch.
@@ -398,6 +443,18 @@ Set the `NEON_API_KEY` environment variable or use the `--neon-api-key` CLI opti
 
 Set the `NEON_PROJECT_ID` environment variable or use the `--neon-project-id` CLI option.
 
+### "SSL connection has been closed unexpectedly" (SQLAlchemy)
+
+This happens when SQLAlchemy tries to reuse a pooled connection after a branch reset. The reset terminates server-side connections, but SQLAlchemy's pool doesn't know.
+
+**Fix:** Add `pool_pre_ping=True` to your engine:
+
+```python
+engine = create_engine(DATABASE_URL, pool_pre_ping=True)
+```
+
+This makes SQLAlchemy verify connections before using them, automatically discarding stale ones.
+
 ## License
 
 MIT

{pytest_neon-0.5.0 → pytest_neon-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pytest-neon"
-version = "0.5.0"
+version = "0.6.0"
 description = "Pytest plugin for Neon database branch isolation in tests"
 readme = "README.md"
 license = "MIT"
@@ -42,12 +42,15 @@ dev = [
     "mypy>=1.0",
     "pytest-cov>=4.0",
     "pytest-mock>=3.0",
+    "psycopg2-binary>=2.9",
+    "psycopg[binary]>=3.1",
+    "sqlalchemy>=2.0",
 ]
 
 [project.urls]
-Homepage = "https://github.com/zain/pytest-neon"
-Repository = "https://github.com/zain/pytest-neon"
-Issues = "https://github.com/zain/pytest-neon/issues"
+Homepage = "https://github.com/ZainRizvi/pytest-neon"
+Repository = "https://github.com/ZainRizvi/pytest-neon"
+Issues = "https://github.com/ZainRizvi/pytest-neon/issues"
 
 [project.entry-points.pytest11]
 neon = "pytest_neon.plugin"

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

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

{pytest_neon-0.5.0 → pytest_neon-0.6.0}/src/pytest_neon/plugin.py

@@ -1,7 +1,36 @@
-"""Pytest plugin providing Neon database branch fixtures."""
+"""Pytest plugin providing Neon database branch fixtures.
+
+This plugin provides fixtures for isolated database testing using Neon's
+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_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:
+
+        engine = create_engine(DATABASE_URL, pool_pre_ping=True)
+
+    This is required because branch resets terminate server-side connections.
+    Without pool_pre_ping, SQLAlchemy may try to reuse dead pooled connections,
+    causing "SSL connection has been closed unexpectedly" errors.
+
+Configuration:
+    Set NEON_API_KEY and NEON_PROJECT_ID environment variables, or use
+    --neon-api-key and --neon-project-id CLI options.
+
+For full documentation, see: https://github.com/ZainRizvi/pytest-neon
+"""
 
 from __future__ import annotations
 
+import contextlib
 import os
 import time
 from collections.abc import Generator
@@ -17,6 +46,41 @@ from neon_api.schema import EndpointState
 # Default branch expiry in seconds (10 minutes)
 DEFAULT_BRANCH_EXPIRY_SECONDS = 600
 
+# Sentinel value to detect when neon_apply_migrations was not overridden
+_MIGRATIONS_NOT_DEFINED = object()
+
+
+def _get_schema_fingerprint(connection_string: str) -> tuple[tuple[Any, ...], ...]:
+    """
+    Get a fingerprint of the database schema for change detection.
+
+    Queries information_schema for all tables, columns, and their properties
+    in the public schema. Returns a hashable tuple that can be compared
+    before/after migrations to detect if the schema actually changed.
+
+    This is used to avoid creating unnecessary migration branches when
+    no actual schema changes occurred.
+    """
+    try:
+        import psycopg
+    except ImportError:
+        try:
+            import psycopg2 as psycopg  # type: ignore[import-not-found]
+        except ImportError:
+            # No driver available - can't fingerprint, assume migrations changed things
+            return ()
+
+    with psycopg.connect(connection_string) as conn, conn.cursor() as cur:
+        cur.execute("""
+            SELECT table_name, column_name, data_type, is_nullable,
+                   column_default, ordinal_position
+            FROM information_schema.columns
+            WHERE table_schema = 'public'
+            ORDER BY table_name, ordinal_position
+        """)
+        rows = cur.fetchall()
+    return tuple(tuple(row) for row in rows)
+
 
 @dataclass
 class NeonBranch:
@@ -339,23 +403,47 @@ def _neon_migration_branch(
     Note: The migration branch cannot have an expiry because Neon doesn't
     allow creating child branches from branches with expiration dates.
     Cleanup relies on the fixture teardown at session end.
+
+    Smart Migration Detection:
+        Before yielding, this fixture captures a schema fingerprint and stores
+        it on request.config. After migrations run, _neon_branch_for_reset
+        compares the fingerprint to detect if the schema actually changed.
     """
     # No expiry - Neon doesn't allow children from branches with expiry
-    yield from _create_neon_branch(
+    branch_gen = _create_neon_branch(
         request,
         branch_expiry_override=0,
         branch_name_suffix="-migrated",
     )
+    branch = next(branch_gen)
+
+    # Capture schema fingerprint BEFORE migrations run
+    # This is stored on config so _neon_branch_for_reset can compare after
+    pre_migration_fingerprint = _get_schema_fingerprint(branch.connection_string)
+    request.config._neon_pre_migration_fingerprint = pre_migration_fingerprint  # type: ignore[attr-defined]
+
+    try:
+        yield branch
+    finally:
+        # Clean up by exhausting the generator (triggers branch deletion)
+        with contextlib.suppress(StopIteration):
+            next(branch_gen)
 
 
 @pytest.fixture(scope="session")
-def neon_apply_migrations(_neon_migration_branch: NeonBranch) -> None:
+def neon_apply_migrations(_neon_migration_branch: NeonBranch) -> Any:
     """
     Override this fixture to run migrations on the test database.
 
     The migration branch is already created and DATABASE_URL is set.
     Migrations run once per test session, before any tests execute.
 
+    Smart Migration Detection:
+        The plugin automatically detects whether migrations actually modified
+        the database schema. If no schema changes occurred (or this fixture
+        isn't overridden), the plugin skips creating a separate migration
+        branch, saving Neon costs and branch slots.
+
     Example in conftest.py:
 
         @pytest.fixture(scope="session")
@@ -384,27 +472,69 @@ def neon_apply_migrations(_neon_migration_branch: NeonBranch) -> None:
         _neon_migration_branch: The migration branch with connection details.
             Use _neon_migration_branch.connection_string to connect directly,
             or rely on DATABASE_URL which is already set.
+
+    Returns:
+        Any value (ignored). The default returns a sentinel to indicate
+        the fixture was not overridden.
     """
-    pass  # No-op by default - users override this fixture to run migrations
+    return _MIGRATIONS_NOT_DEFINED
 
 
-@pytest.fixture(scope="module")
+@pytest.fixture(scope="session")
 def _neon_branch_for_reset(
     request: pytest.FixtureRequest,
     _neon_migration_branch: NeonBranch,
-    neon_apply_migrations: None,  # Ensures migrations run first
+    neon_apply_migrations: Any,  # Ensures migrations run first; value for detection
 ) -> Generator[NeonBranch, None, None]:
     """
     Internal fixture that creates a test branch from the migration branch.
 
-    The test branch is created as a child of the migration branch, so resets
-    restore to post-migration state rather than the original parent state.
+    This is session-scoped so DATABASE_URL remains stable throughout the test
+    session, avoiding issues with Python's module caching (e.g., SQLAlchemy
+    engines created at import time would otherwise point to stale branches).
+
+    Smart Migration Detection:
+        This fixture implements a cost-optimization strategy:
+
+        1. If neon_apply_migrations was not overridden (returns sentinel),
+           skip creating a separate test branch - use the migration branch directly.
+
+        2. If neon_apply_migrations was overridden, compare schema fingerprints
+           before/after migrations. Only create a child branch if the schema
+           actually changed.
+
+        This avoids unnecessary Neon costs and branch slots when:
+        - No migration fixture is defined
+        - Migrations exist but are already applied (no schema changes)
     """
-    yield from _create_neon_branch(
-        request,
-        parent_branch_id_override=_neon_migration_branch.branch_id,
-        branch_name_suffix="-test",
-    )
+    # Check if migrations fixture was overridden
+    migrations_defined = neon_apply_migrations is not _MIGRATIONS_NOT_DEFINED
+
+    # Check if schema actually changed (if we have a pre-migration fingerprint)
+    pre_fingerprint = getattr(request.config, "_neon_pre_migration_fingerprint", ())
+    schema_changed = False
+
+    if migrations_defined and pre_fingerprint:
+        # Compare with current schema
+        conn_str = _neon_migration_branch.connection_string
+        post_fingerprint = _get_schema_fingerprint(conn_str)
+        schema_changed = pre_fingerprint != post_fingerprint
+    elif migrations_defined and not pre_fingerprint:
+        # No fingerprint available (no psycopg/psycopg2 installed)
+        # Assume migrations changed something to be safe
+        schema_changed = True
+
+    # Only create a child branch if migrations actually modified the schema
+    if schema_changed:
+        yield from _create_neon_branch(
+            request,
+            parent_branch_id_override=_neon_migration_branch.branch_id,
+            branch_name_suffix="-test",
+        )
+    else:
+        # No schema changes - reuse the migration branch directly
+        # This saves creating an unnecessary branch
+        yield _neon_migration_branch
 
 
 @pytest.fixture(scope="function")
@@ -416,25 +546,35 @@ def neon_branch(
     Provide an isolated Neon database branch for each test.
 
     This is the primary fixture for database testing. It creates one branch per
-    test module, then resets it to the parent branch's state after each test.
+    test session, then resets it to the parent branch's state after each test.
     This provides test isolation with ~0.5s overhead per test.
 
-    The branch is automatically deleted after all tests in the module complete,
-    unless --neon-keep-branches is specified. Branches also auto-expire after
+    The branch is automatically deleted after all tests complete, unless
+    --neon-keep-branches is specified. Branches also auto-expire after
     10 minutes by default (configurable via --neon-branch-expiry) as a safety net
     for interrupted test runs.
 
     The connection string is automatically set in the DATABASE_URL environment
     variable (configurable via --neon-env-var).
 
+    SQLAlchemy Users:
+        If you create your own engine (not using the neon_engine fixture),
+        you MUST use pool_pre_ping=True::
+
+            engine = create_engine(DATABASE_URL, pool_pre_ping=True)
+
+        Branch resets terminate server-side connections. Without pool_pre_ping,
+        SQLAlchemy may reuse dead pooled connections, causing SSL errors.
+
     Requires either:
-    - NEON_API_KEY and NEON_PROJECT_ID environment variables, or
-    - --neon-api-key and --neon-project-id command line options
+        - 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:
+    Example::
+
         def test_database_operation(neon_branch):
             # DATABASE_URL is automatically set
             conn_string = os.environ["DATABASE_URL"]
@@ -602,12 +742,24 @@ def neon_engine(neon_branch: NeonBranch):
     Requires the sqlalchemy optional dependency:
         pip install pytest-neon[sqlalchemy]
 
-    The engine is disposed after each test.
+    The engine is disposed after each test, which handles stale connections
+    after branch resets automatically.
+
+    Note:
+        If you create your own module-level engine instead of using this
+        fixture, you MUST use pool_pre_ping=True::
+
+            engine = create_engine(DATABASE_URL, pool_pre_ping=True)
+
+        This is required because branch resets terminate server-side
+        connections, and without pool_pre_ping SQLAlchemy may reuse dead
+        pooled connections.
 
     Yields:
         SQLAlchemy Engine object
 
-    Example:
+    Example::
+
         def test_query(neon_engine):
             with neon_engine.connect() as conn:
                 result = conn.execute(text("SELECT 1"))

{pytest_neon-0.5.0 → pytest_neon-0.6.0}/tests/test_integration.py

@@ -206,3 +206,68 @@ class TestRealDatabaseConnectivity:
             )
             result = cur.fetchone()
             assert result[0] == "test_value"
+
+
+class TestSQLAlchemyPooledConnections:
+    """Test SQLAlchemy connection pooling behavior with branch resets.
+
+    Branch resets terminate server-side connections. SQLAlchemy's connection
+    pool doesn't know this, so pooled connections become stale.
+
+    Solution: Use pool_pre_ping=True (recommended for any cloud database).
+    This pings connections before use and discards stale ones automatically.
+    """
+
+    def test_pool_pre_ping_handles_stale_connections(self, pytester):
+        """
+        Verify that pool_pre_ping=True handles stale connections after reset.
+
+        Pattern:
+        1. database.py creates engine with pool_pre_ping=True at import time
+        2. test_one uses it, connection goes to pool
+        3. Branch resets after test_one (server terminates connection)
+        4. test_two gets pooled connection, pool_pre_ping detects it's dead,
+           automatically gets fresh connection
+        """
+        pytester.makepyfile(
+            database="""
+import os
+from sqlalchemy import create_engine
+
+DATABASE_URL = os.environ.get("DATABASE_URL")
+# pool_pre_ping=True is REQUIRED for pytest-neon (and recommended for any cloud DB)
+# It verifies connections are alive before using them
+engine = create_engine(DATABASE_URL, pool_pre_ping=True) if DATABASE_URL else None
+"""
+        )
+
+        pytester.makepyfile(
+            test_sqlalchemy_reset="""
+from sqlalchemy import text
+
+def test_first_query(neon_branch):
+    '''First test - creates pooled connection.'''
+    from database import engine
+    with engine.connect() as conn:
+        result = conn.execute(text("SELECT 1"))
+        assert result.scalar() == 1
+    # Connection returned to pool
+
+def test_second_query_after_reset(neon_branch):
+    '''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):
+    '''Third test - still works thanks to pool_pre_ping.'''
+    from database import engine
+    with engine.connect() as conn:
+        result = conn.execute(text("SELECT 3"))
+        assert result.scalar() == 3
+"""
+        )
+
+        result = pytester.runpytest("-v")
+        result.assert_outcomes(passed=3)

pytest_neon-0.6.0/tests/test_migrations.py

@@ -0,0 +1,156 @@
+"""Tests for migration support."""
+
+import inspect
+
+from pytest_neon.plugin import _MIGRATIONS_NOT_DEFINED, neon_apply_migrations
+
+
+class TestSmartMigrationDetection:
+    """Test the sentinel-based detection for skipping unnecessary branches."""
+
+    def test_sentinel_returned_when_migrations_not_overridden(self):
+        """Default neon_apply_migrations returns sentinel to signal no override."""
+        # Get the default implementation's return behavior from source
+        source = inspect.getsource(neon_apply_migrations)
+        assert "_MIGRATIONS_NOT_DEFINED" in source
+
+    def test_sentinel_is_unique_object(self):
+        """Sentinel should be a unique object that won't match normal returns."""
+        assert _MIGRATIONS_NOT_DEFINED is not None
+        assert _MIGRATIONS_NOT_DEFINED is not False
+        assert _MIGRATIONS_NOT_DEFINED != ()
+
+    def test_user_override_does_not_return_sentinel(self, pytester):
+        """When user overrides neon_apply_migrations, it returns None (not sentinel)."""
+        pytester.makeconftest(
+            """
+            import os
+            import pytest
+            from dataclasses import dataclass
+            from pytest_neon.plugin import _MIGRATIONS_NOT_DEFINED
+
+            @dataclass
+            class FakeNeonBranch:
+                branch_id: str
+                project_id: str
+                connection_string: str
+                host: str
+                parent_id: str
+
+            @pytest.fixture(scope="session")
+            def _neon_migration_branch(request):
+                branch = FakeNeonBranch(
+                    branch_id="br-migration",
+                    project_id="proj-test",
+                    connection_string="postgresql://fake",
+                    host="test.neon.tech",
+                    parent_id="br-parent",
+                )
+                os.environ["DATABASE_URL"] = branch.connection_string
+                request.config._neon_pre_migration_fingerprint = ()
+                yield branch
+
+            @pytest.fixture(scope="session")
+            def neon_apply_migrations(_neon_migration_branch):
+                # User override - returns None implicitly, not the sentinel
+                pass
+
+            @pytest.fixture(scope="session")
+            def _neon_branch_for_reset(_neon_migration_branch, neon_apply_migrations):
+                # Verify the detection logic
+                sentinel = _MIGRATIONS_NOT_DEFINED
+                migrations_defined = neon_apply_migrations is not sentinel
+                assert migrations_defined, "User override should NOT return sentinel"
+                yield _neon_migration_branch
+
+            @pytest.fixture(scope="function")
+            def neon_branch(_neon_branch_for_reset):
+                yield _neon_branch_for_reset
+        """
+        )
+
+        pytester.makepyfile(
+            """
+            def test_migration_override_detected(neon_branch):
+                assert neon_branch.branch_id == "br-migration"
+        """
+        )
+
+        result = pytester.runpytest("-v")
+        result.assert_outcomes(passed=1)
+
+
+class TestMigrationFixtureOrder:
+    """Test that migrations run before test branches are created."""
+
+    def test_migrations_run_before_test_branch_created(self, pytester):
+        """Verify neon_apply_migrations is called before test branch exists."""
+        pytester.makeconftest(
+            """
+            import os
+            import pytest
+            from dataclasses import dataclass
+
+            execution_order = []
+
+            @dataclass
+            class FakeNeonBranch:
+                branch_id: str
+                project_id: str
+                connection_string: str
+                host: str
+                parent_id: str
+
+            @pytest.fixture(scope="session")
+            def _neon_migration_branch():
+                execution_order.append("migration_branch_created")
+                branch = FakeNeonBranch(
+                    branch_id="br-migration",
+                    project_id="proj-test",
+                    connection_string="postgresql://migration",
+                    host="test.neon.tech",
+                    parent_id="br-parent",
+                )
+                os.environ["DATABASE_URL"] = branch.connection_string
+                yield branch
+
+            @pytest.fixture(scope="session")
+            def neon_apply_migrations(_neon_migration_branch):
+                execution_order.append("migrations_applied")
+                # User would run migrations here
+
+            @pytest.fixture(scope="module")
+            def _neon_branch_for_reset(_neon_migration_branch, neon_apply_migrations):
+                execution_order.append("test_branch_created")
+                branch = FakeNeonBranch(
+                    branch_id="br-test",
+                    project_id="proj-test",
+                    connection_string="postgresql://test",
+                    host="test.neon.tech",
+                    parent_id=_neon_migration_branch.branch_id,
+                )
+                yield branch
+
+            @pytest.fixture(scope="function")
+            def neon_branch(_neon_branch_for_reset):
+                yield _neon_branch_for_reset
+
+            def pytest_sessionfinish(session, exitstatus):
+                # Verify order: migration branch -> migrations -> test branch
+                assert execution_order == [
+                    "migration_branch_created",
+                    "migrations_applied",
+                    "test_branch_created",
+                ], f"Wrong order: {execution_order}"
+        """
+        )
+
+        pytester.makepyfile(
+            """
+            def test_uses_branch(neon_branch):
+                assert neon_branch.parent_id == "br-migration"
+        """
+        )
+
+        result = pytester.runpytest("-v")
+        result.assert_outcomes(passed=1)

pytest_neon-0.5.0/tests/test_migrations.py

@@ -1,77 +0,0 @@
-"""Tests for migration support."""
-
-
-class TestMigrationFixtureOrder:
-    """Test that migrations run before test branches are created."""
-
-    def test_migrations_run_before_test_branch_created(self, pytester):
-        """Verify neon_apply_migrations is called before test branch exists."""
-        pytester.makeconftest(
-            """
-            import os
-            import pytest
-            from dataclasses import dataclass
-
-            execution_order = []
-
-            @dataclass
-            class FakeNeonBranch:
-                branch_id: str
-                project_id: str
-                connection_string: str
-                host: str
-                parent_id: str
-
-            @pytest.fixture(scope="session")
-            def _neon_migration_branch():
-                execution_order.append("migration_branch_created")
-                branch = FakeNeonBranch(
-                    branch_id="br-migration",
-                    project_id="proj-test",
-                    connection_string="postgresql://migration",
-                    host="test.neon.tech",
-                    parent_id="br-parent",
-                )
-                os.environ["DATABASE_URL"] = branch.connection_string
-                yield branch
-
-            @pytest.fixture(scope="session")
-            def neon_apply_migrations(_neon_migration_branch):
-                execution_order.append("migrations_applied")
-                # User would run migrations here
-
-            @pytest.fixture(scope="module")
-            def _neon_branch_for_reset(_neon_migration_branch, neon_apply_migrations):
-                execution_order.append("test_branch_created")
-                branch = FakeNeonBranch(
-                    branch_id="br-test",
-                    project_id="proj-test",
-                    connection_string="postgresql://test",
-                    host="test.neon.tech",
-                    parent_id=_neon_migration_branch.branch_id,
-                )
-                yield branch
-
-            @pytest.fixture(scope="function")
-            def neon_branch(_neon_branch_for_reset):
-                yield _neon_branch_for_reset
-
-            def pytest_sessionfinish(session, exitstatus):
-                # Verify order: migration branch -> migrations -> test branch
-                assert execution_order == [
-                    "migration_branch_created",
-                    "migrations_applied",
-                    "test_branch_created",
-                ], f"Wrong order: {execution_order}"
-        """
-        )
-
-        pytester.makepyfile(
-            """
-            def test_uses_branch(neon_branch):
-                assert neon_branch.parent_id == "br-migration"
-        """
-        )
-
-        result = pytester.runpytest("-v")
-        result.assert_outcomes(passed=1)