Fb Copydb Laravel Package

Getting Started

mortezamasumi/fb-copydb copies a Firebird database (schema + data) from one configured Laravel connection to another. It is aimed at the "refresh a downstream environment from a source of truth" workflow — staging/local/dev restored from a production or golden snapshot.

v5.2.0 is a compatibility release. The only change is Laravel 13 support (widened illuminate/* constraints). There are no new APIs, no config changes, and no deprecations, so 5.1.x → 5.2.0 is a drop-in upgrade.

Minimal path:

composer require mortezamasumi/fb-copydb:^5.2
php artisan vendor:publish --tag=fb-copydb-config   # confirm tag name in README

1. Open config/fb-copydb.php first — it defines the source and destination connection names and any copy options. Everything else is driven from here.
2. Define both Firebird connections in config/database.php (driver => 'firebird'), typically firebird_source and firebird_target. The package references connections by name rather than opening raw credentials itself.
3. Run the package's copy command/facade call once against a throwaway target database before pointing it at anything you care about.

First real use case: point source at a read-only replica, target at your local firebird connection, run the copy, and confirm you get a working dataset without hand-rolling gbak/isql shell-outs in a bash script.

Implementation Patterns

Scheduled environment refresh. Wrap the copy call in a dedicated artisan command and schedule it, rather than calling it inline from a controller:

// app/Console/Commands/RefreshFromSource.php
Schedule::command('db:refresh-from-source')->dailyAt('02:00')->withoutOverlapping();

withoutOverlapping() is not optional — two concurrent copies into the same Firebird target will corrupt state or deadlock.

Guard the copy with a cache lock if the command can also be triggered manually from an admin panel or deploy hook. withoutOverlapping() only covers the scheduler.

Least-privilege source credentials. Give the source connection a read-only Firebird user. The package should only read, but the blast radius of a misconfigured source/target swap is the whole point of the guard.

Queue it for large databases. A copy is I/O bound and can run for minutes. Dispatch a job with an explicit $timeout larger than your largest observed copy, and $tries = 1 so a half-finished copy is never silently retried.

Test fixtures. For integration tests against real Firebird, copy a known-good snapshot once in setUpBeforeClass() (or a CI bootstrap step), then let each test transact/rollback against it. This is faster and more faithful than migrate:fresh for packages that depend on Firebird-specific DDL (generators, BLOB SUB_TYPE, computed columns).

CI matrix. Since 5.2.0 adds Laravel 13, expand your matrix to laravel: ^12.0 and ^13.0 with matching PHP versions and assert composer resolution explicitly (composer update --prefer-lowest catches constraint mistakes).

Config-driven, not code-driven. Keep connection names and options in config/fb-copydb.php + .env, so the same deployed command works against staging-from-prod and local-from-staging without code edits. Remember php artisan config:cache after any connection change.

Gotchas and Tips

• This release buys you nothing unless you re-resolve. If you pin ^5.1, you will not get Laravel 13 support. Bump to ^5.2 and re-run composer update.
• PHP floor moves with the framework. Laravel 13 raises the minimum PHP version relative to 12 — verify your image/runtime before rolling this into a matrix, or the failure will surface as an unrelated-looking dependency conflict.
• Client library mismatch is the #1 failure mode. fbclient / gbak versions must be compatible with the server. A copy that works locally and fails in CI is almost always this.
• Server-side file paths run as the Firebird user. If the package (or an underlying gbak call) touches a filesystem path, the firebird OS user needs read/write there — not your web/queue user. Permission errors look like "connection refused" in some wrappers.
• Reset generators after a data copy. Firebird sequences are objects; copying rows without advancing generators yields duplicate-key errors on first insert. Firebird has no "disable FK" switch either, so load/restore order matters if you copy table-by-table instead of using a physical backup.
• Charset/collation drift between source and target silently mangles non-ASCII text. Validate with a known accented string after the first copy.
• Nothing here is transactional across two databases. Treat the target as offline for the duration; drain queues that write to it first.
• Watch max_execution_time in web-triggered contexts and the queue worker's --timeout; both truncate long copies with confusing partial state.
• Escape hatch: if you outgrow the package's copy strategy, the config's connection names are still useful — you can shell out to gbak -b/gbak -c yourself and keep the same env layout.
• Debugging: log the resolved source/target connection names before the copy starts. Swapped connections are the most common "it wiped my data" incident and one log line prevents the whole class of it.