PHPackages                             emaadali/pest-neondb-plugin - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. emaadali/pest-neondb-plugin

ActiveLibrary[Framework](/categories/framework)

emaadali/pest-neondb-plugin
===========================

Pest plugin for isolating Laravel parallel tests with Neon database branches.

v0.1.30(1mo ago)010↑2900%[1 PRs](https://github.com/emaadali/pest-neondb-plugin/pulls)MITPHPPHP ^8.3CI passing

Since Jun 17Pushed 1mo agoCompare

[ Source](https://github.com/emaadali/pest-neondb-plugin)[ Packagist](https://packagist.org/packages/emaadali/pest-neondb-plugin)[ Fund](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=66BYDWAT92N6L)[ GitHub Sponsors](https://github.com/nunomaduro)[ RSS](/packages/emaadali-pest-neondb-plugin/feed)WikiDiscussions 4.x Synced 1mo ago

READMEChangelogDependencies (7)Versions (33)Used By (0)

Pest Database Isolation Plugin
==============================

[](#pest-database-isolation-plugin)

Laravel-focused Pest plugin for isolating concurrent test runs and parallel test workers with Neon branches or local Postgres databases.

Installation
------------

[](#installation)

```
composer require --dev emaadali/pest-database-isolation-plugin
```

Usage
-----

[](#usage)

In `tests/Pest.php`:

```
use function Emaadali\PestDatabaseIsolation\usesDatabaseTestingIsolation;

usesDatabaseTestingIsolation();
```

The plugin also exposes a stable run id for isolating other test artifacts created during the same Pest command:

```
use function Emaadali\PestDatabaseIsolation\testRunId;

pest()->browser()->screenshots(
    dirname(__DIR__).'/tests/Browser/Screenshots/'.testRunId()
);
```

The run id is stored in `PEST_TEST_RUN_ID` and is shared with Laravel parallel test workers.

The plugin auto-selects a driver. If your `DB_URL`, `DATABASE_URL`, or `DB_HOST` contains `neon.tech`, it uses the `neon` driver. Otherwise it uses the `pgsql` driver.

You can configure the driver explicitly:

```
PEST_TEST_DATABASE_DRIVER=neon
# or
PEST_TEST_DATABASE_DRIVER=pgsql
```

Neon Driver
-----------

[](#neon-driver)

Configure Neon:

```
NEON_API_KEY=...
NEON_PROJECT_ID=...
NEON_PARENT_BRANCH_ID=...
NEON_TEST_BRANCH_TTL_SECONDS=21600
```

The root test branch is created once per Pest run and deleted when the parent test process exits. Laravel parallel workers automatically create expiring child branches from that root branch and point the worker database connection at the child branch.

When the `neon` driver is selected but `NEON_API_KEY`, `NEON_PROJECT_ID`, or `NEON_PARENT_BRANCH_ID` is missing, the plugin throws an exception instead of silently falling back.

Postgres Driver
---------------

[](#postgres-driver)

The `pgsql` driver creates a unique database per test run and worker, such as:

```
app_pest_ab12cd34_test_1
app_pest_ab12cd34_test_2

```

Laravel's `RefreshDatabase` trait then runs `migrate:fresh` against that worker database normally. The plugin drops the worker database on shutdown.

Because this driver creates and drops databases, it only operates on a local Postgres host (`localhost`, `127.0.0.1`, `::1`, or a Unix socket). Pointing it at a remote host throws an exception.

The plugin connects to the `postgres` maintenance database to create and drop worker databases. Set `PEST_TEST_PGSQL_ADMIN_DATABASE` to use a different one:

```
PEST_TEST_PGSQL_ADMIN_DATABASE=template1
```

Worktree databases
------------------

[](#worktree-databases)

The package ships a `vendor/bin/setup-worktree-database` binary for giving each git worktree its own isolated local Postgres database. It reads the connection details from the worktree's `.env`, creates a database named `_wt_` (worktree name from `CURSOR_WORKTREE_NAME`, falling back to the directory name), and rewrites `.env` to point at it.

Call it from your worktree setup, after `composer install` and before migrating:

```
cp "$ROOT_WORKTREE_PATH/.env" .env
composer install
vendor/bin/setup-worktree-database
php artisan migrate
```

The database is created empty (migrate it yourself), recreated fresh on each run, and—like the `pgsql` test driver—only operates on a local Postgres host.

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance91

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

32

Last Release

47d ago

Major Versions

v0.1.30 → 4.x-dev2026-06-17

### Community

Maintainers

![](https://www.gravatar.com/avatar/4ffa4cdf0b83948b1b33a89b67d6ff2e8295b86e2855b94e34acac878224c946?d=identicon)[parallel-oss](/maintainers/parallel-oss)

---

Top Contributors

[![emaadali](https://avatars.githubusercontent.com/u/3521616?v=4)](https://github.com/emaadali "emaadali (40 commits)")

---

Tags

phpplugintestingunitframeworktestpest

### Embed Badge

![Health badge](/badges/emaadali-pest-neondb-plugin/health.svg)

```
[![Health](https://phpackages.com/badges/emaadali-pest-neondb-plugin/health.svg)](https://phpackages.com/packages/emaadali-pest-neondb-plugin)
```

###  Alternatives

[pestphp/pest

The elegant PHP Testing Framework.

11.6k77.3M23.3k](/packages/pestphp-pest)[defstudio/pest-plugin-laravel-expectations

A plugin to add laravel tailored expectations to Pest

99617.0k8](/packages/defstudio-pest-plugin-laravel-expectations)[pestphp/pest-plugin-browser

Pest plugin to test browser interactions

1344.6M241](/packages/pestphp-pest-plugin-browser)[pestphp/pest-plugin-arch

The Arch plugin for Pest PHP.

4463.1M6.1k](/packages/pestphp-pest-plugin-arch)[pestphp/pest-plugin-stressless

Stressless plugin for Pest

681.1M18](/packages/pestphp-pest-plugin-stressless)[pestphp/pest-plugin-profanity

The Pest Profanity Plugin

10622.1M73](/packages/pestphp-pest-plugin-profanity)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)