Download the PHP package vitisstudio/laravel-cloud-db-dumper without Composer

Laravel Cloud DB Dumper

Pull a Laravel Cloud database down to your machine with one command.

php artisan db:pull resolves your Cloud target — organization, application, environment, database — fetches the connection credentials for it, dumps it to a file, and optionally restores it into your local database and runs a seeder to scrub what you just pulled down. It only asks about the parts it cannot work out for itself.

Dumps are kept, so a later run can restore an earlier snapshot without downloading anything, and --prune clears them out again. Where policy forbids production data at rest, --no-store keeps the dump out of your project entirely.

Install it as a dev dependency

This package belongs in require-dev and nowhere else. It exists to move production data onto a developer workstation: it reads your Laravel Cloud API tokens, fetches live database credentials, and overwrites your local database. None of that should be reachable from a deployed application. Installing it into require ships that capability to production for no benefit.

The service provider is auto-discovered, so there is nothing to register.

Publishing the config file is optional — the defaults work:

Requirements

The Cloud CLI does the authentication, so this package never asks you for a token:

db:pull checks the CLI version before it does anything else and stops if it is older than 0.5.3. Those versions ask the Laravel Cloud API for an include it no longer allows, so every database lookup fails with a bare 400 Bad Request that says nothing about versions. The check runs up front rather than letting you pick your way down to a database first, and it only blocks on a version it could actually read — a wrapper script or custom build is left alone.

Usage

The command walks you through it:

1. Pick a target. Organization, application, environment, then database. Anything that can be worked out is not asked about — see How the target is resolved.
2. Choose where dumps land. Defaults to database/backups, and is skipped when dump storage is off.
3. Reuse or refetch. Every dump already on disk for that database is offered, newest first, so you can restore an earlier snapshot instead of downloading anything.
4. Restore locally. Opt in, after an explicit warning naming the local database about to be overwritten. Active connections to it are terminated first so the restore is not blocked.
5. Seed. Optionally run one of your seeders against the restored data — the place to scrub emails, tokens and anything else that should not sit on a laptop.

Your choices are remembered, so the next run is a single confirmation.

Arguments and options

Name the application and environment the way you would with any cloud command — an ID or a name, either one:

Naming an application or environment overrides the saved target, so you never have to answer "use the saved one?" with "no" first.

How the target is resolved

db:pull resolves each part the way the Cloud CLI's own commands do, and only asks when something is genuinely ambiguous:

If you have already run cloud repo:config in the project, db:pull inherits those defaults and can run without a single prompt. Anything resolved for you is echoed, so a quiet run still tells you what it picked.

The environment is deliberately not inferred from your current git branch, unlike cloud deploy. This command overwrites your local database, so which environment it reads from stays an explicit choice.

Multiple Cloud organizations

Cloud CLI 0.5 holds one API token per organization, and it only prompts you to choose between them when it is attached to a terminal — which it never is when a package shells out to it. Left alone, it fails with Multiple API tokens found.

This package resolves the organization itself: it asks you once, then forwards the matching token for the rest of the run. The organization name is remembered with your other preferences. Only the name — the token is never written to disk.

Naming an organization is treated as an assertion: if it matches nothing, the command stops and lists what is available, rather than quietly running against a different one. Match is by name or slug — the CLI's token listing reports no organization id, so an id cannot be matched.

To skip that prompt entirely, name the organization up front:

Configuration

Point the package at binaries that live outside your PATH — a DBngin install, for instance:

What gets written to your project

Both belong in your .gitignore:

Database credentials are fetched live from Laravel Cloud on every run and held in memory only. They are never written to the preferences file, the dump filename, or console output.

Restoring an earlier dump

Dumps accumulate under backup_path, one per database per day, and every one of them stays restorable. On a repeat pull you are shown what is already there:

Picking one skips the download entirely — no Cloud credentials are fetched — and restores that file. Today's dump is preselected, since that is what a repeat run usually wants; an older snapshot is always a deliberate choice. Only dumps of the same database and driver are listed.

Use --download to skip the question and always pull afresh:

Dumps are never deleted behind your back. Clear them out with --prune when you want the space back.

Deleting stored dumps

Every file is listed with its size and the day it was taken before anything happens, and the confirmation defaults to no. Pruning never contacts Laravel Cloud — it is a local file operation, so there is no application picker to walk first.

Only dumps this package wrote are ever deleted. Files are matched against the {database}_{driver}_{date}.sql naming scheme, so anything else living in that folder is invisible to prune and cannot be removed by it, even by accident.

For scripts, --force skips the confirmation:

Without --force, a non-interactive run declines and deletes nothing.

Database client versions

pg_dump refuses to read a server newer than itself, and a dump taken from a newer server may not load into an older one. Most machines have several versions installed with only one of them on the PATH, which is usually the wrong one.

So on the first run db:pull asks your local database what version it is, finds every pg_dump and psql (or mysqldump and mysql) on the machine — the PATH, DBngin, Postgres.app, Homebrew — and picks the one that fits:

The choice is remembered in the preferences file with the local server version it was made for. Later runs say nothing — until something moves:

• your local database is now a different version than when you chose
• the binary you chose has been uninstalled

Then it says what changed and asks again. --clients re-opens the question at any time, and setting PG_DUMP_PATH/PSQL_PATH (or the MySQL equivalents) in config skips it entirely — an explicit path is taken as a decision already made.

A local database that is not running is not an error: the version simply stays unknown and the newest client is preferred.

Keeping nothing on disk

A dump is production data sitting on a laptop. Where a data handling policy does not allow that, turn storage off and the dump never lands in your project:

The dump is written to a private temporary directory created at mode 0700, restored into your local database, and deleted before the command exits — including when the restore fails. Same-day caching is off in this mode, because there is no longer a file to reuse, so every run downloads afresh.

Setting it in config covers the whole team; --no-store covers a single run. --no-store together with --no-restore is refused, since that combination would download a dump and then delete it unused.

The preferences file is a separate thing and is still written. It records the application, environment, cluster and database names you picked, and never any credentials — delete it, or point prefs_file somewhere outside the repository, if even that is more than your policy allows.

Contributing

Pull requests are welcome. Please keep the test suite and PHPStan green.

Security

Please review our security policy for how to report a vulnerability. Do not open a public issue for security problems.

Changelog

See CHANGELOG.md for what has changed recently.

Credits

• Dan Poblete
• All Contributors

Built on spatie/db-dumper and spatie/laravel-package-tools.

License

The MIT License (MIT). Please see LICENSE.md for more information.