Download the PHP package phattarachai/laravel-db-tunnel without Composer

Laravel DB Tunnel

Reach remote databases (production, UAT, QAS) from your local Laravel app through SSH, so their ports never have to be open to the internet.

The main use case is giving Laravel Boost read-only claude-* connections, so an AI agent can investigate real data on remote environments. It also handles an app whose own database lives behind a tunnel.

• Machine-wide port allocation. Every project on your machine gets its own stable local port. db:tunnel install picks one that no other project, ~/.ssh/config LocalForward or running process holds.
• Opens on first use. In local, resolving a tunneled connection opens its tunnel automatically. Boost's database-query just works.
• Uses the SSH login you already have. The tunnel is ssh -f -N -L 127.0.0.1:<port>:127.0.0.1:<remote> <alias> over your existing Host alias. You don't need a per-tunnel alias.
• Supervised mode for an app's primary database: db:tunnel watch re-dials dropped and stalled connections inside composer dev.
• Ships a Laravel Boost skill, so the agent in every project that installs this knows how to use it.

Requirements

• PHP 8.3+, Laravel 12 or 13
• macOS, Linux or WSL2 with OpenSSH
• lsof (macOS) or ss (Linux/WSL2), to see which process listens on a port
• SSH key access to the database host. Tunnels run with BatchMode=yes, so they never prompt.

Installation

With Laravel Boost installed, run php artisan boost:update (or boost:install) and select this package to get its agent skill.

Quick start: a read-only production connection for Boost

1. Add a connection in config/database.php. The port is machine-specific, so it has no default. Neither does the password.

2. Describe the tunnel in config/db-tunnel.php, keyed by the same connection name:

3. Allocate a port:

4. Query. DB::connection('claude-prod'), php artisan db:show --database=claude-prod, or Boost's database-query with database: claude-prod all open the tunnel on first use. Check with php artisan db:tunnel status.

How it works

Ports

The local end of each tunnel is the connection's own port. That keeps config/database.php as the single source of truth, which matters because tools such as the Boost MCP server read it once at boot.

db:tunnel install picks the port once and keeps it stable. It considers a port taken when any of these hold it:

• another project in the machine registry, ~/.config/db-tunnel/ports.json (or $XDG_CONFIG_HOME/db-tunnel)
• a LocalForward in ~/.ssh/config, including Included files, under a different alias
• a process listening on it right now

Install then decides in this order:

1. It reuses the port already registered for this project and connection.
2. Otherwise it adopts the current .env port, if that port is inside port_range (default 15440–15999) and free.
3. Otherwise it takes the first free port in the range.

If a registered port has since been taken by someone else, install moves the connection to a fresh port. Pin a port with --port=15444.

.env.example gets an empty <ENV>_DB_PORT=, because each machine allocates its own.

Opening and closing

open runs:

It then waits until the port is actually listening. If the alias already declares a LocalForward for that port, -L is left out and plain ssh -f -N <alias> is used, so dedicated tunnel aliases keep working.

ControlMaster=no and ControlPath=none keep the tunnel out of SSH connection multiplexing. Without them, an alias with ControlMaster auto and a live master connection would hand the -L forward to that master process and exit, so the port would be held by ssh: … [mux] instead of a tunnel db:tunnel recognises. The tunnel always gets its own connection, whatever the alias sets; your interactive ssh <alias> sessions keep multiplexing as before.

Tunnel state comes from the process that listens on the port (lsof/ss), not from a connect probe. A connect probe such as nc -z reports ports open on WSL2 that nothing is listening on. The listener check tells three cases apart:

• the tunnel is open: an ssh process to the right alias listens on the port
• the tunnel is closed: nothing listens
• the port is held by something else, e.g. a local Postgres

close kills only an ssh listener to the right alias.

Auto-open

When db-tunnel.auto_open is null (the default), tunnels open automatically in APP_ENV=local. The package registers a connection resolver for each tunneled connection. That resolver opens the tunnel, if needed, the moment Laravel resolves the connection. A failure throws a TunnelException that carries ssh's own error message.

Set 'auto_open' => false on a tunnel, or DB_TUNNEL_AUTO_OPEN=false, to turn this off.

The app's own database behind a tunnel

When the default connection itself goes through SSH, supervise the tunnel inside composer dev rather than detaching it. Also set 'auto_open' => false on that tunnel.

watch does the following:

• dials in the foreground
• kills a dial that hasn't forwarded within watch.establish_timeout (90s), which covers networks whose SSH handshake stalls
• re-dials after the connection drops
• idles when another tunnel already serves the port
• takes its ssh down on SIGINT/SIGTERM

Anything network-specific, such as bringing a VPN up first, stays in the project's own dev script.

A read-only role on the server

The claude-* role should only ever SELECT. Tunnelled connections arrive from the server's own loopback.

PostgreSQL:

MySQL / MariaDB:

Keep the password in .env only. Never put it in an env() default in committed config.

Configuration

If the alias is missing from ~/.ssh/config, open and install print a login block to add:

Testing

Changelog

See the Releases page.

License

The MIT License (MIT). See LICENSE.md.