pytest-neon 2.3.2__py3-none-any.whl → 3.0.1__py3-none-any.whl

pytest_neon/plugin.py

@@ -1,15 +1,10 @@
 """Pytest plugin providing Neon database branch fixtures.
 
-This plugin provides fixtures for database testing using Neon's instant
-branching feature. Multiple isolation levels are available:
+This plugin provides a simple fixture for database testing using Neon's instant
+branching feature. All tests share a single branch per session.
 
-Main fixtures:
-    neon_branch_readonly: True read-only access via read_only endpoint (enforced)
-    neon_branch_dirty: Session-scoped read-write, shared state across all tests
-    neon_branch_isolated: Per-worker branch with reset after each test (recommended)
-    neon_branch_readwrite: Deprecated, use neon_branch_isolated instead
-    neon_branch: Deprecated alias for neon_branch_isolated
-    neon_branch_shared: Shared branch without reset (module-scoped)
+Main fixture:
+    neon_branch: Session-scoped shared branch for all tests
 
 Connection fixtures (require extras):
     neon_connection: psycopg2 connection (requires psycopg2 extra)
@@ -18,32 +13,35 @@ Connection fixtures (require extras):
 
 Architecture:
     Parent Branch (configured or project default)
-        └── Migration Branch (session-scoped, read_write endpoint)
-                │   ↑ migrations run here ONCE
-                │
-                ├── Read-only Endpoint (read_only endpoint ON migration branch)
-                │       ↑ neon_branch_readonly uses this
-                │
-                ├── Dirty Branch (session-scoped child, shared across ALL workers)
-                │       ↑ neon_branch_dirty uses this
-                │
-                └── Isolated Branch (one per xdist worker, lazily created)
-                        ↑ neon_branch_isolated uses this, reset after each test
-
-SQLAlchemy Users:
-    If you create your own SQLAlchemy engine (not using neon_engine fixture),
-    you MUST use pool_pre_ping=True when using neon_branch_isolated:
-
-        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.
+        └── Test Branch (session-scoped, 10-min expiry)
+                ↑ migrations run here ONCE, all tests share this
 
 Configuration:
     Set NEON_API_KEY and NEON_PROJECT_ID environment variables, or use
     --neon-api-key and --neon-project-id CLI options.
 
+Test Isolation:
+    Since all tests share the same branch, tests that modify data will see
+    each other's changes. For test isolation, use one of these patterns:
+
+    1. Transaction rollback:
+        @pytest.fixture
+        def db_transaction(neon_branch):
+            import psycopg
+            conn = psycopg.connect(neon_branch.connection_string)
+            conn.execute("BEGIN")
+            yield conn
+            conn.execute("ROLLBACK")
+            conn.close()
+
+    2. Table truncation:
+        @pytest.fixture(autouse=True)
+        def clean_tables(neon_branch):
+            yield
+            with psycopg.connect(neon_branch.connection_string) as conn:
+                conn.execute("TRUNCATE users, orders CASCADE")
+                conn.commit()
+
 For full documentation, see: https://github.com/ZainRizvi/pytest-neon
 """
 
@@ -80,9 +78,6 @@ _RATE_LIMIT_MAX_TOTAL_DELAY = 90.0  # 1.5 minutes total cap
 _RATE_LIMIT_JITTER_FACTOR = 0.25  # +/- 25% jitter
 _RATE_LIMIT_MAX_ATTEMPTS = 10  # Maximum number of retry attempts
 
-# Sentinel value to detect when neon_apply_migrations was not overridden
-_MIGRATIONS_NOT_DEFINED = object()
-
 
 class NeonRateLimitError(Exception):
     """Raised when Neon API rate limit is exceeded and retries are exhausted."""
@@ -245,8 +240,8 @@ def _get_xdist_worker_id() -> str:
     Get the pytest-xdist worker ID, or "main" if not running under xdist.
 
     When running tests in parallel with pytest-xdist, each worker process
-    gets a unique ID (gw0, gw1, gw2, etc.). This is used to create separate
-    branches per worker to avoid database state pollution between parallel tests.
+    gets a unique ID (gw0, gw1, gw2, etc.). This is used to coordinate
+    branch creation and migrations across workers.
     """
     return os.environ.get("PYTEST_XDIST_WORKER", "main")
 
@@ -295,17 +290,6 @@ def _get_git_branch_name() -> str | None:
     return None
 
 
-def _extract_password_from_connection_string(connection_string: str) -> str:
-    """Extract password from a PostgreSQL connection string."""
-    # Format: postgresql://user:password@host/db?params
-    from urllib.parse import urlparse
-
-    parsed = urlparse(connection_string)
-    if parsed.password:
-        return parsed.password
-    raise ValueError(f"No password found in connection string: {connection_string}")
-
-
 def _reveal_role_password(
     api_key: str, project_id: str, branch_id: str, role_name: str
 ) -> str:
@@ -337,38 +321,6 @@ def _reveal_role_password(
     return data["password"]
 
 
-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:
     """Information about a Neon test branch."""
@@ -479,7 +431,7 @@ class NeonBranchManager:
         Create a new Neon branch with a read_write endpoint.
 
         Args:
-            name_suffix: Suffix to add to branch name (e.g., "-migration", "-dirty")
+            name_suffix: Suffix to add to branch name (e.g., "-test")
             parent_branch_id: Parent branch ID (defaults to config's parent)
             expiry_seconds: Branch expiry in seconds (0 or None for no expiry)
 
@@ -552,53 +504,6 @@ class NeonBranchManager:
             endpoint_id=endpoint_id,
         )
 
-    def create_readonly_endpoint(self, branch: NeonBranch) -> NeonBranch:
-        """
-        Create a read_only endpoint on an existing branch.
-
-        This creates a true read-only endpoint that enforces no writes at the
-        database level.
-
-        Args:
-            branch: The branch to create the endpoint on
-
-        Returns:
-            NeonBranch with the read_only endpoint's connection details
-        """
-        result = _retry_on_rate_limit(
-            lambda: self._neon.endpoint_create(
-                project_id=self.config.project_id,
-                endpoint={
-                    "branch_id": branch.branch_id,
-                    "type": "read_only",
-                },
-            ),
-            operation_name="endpoint_create_readonly",
-        )
-
-        endpoint_id = result.endpoint.id
-        host = self._wait_for_endpoint(endpoint_id)
-
-        # Reuse the password from the parent branch's connection string.
-        # DO NOT call role_password_reset here - it would invalidate the
-        # password used by the parent branch's read_write endpoint, breaking
-        # any existing connections (especially in xdist where other workers
-        # may be using the cached connection string).
-        password = _extract_password_from_connection_string(branch.connection_string)
-        connection_string = (
-            f"postgresql://{self.config.role_name}:{password}@{host}/"
-            f"{self.config.database_name}?sslmode=require"
-        )
-
-        return NeonBranch(
-            branch_id=branch.branch_id,
-            project_id=self.config.project_id,
-            connection_string=connection_string,
-            host=host,
-            parent_id=branch.parent_id,
-            endpoint_id=endpoint_id,
-        )
-
     def delete_branch(self, branch_id: str) -> None:
         """Delete a branch (silently ignores errors)."""
         if self.config.keep_branches:
@@ -614,28 +519,6 @@ class NeonBranchManager:
             msg = f"Failed to delete Neon branch {branch_id}: {e}"
             warnings.warn(msg, stacklevel=2)
 
-    def delete_endpoint(self, endpoint_id: str) -> None:
-        """Delete an endpoint (silently ignores errors)."""
-        try:
-            _retry_on_rate_limit(
-                lambda: self._neon.endpoint_delete(
-                    project_id=self.config.project_id, endpoint_id=endpoint_id
-                ),
-                operation_name="endpoint_delete",
-            )
-        except Exception as e:
-            warnings.warn(
-                f"Failed to delete Neon endpoint {endpoint_id}: {e}", stacklevel=2
-            )
-
-    def reset_branch(self, branch: NeonBranch) -> None:
-        """Reset a branch to its parent's state."""
-        if not branch.parent_id:
-            msg = f"Branch {branch.branch_id} has no parent - cannot reset"
-            raise RuntimeError(msg)
-
-        _reset_branch_to_parent(branch, self.config.api_key)
-
     def _wait_for_endpoint(self, endpoint_id: str, max_wait_seconds: float = 60) -> str:
         """Wait for endpoint to become active and return its host."""
         poll_interval = 0.5
@@ -688,12 +571,13 @@ class XdistCoordinator:
     Coordinates branch sharing across pytest-xdist workers.
 
     Uses file locks and JSON cache files to ensure only one worker creates
-    shared resources (like the migration branch), while others reuse them.
+    shared resources (like the test branch), while others reuse them.
     """
 
     def __init__(self, tmp_path_factory: pytest.TempPathFactory):
         self.worker_id = _get_xdist_worker_id()
         self.is_xdist = self.worker_id != "main"
+        self._worker_count: int | None = None
 
         if self.is_xdist:
             root_tmp_dir = tmp_path_factory.getbasetemp().parent
@@ -701,6 +585,21 @@ class XdistCoordinator:
         else:
             self._lock_dir = None
 
+    def _get_worker_count(self) -> int:
+        """Get the total number of xdist workers."""
+        if self._worker_count is not None:
+            return self._worker_count
+
+        # PYTEST_XDIST_WORKER_COUNT is set by xdist
+        count_str = os.environ.get("PYTEST_XDIST_WORKER_COUNT")
+        if count_str:
+            self._worker_count = int(count_str)
+        else:
+            # Fallback: count from worker ID pattern (gw0, gw1, etc.)
+            # This shouldn't happen in normal xdist runs
+            self._worker_count = 1
+        return self._worker_count
+
     def coordinate_resource(
         self,
         resource_name: str,
@@ -759,6 +658,53 @@ class XdistCoordinator:
         signal_file = self._lock_dir / f"neon_{signal_name}"
         signal_file.write_text("done")
 
+    def signal_worker_done(self) -> None:
+        """Signal that this worker has completed all tests."""
+        if not self.is_xdist or self._lock_dir is None:
+            return
+
+        done_file = self._lock_dir / f"neon_worker_done_{self.worker_id}"
+        done_file.write_text("done")
+
+    def wait_for_all_workers_done(self, timeout: float = 300) -> None:
+        """
+        Wait for all xdist workers to signal completion.
+
+        This ensures the branch isn't deleted while other workers are still
+        running tests.
+
+        Args:
+            timeout: Maximum time to wait in seconds (default: 5 minutes)
+        """
+        if not self.is_xdist or self._lock_dir is None:
+            return
+
+        worker_count = self._get_worker_count()
+        waited = 0.0
+        poll_interval = 0.5
+
+        while waited < timeout:
+            done_count = 0
+            for i in range(worker_count):
+                done_file = self._lock_dir / f"neon_worker_done_gw{i}"
+                if done_file.exists():
+                    done_count += 1
+
+            if done_count >= worker_count:
+                return
+
+            time.sleep(poll_interval)
+            waited += poll_interval
+
+        # Timeout - log warning but proceed with cleanup anyway
+        # This prevents infinite hangs if a worker crashes
+        warnings.warn(
+            f"Timeout waiting for all workers to complete after {timeout}s. "
+            f"Only {done_count}/{worker_count} workers signaled completion. "
+            f"Proceeding with branch cleanup.",
+            stacklevel=2,
+        )
+
 
 class EnvironmentManager:
     """Manages DATABASE_URL environment variable lifecycle."""
@@ -802,8 +748,7 @@ def _get_default_branch_id(neon: NeonAPI, project_id: str) -> str | None:
     Get the default/primary branch ID for a project.
 
     This is used as a safety check to ensure we never accidentally
-    perform destructive operations (like password reset) on the
-    production branch.
+    perform destructive operations on the production branch.
 
     Returns:
         The branch ID of the default branch, or None if not found.
@@ -932,447 +877,6 @@ def _get_config_value(
     return default
 
 
-def _create_neon_branch(
-    request: pytest.FixtureRequest,
-    parent_branch_id_override: str | None = None,
-    branch_expiry_override: int | None = None,
-    branch_name_suffix: str = "",
-) -> Generator[NeonBranch, None, None]:
-    """
-    Internal helper that creates and manages a Neon branch lifecycle.
-
-    This is the core implementation used by branch fixtures.
-
-    Args:
-        request: Pytest fixture request
-        parent_branch_id_override: If provided, use this as parent instead of config
-        branch_expiry_override: If provided, use this expiry instead of config
-        branch_name_suffix: Optional suffix for branch name (e.g., "-migrated", "-test")
-    """
-    config = request.config
-
-    api_key = _get_config_value(config, "neon_api_key", "NEON_API_KEY", "neon_api_key")
-    project_id = _get_config_value(
-        config, "neon_project_id", "NEON_PROJECT_ID", "neon_project_id"
-    )
-    # Use override if provided, otherwise read from config
-    parent_branch_id = parent_branch_id_override or _get_config_value(
-        config, "neon_parent_branch", "NEON_PARENT_BRANCH_ID", "neon_parent_branch"
-    )
-    database_name = _get_config_value(
-        config, "neon_database", "NEON_DATABASE", "neon_database", "neondb"
-    )
-    role_name = _get_config_value(
-        config, "neon_role", "NEON_ROLE", "neon_role", "neondb_owner"
-    )
-
-    # For boolean/int options, check CLI first, then ini
-    keep_branches = config.getoption("neon_keep_branches", default=None)
-    if keep_branches is None:
-        keep_branches = config.getini("neon_keep_branches")
-
-    # Use override if provided, otherwise read from config
-    if branch_expiry_override is not None:
-        branch_expiry = branch_expiry_override
-    else:
-        branch_expiry = config.getoption("neon_branch_expiry", default=None)
-        if branch_expiry is None:
-            branch_expiry = int(config.getini("neon_branch_expiry"))
-
-    env_var_name = _get_config_value(
-        config, "neon_env_var", "", "neon_env_var", "DATABASE_URL"
-    )
-
-    if not api_key:
-        pytest.skip(
-            "Neon API key not configured (set NEON_API_KEY or use --neon-api-key)"
-        )
-    if not project_id:
-        pytest.skip(
-            "Neon project ID not configured "
-            "(set NEON_PROJECT_ID or use --neon-project-id)"
-        )
-
-    neon = NeonAPI(api_key=api_key)
-
-    # Cache the default branch ID for safety checks (only fetch once per session)
-    if not hasattr(config, "_neon_default_branch_id"):
-        config._neon_default_branch_id = _get_default_branch_id(neon, project_id)  # type: ignore[attr-defined]
-
-    # Generate unique branch name
-    # Format: pytest-[git branch (first 15 chars)]-[random]-[suffix]
-    # This helps identify orphaned branches by showing which git branch created them
-    random_suffix = os.urandom(2).hex()  # 2 bytes = 4 hex chars
-    git_branch = _get_git_branch_name()
-    if git_branch:
-        # Truncate git branch to 15 chars to keep branch names reasonable
-        git_prefix = git_branch[:15]
-        branch_name = f"pytest-{git_prefix}-{random_suffix}{branch_name_suffix}"
-    else:
-        branch_name = f"pytest-{random_suffix}{branch_name_suffix}"
-
-    # Build branch creation payload
-    branch_config: dict[str, Any] = {"name": branch_name}
-    if parent_branch_id:
-        branch_config["parent_id"] = parent_branch_id
-
-    # Set branch expiration (auto-delete) as a safety net for interrupted test runs
-    # This uses the branch expires_at field, not endpoint suspend_timeout
-    if branch_expiry and branch_expiry > 0:
-        expires_at = datetime.now(timezone.utc) + timedelta(seconds=branch_expiry)
-        branch_config["expires_at"] = expires_at.strftime("%Y-%m-%dT%H:%M:%SZ")
-
-    # Create branch with compute endpoint
-    # Wrap in retry logic to handle rate limits
-    # See: https://api-docs.neon.tech/reference/api-rate-limiting
-    result = _retry_on_rate_limit(
-        lambda: neon.branch_create(
-            project_id=project_id,
-            branch=branch_config,
-            endpoints=[{"type": "read_write"}],
-        ),
-        operation_name="branch_create",
-    )
-
-    branch = result.branch
-
-    # Get endpoint_id from operations
-    # (branch_create returns operations, not endpoints directly)
-    endpoint_id = None
-    for op in result.operations:
-        if op.endpoint_id:
-            endpoint_id = op.endpoint_id
-            break
-
-    if not endpoint_id:
-        raise RuntimeError(f"No endpoint created for branch {branch.id}")
-
-    # Wait for endpoint to be ready (it starts in "init" state)
-    # Endpoints typically become active in 1-2 seconds, but we allow up to 60s
-    # to handle occasional Neon API slowness or high load scenarios
-    max_wait_seconds = 60
-    poll_interval = 0.5  # Poll every 500ms for responsive feedback
-    waited = 0.0
-
-    while True:
-        # Wrap in retry logic to handle rate limits during polling
-        # See: https://api-docs.neon.tech/reference/api-rate-limiting
-        endpoint_response = _retry_on_rate_limit(
-            lambda: neon.endpoint(project_id=project_id, endpoint_id=endpoint_id),
-            operation_name="endpoint_status",
-        )
-        endpoint = endpoint_response.endpoint
-        state = endpoint.current_state
-
-        if state == EndpointState.active:
-            break
-
-        if waited >= max_wait_seconds:
-            raise RuntimeError(
-                f"Timeout waiting for endpoint {endpoint_id} to become active "
-                f"(current state: {state})"
-            )
-
-        time.sleep(poll_interval)
-        waited += poll_interval
-
-    host = endpoint.host
-
-    # Get password using reveal (not reset) to avoid invalidating existing connections
-    # See: https://api-docs.neon.tech/reference/getprojectbranchrolepassword
-    password = _retry_on_rate_limit(
-        lambda: _reveal_role_password(
-            api_key=api_key,
-            project_id=project_id,
-            branch_id=branch.id,
-            role_name=role_name,
-        ),
-        operation_name="role_password_reveal",
-    )
-
-    # Build connection string
-    connection_string = (
-        f"postgresql://{role_name}:{password}@{host}/{database_name}?sslmode=require"
-    )
-
-    neon_branch_info = NeonBranch(
-        branch_id=branch.id,
-        project_id=project_id,
-        connection_string=connection_string,
-        host=host,
-        parent_id=branch.parent_id,
-        endpoint_id=endpoint_id,
-    )
-
-    # Set DATABASE_URL (or configured env var) for the duration of the fixture scope
-    original_env_value = os.environ.get(env_var_name)
-    os.environ[env_var_name] = connection_string
-
-    try:
-        yield neon_branch_info
-    finally:
-        # Restore original env var
-        if original_env_value is None:
-            os.environ.pop(env_var_name, None)
-        else:
-            os.environ[env_var_name] = original_env_value
-
-        # Cleanup: delete branch unless --neon-keep-branches was specified
-        if not keep_branches:
-            try:
-                # Wrap in retry logic to handle rate limits
-                # See: https://api-docs.neon.tech/reference/api-rate-limiting
-                _retry_on_rate_limit(
-                    lambda: neon.branch_delete(
-                        project_id=project_id, branch_id=branch.id
-                    ),
-                    operation_name="branch_delete",
-                )
-            except Exception as e:
-                # Log but don't fail tests due to cleanup issues
-                warnings.warn(
-                    f"Failed to delete Neon branch {branch.id}: {e}",
-                    stacklevel=2,
-                )
-
-
-def _create_readonly_endpoint(
-    branch: NeonBranch,
-    api_key: str,
-    database_name: str,
-    role_name: str,
-) -> NeonBranch:
-    """
-    Create a read_only endpoint on an existing branch.
-
-    Returns a new NeonBranch object with the read_only endpoint's connection string.
-    The read_only endpoint enforces that no writes can be made through this connection.
-
-    Args:
-        branch: The branch to create a read_only endpoint on
-        api_key: Neon API key
-        database_name: Database name for connection string
-        role_name: Role name for connection string
-
-    Returns:
-        NeonBranch with read_only endpoint connection details
-    """
-    neon = NeonAPI(api_key=api_key)
-
-    # Create read_only endpoint on the branch
-    # See: https://api-docs.neon.tech/reference/createprojectendpoint
-    result = _retry_on_rate_limit(
-        lambda: neon.endpoint_create(
-            project_id=branch.project_id,
-            endpoint={
-                "branch_id": branch.branch_id,
-                "type": "read_only",
-            },
-        ),
-        operation_name="endpoint_create_readonly",
-    )
-
-    endpoint = result.endpoint
-    endpoint_id = endpoint.id
-
-    # Wait for endpoint to be ready
-    max_wait_seconds = 60
-    poll_interval = 0.5
-    waited = 0.0
-
-    while True:
-        endpoint_response = _retry_on_rate_limit(
-            lambda: neon.endpoint(
-                project_id=branch.project_id, endpoint_id=endpoint_id
-            ),
-            operation_name="endpoint_status_readonly",
-        )
-        endpoint = endpoint_response.endpoint
-        state = endpoint.current_state
-
-        if state == EndpointState.active:
-            break
-
-        if waited >= max_wait_seconds:
-            raise RuntimeError(
-                f"Timeout waiting for read_only endpoint {endpoint_id} "
-                f"to become active (current state: {state})"
-            )
-
-        time.sleep(poll_interval)
-        waited += poll_interval
-
-    host = endpoint.host
-
-    # Reuse the password from the parent branch's connection string.
-    # DO NOT call role_password_reset here - it would invalidate the
-    # password used by the parent branch's read_write endpoint.
-    password = _extract_password_from_connection_string(branch.connection_string)
-
-    # Build connection string for the read_only endpoint
-    connection_string = (
-        f"postgresql://{role_name}:{password}@{host}/{database_name}?sslmode=require"
-    )
-
-    return NeonBranch(
-        branch_id=branch.branch_id,
-        project_id=branch.project_id,
-        connection_string=connection_string,
-        host=host,
-        parent_id=branch.parent_id,
-        endpoint_id=endpoint_id,
-    )
-
-
-def _delete_endpoint(project_id: str, endpoint_id: str, api_key: str) -> None:
-    """Delete a Neon endpoint."""
-    neon = NeonAPI(api_key=api_key)
-    try:
-        _retry_on_rate_limit(
-            lambda: neon.endpoint_delete(
-                project_id=project_id, endpoint_id=endpoint_id
-            ),
-            operation_name="endpoint_delete",
-        )
-    except Exception as e:
-        warnings.warn(
-            f"Failed to delete Neon endpoint {endpoint_id}: {e}",
-            stacklevel=2,
-        )
-
-
-def _reset_branch_to_parent(branch: NeonBranch, api_key: str) -> None:
-    """Reset a branch to its parent's state using the Neon API.
-
-    Uses exponential backoff retry logic with jitter to handle rate limit (429)
-    errors. After initiating the restore, polls the operation status until it
-    completes.
-
-    See: https://api-docs.neon.tech/reference/api-rate-limiting
-
-    Args:
-        branch: The branch to reset
-        api_key: Neon API key
-    """
-    if not branch.parent_id:
-        raise RuntimeError(f"Branch {branch.branch_id} has no parent - cannot reset")
-
-    base_url = "https://console.neon.tech/api/v2"
-    project_id = branch.project_id
-    branch_id = branch.branch_id
-    restore_url = f"{base_url}/projects/{project_id}/branches/{branch_id}/restore"
-    headers = {
-        "Authorization": f"Bearer {api_key}",
-        "Content-Type": "application/json",
-    }
-
-    def do_restore() -> dict[str, Any]:
-        response = requests.post(
-            restore_url,
-            headers=headers,
-            json={"source_branch_id": branch.parent_id},
-            timeout=30,
-        )
-        response.raise_for_status()
-        return response.json()
-
-    # Wrap in retry logic to handle rate limits
-    # See: https://api-docs.neon.tech/reference/api-rate-limiting
-    data = _retry_on_rate_limit(do_restore, operation_name="branch_restore")
-    operations = data.get("operations", [])
-
-    # The restore API returns operations that run asynchronously.
-    # We must wait for operations to complete before the next test
-    # starts, otherwise connections may fail during the restore.
-    if operations:
-        _wait_for_operations(
-            project_id=branch.project_id,
-            operations=operations,
-            headers=headers,
-            base_url=base_url,
-        )
-
-
-def _wait_for_operations(
-    project_id: str,
-    operations: list[dict[str, Any]],
-    headers: dict[str, str],
-    base_url: str,
-    max_wait_seconds: float = 60,
-    poll_interval: float = 0.5,
-) -> None:
-    """Wait for Neon operations to complete.
-
-    Handles rate limit (429) errors with exponential backoff retry.
-    See: https://api-docs.neon.tech/reference/api-rate-limiting
-
-    Args:
-        project_id: The Neon project ID
-        operations: List of operation dicts from the API response
-        headers: HTTP headers including auth
-        base_url: Base URL for Neon API
-        max_wait_seconds: Maximum time to wait (default: 60s)
-        poll_interval: Time between polls (default: 0.5s)
-    """
-    # Get operation IDs that aren't already finished
-    pending_op_ids = [
-        op["id"] for op in operations if op.get("status") not in ("finished", "skipped")
-    ]
-
-    if not pending_op_ids:
-        return  # All operations already complete
-
-    waited = 0.0
-    first_poll = True
-    while pending_op_ids and waited < max_wait_seconds:
-        # Poll immediately first time (operation usually completes instantly),
-        # then wait between subsequent polls
-        if first_poll:
-            time.sleep(0.1)  # Tiny delay to let operation start
-            waited += 0.1
-            first_poll = False
-        else:
-            time.sleep(poll_interval)
-            waited += poll_interval
-
-        # Check status of each pending operation
-        still_pending = []
-        for op_id in pending_op_ids:
-            op_url = f"{base_url}/projects/{project_id}/operations/{op_id}"
-
-            def get_operation_status(url: str = op_url) -> dict[str, Any]:
-                """Fetch operation status. Default arg captures url by value."""
-                response = requests.get(url, headers=headers, timeout=10)
-                response.raise_for_status()
-                return response.json()
-
-            try:
-                # Wrap in retry logic to handle rate limits
-                # See: https://api-docs.neon.tech/reference/api-rate-limiting
-                result = _retry_on_rate_limit(
-                    get_operation_status,
-                    operation_name=f"operation_status({op_id})",
-                )
-                op_data = result.get("operation", {})
-                status = op_data.get("status")
-
-                if status == "failed":
-                    err = op_data.get("error", "unknown error")
-                    raise RuntimeError(f"Operation {op_id} failed: {err}")
-                if status not in ("finished", "skipped", "cancelled"):
-                    still_pending.append(op_id)
-            except requests.RequestException:
-                # On network error (non-429), assume still pending and retry
-                still_pending.append(op_id)
-
-        pending_op_ids = still_pending
-
-    if pending_op_ids:
-        raise RuntimeError(
-            f"Timeout waiting for operations to complete: {pending_op_ids}"
-        )
-
-
 def _branch_to_dict(branch: NeonBranch) -> dict[str, Any]:
     """Convert NeonBranch to a JSON-serializable dict."""
     return asdict(branch)
@@ -1418,301 +922,120 @@ def _neon_xdist_coordinator(
 
 
 @pytest.fixture(scope="session")
-def _neon_migration_branch(
-    request: pytest.FixtureRequest,
+def _neon_test_branch(
     _neon_config: NeonConfig,
     _neon_branch_manager: NeonBranchManager,
     _neon_xdist_coordinator: XdistCoordinator,
-) -> Generator[NeonBranch, None, None]:
+) -> Generator[tuple[NeonBranch, bool], None, None]:
     """
-    Session-scoped branch where migrations are applied.
+    Internal: Create test branch, coordinated across workers.
 
-    This branch is ALWAYS created from the configured parent and serves as
-    the parent for all test branches (dirty, isolated, readonly endpoint).
-    Migrations run once per session on this branch.
+    This creates a single branch with expiry that all tests share.
+    The first worker creates the branch, others reuse it.
 
-    pytest-xdist Support:
-        When running with pytest-xdist, the first worker to acquire the lock
-        creates the migration branch. Other workers wait for migrations to
-        complete, then reuse the same branch. This avoids redundant API calls
-        and ensures migrations only run once. Only the creator cleans up the
-        branch at session end.
-
-    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.
+    Branch cleanup is coordinated so the creator waits for ALL workers
+    to complete before deleting the branch, preventing connection errors
+    for workers that finish later.
+
+    Yields:
+        Tuple of (branch, is_creator) where is_creator indicates if this
+        worker created the branch (and should run migrations/cleanup).
     """
     env_manager = EnvironmentManager(_neon_config.env_var_name)
-    branch: NeonBranch
-    is_creator: bool
 
-    def create_migration_branch() -> dict[str, Any]:
+    def create_branch() -> dict[str, Any]:
         b = _neon_branch_manager.create_branch(
-            name_suffix="-migration",
-            expiry_seconds=0,  # No expiry - child branches need this
+            name_suffix="-test",
+            expiry_seconds=_neon_config.branch_expiry,
         )
         return {"branch": _branch_to_dict(b)}
 
-    # Coordinate branch creation across xdist workers
     data, is_creator = _neon_xdist_coordinator.coordinate_resource(
-        "migration_branch", create_migration_branch
+        "test_branch", create_branch
     )
     branch = _dict_to_branch(data["branch"])
-
-    # Store creator status for other fixtures
-    request.config._neon_is_migration_creator = is_creator  # type: ignore[attr-defined]
-
-    # Set DATABASE_URL
     env_manager.set(branch.connection_string)
 
-    # Non-creators wait for migrations to complete
-    if not is_creator:
-        _neon_xdist_coordinator.wait_for_signal(
-            "migrations_done", timeout=_MIGRATION_WAIT_TIMEOUT
-        )
-
     try:
-        yield branch
+        yield branch, is_creator
     finally:
         env_manager.restore()
-        # Only creator cleans up
+        # Signal that this worker is done with all tests
+        _neon_xdist_coordinator.signal_worker_done()
+
         if is_creator:
+            # Wait for all other workers to finish before deleting the branch
+            # This prevents "endpoint not found" errors for slower workers
+            _neon_xdist_coordinator.wait_for_all_workers_done()
             _neon_branch_manager.delete_branch(branch.branch_id)
 
 
 @pytest.fixture(scope="session")
-def neon_apply_migrations(_neon_migration_branch: NeonBranch) -> Any:
+def neon_apply_migrations(_neon_test_branch: tuple[NeonBranch, bool]) -> Any:
     """
     Override this fixture to run migrations on the test database.
 
-    The migration branch is already created and DATABASE_URL is set.
+    The test branch is already created and DATABASE_URL is set.
     Migrations run once per test session, before any tests execute.
 
     pytest-xdist Support:
         When running with pytest-xdist, migrations only run on the first
-        worker (the one that created the migration branch). Other workers
+        worker (the one that created the test branch). Other workers
         wait for migrations to complete before proceeding. This ensures
         migrations run exactly once, even with parallel workers.
 
-    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")
-        def neon_apply_migrations(_neon_migration_branch):
+        def neon_apply_migrations(_neon_test_branch):
             import subprocess
             subprocess.run(["alembic", "upgrade", "head"], check=True)
 
     Or with Django:
 
         @pytest.fixture(scope="session")
-        def neon_apply_migrations(_neon_migration_branch):
+        def neon_apply_migrations(_neon_test_branch):
             from django.core.management import call_command
             call_command("migrate", "--noinput")
 
     Or with raw SQL:
 
         @pytest.fixture(scope="session")
-        def neon_apply_migrations(_neon_migration_branch):
+        def neon_apply_migrations(_neon_test_branch):
             import psycopg
-            with psycopg.connect(_neon_migration_branch.connection_string) as conn:
+            branch, is_creator = _neon_test_branch
+            with psycopg.connect(branch.connection_string) as conn:
                 with open("schema.sql") as f:
                     conn.execute(f.read())
                 conn.commit()
 
     Args:
-        _neon_migration_branch: The migration branch with connection details.
-            Use _neon_migration_branch.connection_string to connect directly,
+        _neon_test_branch: Tuple of (NeonBranch, is_creator).
+            Use _neon_test_branch[0].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.
+        Any value (ignored). The default returns None.
     """
-    return _MIGRATIONS_NOT_DEFINED
+    return None
 
 
 @pytest.fixture(scope="session")
-def _neon_migrations_synchronized(
-    request: pytest.FixtureRequest,
-    _neon_migration_branch: NeonBranch,
+def neon_branch(
+    _neon_test_branch: tuple[NeonBranch, bool],
     _neon_xdist_coordinator: XdistCoordinator,
     neon_apply_migrations: Any,
-) -> Any:
-    """
-    Internal fixture that synchronizes migrations across xdist workers.
-
-    This fixture ensures that:
-    1. Only the creator worker runs migrations (non-creators wait in
-       _neon_migration_branch BEFORE neon_apply_migrations runs)
-    2. Creator signals completion after migrations finish
-    3. The return value from neon_apply_migrations is preserved for detection
-
-    Without xdist, this is a simple passthrough.
-    """
-    is_creator = getattr(request.config, "_neon_is_migration_creator", True)
-
-    if is_creator:
-        # Creator: migrations just ran via neon_apply_migrations dependency
-        # Signal completion to other workers
-        _neon_xdist_coordinator.send_signal("migrations_done")
-
-    return neon_apply_migrations
-
-
-@pytest.fixture(scope="session")
-def _neon_dirty_branch(
-    _neon_config: NeonConfig,
-    _neon_branch_manager: NeonBranchManager,
-    _neon_xdist_coordinator: XdistCoordinator,
-    _neon_migration_branch: NeonBranch,
-    _neon_migrations_synchronized: Any,  # Ensures migrations complete first
-) -> Generator[NeonBranch, None, None]:
-    """
-    Session-scoped dirty branch shared across ALL xdist workers.
-
-    This branch is a child of the migration branch. All tests using
-    neon_branch_dirty share this single branch - writes persist and
-    are visible to all tests (even across workers).
-
-    This is the "dirty" branch because:
-    - No reset between tests
-    - Shared across all workers (concurrent writes possible)
-    - Fast because no per-test overhead
-    """
-    env_manager = EnvironmentManager(_neon_config.env_var_name)
-    branch: NeonBranch
-    is_creator: bool
-
-    def create_dirty_branch() -> dict[str, Any]:
-        b = _neon_branch_manager.create_branch(
-            name_suffix="-dirty",
-            parent_branch_id=_neon_migration_branch.branch_id,
-            expiry_seconds=_neon_config.branch_expiry,
-        )
-        return {"branch": _branch_to_dict(b)}
-
-    # Coordinate dirty branch creation - shared across ALL workers
-    data, is_creator = _neon_xdist_coordinator.coordinate_resource(
-        "dirty_branch", create_dirty_branch
-    )
-    branch = _dict_to_branch(data["branch"])
-
-    # Set DATABASE_URL
-    env_manager.set(branch.connection_string)
-
-    try:
-        yield branch
-    finally:
-        env_manager.restore()
-        # Only creator cleans up
-        if is_creator:
-            _neon_branch_manager.delete_branch(branch.branch_id)
-
-
-@pytest.fixture(scope="session")
-def _neon_readonly_endpoint(
-    _neon_config: NeonConfig,
-    _neon_branch_manager: NeonBranchManager,
-    _neon_xdist_coordinator: XdistCoordinator,
-    _neon_migration_branch: NeonBranch,
-    _neon_migrations_synchronized: Any,  # Ensures migrations complete first
-) -> Generator[NeonBranch, None, None]:
-    """
-    Session-scoped read_only endpoint on the migration branch.
-
-    This is a true read-only endpoint - writes are blocked at the database
-    level. All workers share this endpoint since it's read-only anyway.
-    """
-    env_manager = EnvironmentManager(_neon_config.env_var_name)
-    branch: NeonBranch
-    is_creator: bool
-
-    def create_readonly_endpoint() -> dict[str, Any]:
-        b = _neon_branch_manager.create_readonly_endpoint(_neon_migration_branch)
-        return {"branch": _branch_to_dict(b)}
-
-    # Coordinate endpoint creation - shared across ALL workers
-    data, is_creator = _neon_xdist_coordinator.coordinate_resource(
-        "readonly_endpoint", create_readonly_endpoint
-    )
-    branch = _dict_to_branch(data["branch"])
-
-    # Set DATABASE_URL
-    env_manager.set(branch.connection_string)
-
-    try:
-        yield branch
-    finally:
-        env_manager.restore()
-        # Only creator cleans up the endpoint
-        if is_creator and branch.endpoint_id:
-            _neon_branch_manager.delete_endpoint(branch.endpoint_id)
-
-
-@pytest.fixture(scope="session")
-def _neon_isolated_branch(
-    request: pytest.FixtureRequest,
-    _neon_config: NeonConfig,
-    _neon_branch_manager: NeonBranchManager,
-    _neon_xdist_coordinator: XdistCoordinator,
-    _neon_migration_branch: NeonBranch,
-    _neon_migrations_synchronized: Any,  # Ensures migrations complete first
-) -> Generator[NeonBranch, None, None]:
-    """
-    Session-scoped isolated branch, one per xdist worker.
-
-    Each worker gets its own branch. Unlike the dirty branch, this is
-    per-worker to allow reset operations without affecting other workers.
-
-    The branch is reset after each test that uses neon_branch_isolated.
-    """
-    env_manager = EnvironmentManager(_neon_config.env_var_name)
-    worker_id = _neon_xdist_coordinator.worker_id
-
-    # Each worker creates its own isolated branch - no coordination needed
-    # because each worker has a unique ID
-    branch = _neon_branch_manager.create_branch(
-        name_suffix=f"-isolated-{worker_id}",
-        parent_branch_id=_neon_migration_branch.branch_id,
-        expiry_seconds=_neon_config.branch_expiry,
-    )
-
-    # Store branch manager on config for reset operations
-    request.config._neon_isolated_branch_manager = _neon_branch_manager  # type: ignore[attr-defined]
-
-    # Set DATABASE_URL
-    env_manager.set(branch.connection_string)
-
-    try:
-        yield branch
-    finally:
-        env_manager.restore()
-        _neon_branch_manager.delete_branch(branch.branch_id)
-
-
-@pytest.fixture(scope="session")
-def neon_branch_readonly(
-    _neon_config: NeonConfig,
-    _neon_readonly_endpoint: NeonBranch,
 ) -> NeonBranch:
     """
-    Provide a true read-only Neon database connection.
+    Provide a shared Neon database branch for all tests.
 
-    This fixture uses a read_only endpoint on the migration branch, which
-    enforces read-only access at the database level. Any attempt to write
-    will result in a database error.
+    This is a session-scoped branch that all tests share. Migrations run
+    once before tests start, then all tests see the same database state.
 
-    This is the recommended fixture for tests that only read data (SELECT queries).
-    It's session-scoped and shared across all tests and workers since it's read-only.
-
-    Use this fixture when your tests only perform SELECT queries.
-    For tests that INSERT, UPDATE, or DELETE data, use ``neon_branch_dirty``
-    (for shared state) or ``neon_branch_isolated`` (for test isolation).
+    Since all tests share the branch:
+    - Data written by one test IS visible to subsequent tests
+    - Use transaction rollback or cleanup fixtures for test isolation
+    - Tests run in parallel (xdist) share the same branch
 
     The connection string is automatically set in the DATABASE_URL environment
     variable (configurable via --neon-env-var).
@@ -1726,242 +1049,44 @@ def neon_branch_readonly(
 
     Example::
 
-        def test_query_users(neon_branch_readonly):
+        def test_query_users(neon_branch):
             # DATABASE_URL is automatically set
-            conn_string = os.environ["DATABASE_URL"]
-
-            # Read-only query
-            with psycopg.connect(conn_string) as conn:
+            import psycopg
+            with psycopg.connect(neon_branch.connection_string) as conn:
                 result = conn.execute("SELECT * FROM users").fetchall()
-                assert len(result) > 0
-
-            # This would fail with a database error:
-            # conn.execute("INSERT INTO users (name) VALUES ('test')")
-    """
-    # DATABASE_URL is already set by _neon_readonly_endpoint
-    return _neon_readonly_endpoint
-
-
-@pytest.fixture(scope="session")
-def neon_branch_dirty(
-    _neon_config: NeonConfig,
-    _neon_dirty_branch: NeonBranch,
-) -> NeonBranch:
-    """
-    Provide a session-scoped Neon database branch for read-write access.
-
-    All tests share the same branch and writes persist across tests (no cleanup
-    between tests). This is faster than neon_branch_isolated because there's no
-    reset overhead.
-
-    Use this fixture when:
-    - Most tests can share database state without interference
-    - You want maximum performance with minimal API calls
-    - You manually manage test data cleanup if needed
-    - You're using it alongside ``neon_branch_isolated`` for specific tests
-      that need guaranteed clean state
-
-    The connection string is automatically set in the DATABASE_URL environment
-    variable (configurable via --neon-env-var).
+                assert len(result) >= 0
 
-    Warning:
-        Data written by one test WILL be visible to subsequent tests AND to
-        other xdist workers. This is truly shared - use ``neon_branch_isolated``
-        for tests that require guaranteed clean state.
+    For test isolation, use a transaction fixture::
 
-    pytest-xdist:
-        ALL workers share the same dirty branch. Concurrent writes from different
-        workers may conflict. This is "dirty" by design - for isolation, use
-        ``neon_branch_isolated``.
-
-    Requires either:
-        - NEON_API_KEY and NEON_PROJECT_ID environment variables, or
-        - --neon-api-key and --neon-project-id command line options
-
-    Returns:
-        NeonBranch: Object with branch_id, project_id, connection_string, and host.
-
-    Example::
-
-        def test_insert_user(neon_branch_dirty):
-            # DATABASE_URL is automatically set
+        @pytest.fixture
+        def db_transaction(neon_branch):
             import psycopg
-            with psycopg.connect(neon_branch_dirty.connection_string) as conn:
-                conn.execute("INSERT INTO users (name) VALUES ('test')")
-                conn.commit()
-            # Data persists - next test will see this user
-
-        def test_count_users(neon_branch_dirty):
-            # This test sees data from previous tests
-            import psycopg
-            with psycopg.connect(neon_branch_dirty.connection_string) as conn:
-                result = conn.execute("SELECT COUNT(*) FROM users").fetchone()
-                # Count includes users from previous tests
-    """
-    # DATABASE_URL is already set by _neon_dirty_branch
-    return _neon_dirty_branch
-
-
-@pytest.fixture(scope="function")
-def neon_branch_isolated(
-    request: pytest.FixtureRequest,
-    _neon_config: NeonConfig,
-    _neon_isolated_branch: NeonBranch,
-) -> Generator[NeonBranch, None, None]:
+            conn = psycopg.connect(neon_branch.connection_string)
+            conn.execute("BEGIN")
+            yield conn
+            conn.execute("ROLLBACK")
+            conn.close()
+
+        def test_with_isolation(db_transaction):
+            db_transaction.execute("INSERT INTO users (name) VALUES ('test')")
+            # Rolled back after test - next test won't see this
     """
-    Provide an isolated Neon database branch with reset after each test.
-
-    This is the recommended fixture for tests that modify database state and
-    need isolation. Each xdist worker has its own branch, and the branch is
-    reset to the migration state after each test.
-
-    Use this fixture when:
-    - Tests modify database state (INSERT, UPDATE, DELETE)
-    - You need test isolation (each test starts with clean state)
-    - You're using it alongside ``neon_branch_dirty`` for specific tests
-
-    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.
-
-    pytest-xdist:
-        Each worker has its own isolated branch. Resets only affect that worker's
-        branch, so workers don't interfere with each other.
-
-    Requires either:
-        - NEON_API_KEY and NEON_PROJECT_ID environment variables, or
-        - --neon-api-key and --neon-project-id command line options
+    branch, is_creator = _neon_test_branch
 
-    Yields:
-        NeonBranch: Object with branch_id, project_id, connection_string, and host.
-
-    Example::
-
-        def test_insert_user(neon_branch_isolated):
-            # DATABASE_URL is automatically set
-            conn_string = os.environ["DATABASE_URL"]
-
-            # 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()
-            # Next test starts with clean state
-    """
-    # DATABASE_URL is already set by _neon_isolated_branch
-    yield _neon_isolated_branch
-
-    # Reset branch to migration state after each test
-    branch_manager = getattr(request.config, "_neon_isolated_branch_manager", None)
-    if branch_manager is not None:
-        try:
-            branch_manager.reset_branch(_neon_isolated_branch)
-        except Exception as e:
-            pytest.fail(
-                f"\n\nFailed to reset branch {_neon_isolated_branch.branch_id} "
-                f"after test. Subsequent tests may see dirty state.\n\n"
-                f"Error: {e}\n\n"
-                f"To keep the branch for debugging, use --neon-keep-branches"
-            )
-
-
-@pytest.fixture(scope="function")
-def neon_branch_readwrite(
-    neon_branch_isolated: NeonBranch,
-) -> Generator[NeonBranch, None, None]:
-    """
-    Deprecated: Use ``neon_branch_isolated`` instead.
-
-    This fixture is now an alias for ``neon_branch_isolated``.
-
-    .. deprecated:: 2.3.0
-        Use ``neon_branch_isolated`` for tests that modify data with reset,
-        ``neon_branch_dirty`` for shared state, or ``neon_branch_readonly``
-        for read-only access.
-    """
-    warnings.warn(
-        "neon_branch_readwrite is deprecated. Use neon_branch_isolated (for tests "
-        "that modify data with isolation) or neon_branch_dirty (for shared state).",
-        DeprecationWarning,
-        stacklevel=2,
-    )
-    yield neon_branch_isolated
-
-
-@pytest.fixture(scope="function")
-def neon_branch(
-    neon_branch_isolated: NeonBranch,
-) -> Generator[NeonBranch, None, None]:
-    """
-    Deprecated: Use ``neon_branch_isolated``, ``neon_branch_dirty``, or
-    ``neon_branch_readonly`` instead.
-
-    This fixture is now an alias for ``neon_branch_isolated``.
-
-    .. deprecated:: 1.1.0
-        Use ``neon_branch_isolated`` for tests that modify data with reset,
-        ``neon_branch_dirty`` for shared state, or ``neon_branch_readonly``
-        for read-only access.
-    """
-    warnings.warn(
-        "neon_branch is deprecated. Use neon_branch_isolated (for tests that "
-        "modify data), neon_branch_dirty (for shared state), or "
-        "neon_branch_readonly (for read-only tests).",
-        DeprecationWarning,
-        stacklevel=2,
-    )
-    yield neon_branch_isolated
-
-
-@pytest.fixture(scope="module")
-def neon_branch_shared(
-    request: pytest.FixtureRequest,
-    _neon_migration_branch: NeonBranch,
-    _neon_migrations_synchronized: Any,  # Ensures migrations complete first
-) -> Generator[NeonBranch, None, None]:
-    """
-    Provide a shared Neon database branch for all tests in a module.
-
-    This fixture 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.
-
-    If you override the `neon_apply_migrations` fixture, migrations will run
-    once before the first test, and this branch will include the migrated schema.
-
-    Use this when:
-    - Tests are read-only or don't interfere with each other
-    - You manually clean up test data within each test
-    - Maximum speed is more important than isolation
-
-    Warning: Tests in the same module will share database state. Data created
-    by one test will be visible to subsequent tests. Use `neon_branch` instead
-    if you need isolation between tests.
-
-    Yields:
-        NeonBranch: Object with branch_id, project_id, connection_string, and host.
+    if is_creator:
+        # Creator runs migrations (via dependency), then signals completion
+        _neon_xdist_coordinator.send_signal("migrations_done")
+    else:
+        # Non-creators wait for migrations to complete
+        _neon_xdist_coordinator.wait_for_signal(
+            "migrations_done", timeout=_MIGRATION_WAIT_TIMEOUT
+        )
 
-    Example:
-        def test_read_only_query(neon_branch_shared):
-            # Fast: no reset between tests, but be careful about data leakage
-            conn_string = neon_branch_shared.connection_string
-    """
-    yield from _create_neon_branch(
-        request,
-        parent_branch_id_override=_neon_migration_branch.branch_id,
-        branch_name_suffix="-shared",
-    )
+    return branch
 
 
 @pytest.fixture
-def neon_connection(neon_branch_isolated: NeonBranch):
+def neon_connection(neon_branch: NeonBranch):
     """
     Provide a psycopg2 connection to the test branch.
 
@@ -1969,7 +1094,6 @@ def neon_connection(neon_branch_isolated: NeonBranch):
         pip install pytest-neon[psycopg2]
 
     The connection is rolled back and closed after each test.
-    Uses neon_branch_isolated for test isolation.
 
     Yields:
         psycopg2 connection object
@@ -1991,22 +1115,22 @@ def neon_connection(neon_branch_isolated: NeonBranch):
             "  The 'neon_connection' fixture requires psycopg2.\n\n"
             "  To fix this, install the psycopg2 extra:\n\n"
             "      pip install pytest-neon[psycopg2]\n\n"
-            "  Or use the 'neon_branch_isolated' fixture with your own driver:\n\n"
-            "      def test_example(neon_branch_isolated):\n"
+            "  Or use the 'neon_branch' fixture with your own driver:\n\n"
+            "      def test_example(neon_branch):\n"
             "          import your_driver\n"
             "          conn = your_driver.connect(\n"
-            "              neon_branch_isolated.connection_string)\n\n"
+            "              neon_branch.connection_string)\n\n"
             "═══════════════════════════════════════════════════════════════════\n"
         )
 
-    conn = psycopg2.connect(neon_branch_isolated.connection_string)
+    conn = psycopg2.connect(neon_branch.connection_string)
     yield conn
     conn.rollback()
     conn.close()
 
 
 @pytest.fixture
-def neon_connection_psycopg(neon_branch_isolated: NeonBranch):
+def neon_connection_psycopg(neon_branch: NeonBranch):
     """
     Provide a psycopg (v3) connection to the test branch.
 
@@ -2014,7 +1138,6 @@ def neon_connection_psycopg(neon_branch_isolated: NeonBranch):
         pip install pytest-neon[psycopg]
 
     The connection is rolled back and closed after each test.
-    Uses neon_branch_isolated for test isolation.
 
     Yields:
         psycopg connection object
@@ -2036,40 +1159,29 @@ def neon_connection_psycopg(neon_branch_isolated: NeonBranch):
             "  The 'neon_connection_psycopg' fixture requires psycopg v3.\n\n"
             "  To fix this, install the psycopg extra:\n\n"
             "      pip install pytest-neon[psycopg]\n\n"
-            "  Or use the 'neon_branch_isolated' fixture with your own driver:\n\n"
-            "      def test_example(neon_branch_isolated):\n"
+            "  Or use the 'neon_branch' fixture with your own driver:\n\n"
+            "      def test_example(neon_branch):\n"
             "          import your_driver\n"
             "          conn = your_driver.connect(\n"
-            "              neon_branch_isolated.connection_string)\n\n"
+            "              neon_branch.connection_string)\n\n"
             "═══════════════════════════════════════════════════════════════════\n"
         )
 
-    conn = psycopg.connect(neon_branch_isolated.connection_string)
+    conn = psycopg.connect(neon_branch.connection_string)
     yield conn
     conn.rollback()
     conn.close()
 
 
 @pytest.fixture
-def neon_engine(neon_branch_isolated: NeonBranch):
+def neon_engine(neon_branch: NeonBranch):
     """
     Provide a SQLAlchemy engine connected to the test branch.
 
     Requires the sqlalchemy optional dependency:
         pip install pytest-neon[sqlalchemy]
 
-    The engine is disposed after each test, which handles stale connections
-    after branch resets automatically. Uses neon_branch_isolated for test isolation.
-
-    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.
+    The engine is disposed after each test.
 
     Yields:
         SQLAlchemy Engine object
@@ -2091,14 +1203,14 @@ def neon_engine(neon_branch_isolated: NeonBranch):
             "  The 'neon_engine' fixture requires SQLAlchemy.\n\n"
             "  To fix this, install the sqlalchemy extra:\n\n"
             "      pip install pytest-neon[sqlalchemy]\n\n"
-            "  Or use the 'neon_branch_isolated' fixture with your own driver:\n\n"
-            "      def test_example(neon_branch_isolated):\n"
+            "  Or use the 'neon_branch' fixture with your own driver:\n\n"
+            "      def test_example(neon_branch):\n"
             "          from sqlalchemy import create_engine\n"
             "          engine = create_engine(\n"
-            "              neon_branch_isolated.connection_string)\n\n"
+            "              neon_branch.connection_string)\n\n"
             "═══════════════════════════════════════════════════════════════════\n"
         )
 
-    engine = create_engine(neon_branch_isolated.connection_string)
+    engine = create_engine(neon_branch.connection_string)
     yield engine
     engine.dispose()