README

A powerful, interactive CLI tool for Laravel developers to securely pull remote databases into local environments via SSH tunnels. Designed for Laravel 12+, it features a modern interactive wizard and granular control over table data. No need for manual sync anymore, this tool covers up:

Syncrhonize / Pull databases from different remotes
Multi-DB-Support for local environment
Secure configuration
Extendable by follow-up-commands
Additional rules per table possible (skip, structure-only, manual filter data)

Features

Interactive Wizard: Powered by Laravel Prompts for a seamless setup experience.
SSH Tunneling: Securely connect to remote databases without exposing ports.
Table Management:
- Full Skip: Exclude tables entirely (no structure, no data).
- Structure Only: Import table definitions without any data.
- Data Filtering: Use SQL WHERE clauses to import only partial data (e.g., last 3 months of logs).
Environment Aware: Automatically manages .env variables and configuration files.
Safety First: Environment guards prevent accidental overwrites in production.

Installation

composer require lbyit/laravel-db-pull --dev

Setup

Run the interactive wizard to add your first remote environment (e.g., production, staging):

php artisan db:pull-add

The wizard will guide you through:

SSH Connection details (Host, User, Port, Private Key).
Database credentials.
Analyzing remote tables for advanced filtering.
Selecting and ordering Follow-Up artisan commands to run after a successful import.

To edit an existing environment:

php artisan db:pull-edit

Usage

To pull a remote database into your local instance:

php artisan db:pull

If you have multiple remotes configured, you will be prompted to select one.

Follow-Up Commands

You can configure Follow-Up artisan commands during the wizard or later in db:pull-edit.
After a successful import, the selected commands run in the exact order you defined.
If any configured command is no longer available in your application, the pull is aborted before any changes and you will be prompted to open the editor to update the configuration.

How it works

The process executes in three safe stages:

Structure Stage: Creates all table definitions (respecting your skip list).
Base Data Stage: Imports data for all tables not marked for filtering or structure-only.
Filtered Data Stage: Imports specific data based on your custom WHERE clauses.

Configuration

The package stores connection templates in config/db-pull.php and sensitive credentials in your .env file.

Example Config Structure

"production" => [
    "ssh_host" => env("DB_PULL_PRODUCTION_SSH_HOST"),
    // ...
    "local_connection" => "mysql",
    "options" => [
        "skip_tables" => ["logs_backup", "temp_data"],
        "exclude_data" => ["activity_log", "sessions"],
        "filters" => [
            "orders" => "created_at >= DATE_SUB(NOW(), INTERVAL 6 MONTH)",
        ],
        "follow_ups" => [
            "migrate",
            "cache:clear",
        ],
    ],
],

Multi-Database Configuration Guide

Configure the target local connection per remote during the db:pull-add wizard. The selected value is stored as local_connection in config/db-pull.php.
If local_connection is omitted, db:pull will default to mysql and warn you to consider running php artisan db:pull-edit to set a specific connection.

Example with multiple remotes targeting different local connections:

"production-main" => [
    "local_connection" => "mysql",
    // ...
],
"production-billing" => [
    "local_connection" => "reporting",
    // ...
],

Requirements

PHP: 8.2+
Laravel: 12.0+
Local Binaries: ssh, mysql, mysqldump, sshpass (required when using SSH password authentication)
Remote Access: SSH access to the remote server and permission to run mysqldump.

Password-based SSH

If you do not use an SSH private key and choose password authentication, you must have sshpass installed locally. The wizard and pull command will use sshpass to pass the password non-interactively.

Install sshpass on common platforms:

Ubuntu/Debian: sudo apt-get update && sudo apt-get install -y sshpass
Alpine Linux: apk add --no-cache sshpass
Fedora/CentOS/RHEL: sudo dnf install -y sshpass (or sudo yum install -y sshpass)
macOS (Homebrew): brew install esolitos/ipa/sshpass

Contributing & Support

Follow our development and contribute on GitLab: lbyit/laravel-db-pull

Made with ♥ by LBY IT

lbyit / laravel-db-pull

Maintainers

Package info

Statistics

Security