lbyit/laravel-db-pull

Safely pull remote databases to local environments via SSH tunnels.

v0.6.0 2026-02-10 11:03 UTC

Requires

• php: ^8.2
• ext-pcntl: *
• ext-posix: *
• illuminate/console: ^12.0
• illuminate/process: ^12.0
• illuminate/support: ^12.0

Suggests

• ext-ssh2: Optional. Allows for advanced SSH operations if native binaries are restricted.
• mysql-client: Required. The 'mysql' and 'mysqldump' binaries must be installed on the local system.
• openssh-client: Required if using SSH tunnels to access remote databases.

MIT

• LBY IT

README

A safe and efficient tool to pull remote databases (Production/Staging) into your local Laravel development environment via SSH tunnels.

Note: This package currently supports MySQL/MariaDB only.

Requirements

System Binaries

The following binaries must be installed on your local system and available in your PATH:

• mysql-client (mysql & mysqldump): Required for import/export.

• openssh-client (ssh): Required for connecting via tunnel.

PHP Environment

• PHP 8.2+

• Laravel 12.0+

• PHP Extensions: ext-pcntl, ext-posix.

Installation

composer require lbyit/laravel-db-pull

Configuration Management

The package provides a full suite for managing your remote environments without requiring manual edits to configuration files.

Add a Remote

Starts an interactive wizard that scans your SSH keys, analyzes remote tables, and writes the configuration to your .env and config/db-pull.php.

php artisan db:pull-add

Edit a Remote

Updates an existing configuration. Ideal for re-running table analysis after database changes or adjusting filters.

php artisan db:pull-edit {remote?}

Remove a Remote

Cleanly deletes an environment's configuration from both .env and config/db-pull.php.

php artisan db:pull-remove {remote?}

Usage

To pull the database from a configured environment:

php artisan db:pull production

Safety Features

• Database Wipe: Automatically runs db:wipe locally before import to prevent foreign key constraint conflicts.

• Environment Guard: Commands only execute in local, development, or testing environments.

• Confirmation Prompt: Prevents accidental overwriting of local data.

Advanced Configuration

In config/db-pull.php, you can control the behavior per table:

• exclude_data: Imports only the structure, not the data (ideal for logs or sessions).

• filters: Allows SQL Where statements (e.g., only import the last 3 months).

'options' => [
    'exclude_data' => ['activity_log', 'sessions'],
    'filters' => [
        'orders' => 'created_at >= DATE_SUB(NOW(), INTERVAL 3 MONTH)',
    ],
],

Troubleshooting

mysql: command not found (Remote)

If the connection is established but mysql is not found on the remote server (common in Docker/Alpine), add a symlink in the target system's Dockerfile:

RUN ln -s /usr/bin/mysql /usr/local/bin/mysql &&\
    ln -s /usr/bin/mysqldump /usr/local/bin/mysqldump

Plugin caching_sha2_password could not be loaded

If connecting from an Alpine client to a MySQL 8+ server, install the MariaDB connector:

RUN apk add --no-cache mariadb-connector-c

Access Denied (172.21.0.1)

If the remote DB is running in Docker, the DB user must have permissions for the Docker network's gateway IP (usually 172.x.x.1 or %).

Credits

Made with ♥ by LBY IT