pytest-neon 0.5.1__py3-none-any.whl → 0.6.0__py3-none-any.whl

pytest_neon/__init__.py

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

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.1.dist-info → pytest_neon-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-neon
-Version: 0.5.1
+Version: 0.6.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
@@ -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.6.0.dist-info/RECORD

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

pytest_neon-0.5.1.dist-info/RECORD

@@ -1,8 +0,0 @@
-pytest_neon/__init__.py,sha256=YQt1LLTbNLiq4kChmiPEmOD5aTsqhCgpRpxK80VAY7Y,398
-pytest_neon/plugin.py,sha256=1TukuxsBQ88NlgQS6qosUarIrCc94apMrwvVrYt9IOg,23241
-pytest_neon/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pytest_neon-0.5.1.dist-info/METADATA,sha256=i1h6TFZWjG0QY2h_UZsYzz5e9AaQewfCXKIXi_JC00E,13547
-pytest_neon-0.5.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-pytest_neon-0.5.1.dist-info/entry_points.txt,sha256=5U88Idj_G8-PSDb9VF3OwYFbGLHnGOo_GxgYvi0dtXw,37
-pytest_neon-0.5.1.dist-info/licenses/LICENSE,sha256=aKKp_Ex4WBHTByY4BhXJ181dzB_qYhi2pCUmZ7Spn_0,1067
-pytest_neon-0.5.1.dist-info/RECORD,,