Laravel Vanguard Laravel Package

Technical Evaluation

Architecture fit: Vanguard v2.7.0 remains a strong fit for Laravel applications that need package-managed backup/restore across landlord and tenant boundaries. The release is deliberately opt-in: default backups, .tar archives, checksums, health payloads, and dashboard behavior remain identical to 2.6.1. That makes the release low-risk for existing adopters and suitable for teams that want incremental adoption of tenancy, encryption, storage, and PostgreSQL safeguards without a config republish.

Integration feasibility: Most new capabilities are environment-driven and do not require application code changes. Feasible additions include dedicated backup/restore database connections, single-database tenancy mode, age-encrypted archives, PostgreSQL pg_dump/server major checks, Cloudflare R2 as a remote destination, and installer drift reporting. Feasibility depends on operational prerequisites: correct database roles and drivers, an age binary and recipient/private-key custody, league/flysystem-aws-s3-v3 for R2, and a deliberate restore model for encrypted archives.

Technical risk:

• Encryption is operationally sensitive. Losing the age private key makes archives unrecoverable, and encrypted restores are intentionally console-only via vanguard:restore --identity or --identity-stdin; endpoint and job restores are refused with 400.
• Single-database tenancy is not a full tenant-row restore solution. In single mode, landlord backups cover the shared database once, tenant backups cover files only, and restoring a single tenant’s rows is explicitly out of scope.
• Dedicated backup/restore connections fail loudly on undeclared connections or driver mismatch. That is safer than silent fallback, but it requires correct environment setup before enabling.
• PostgreSQL version checking defaults to off; warn is low-risk, while strict can block backups before the dump starts.
• Packages extending Vanguard face compatibility risk: BackupManager::createRecord() gains an optional fourth parameter, and subclasses that redefine it must update their signature. Subclasses that write backups outside the standard methods should call assertEncryptionReady() to honor encryption opt-in.
• Config merge behavior is a practical risk. New keys nested in existing sections (tenancy.database_mode, dump.pgsql_version_check, binaries.age) must be copied into an already-published config before their environment variables are read; the new database, encryption, and r2 sections do not need copying.
• R2 setup depends on the Flysystem S3 adapter being installed; disk name collisions are handled by letting the application’s existing disk win, but the dependency must be present.

Key questions:

• Which database engines and tenancy models are in scope: multi-database, single shared database, PostgreSQL with RLS, or mixed?
• What is the restore operating model, especially for encrypted archives that require console access and private-key input?
• Who owns age recipient configuration, private-key custody, rotation, and disaster-recovery testing?
• Is Cloudflare R2 the intended remote target, and is the S3-compatible adapter already available in the runtime image?
• What are the current pg_dump and PostgreSQL server versions, and should the version check start as warn or strict?
• Are there internal subclasses or custom backup paths that override BackupManager::createRecord() or bypass backupLandlord() / backupTenant() / backupFilesystem()?
• Does the published config predate 2.7.0, and are nested opt-in keys being copied correctly?
• Is the default dashboard authentication model acceptable, or does the application need platform-operator-only authorization through Vanguard::auth()?

Integration Approach

Stack fit: Vanguard fits Laravel applications already using scheduled jobs, queues, and environment-based configuration. The release aligns well with teams standardizing on S3-compatible storage via R2, PostgreSQL backup hygiene, and stricter tenant isolation. It also supports applications that cannot move to per-tenant databases by offering a files-only tenant backup mode for single-database tenancy.

Migration path: Treat v2.7.0 as a default-safe upgrade first. Update the package, run the existing test suite, and verify that default backups, restores, health output, and dashboard behavior match 2.6.1. Do not republish config unless required. Run vanguard:install to surface drift, using the new “New optional settings” report to distinguish disabled-by-default keys from genuinely missing behavior-changing keys. For older published configs, copy nested opt-in keys into their existing sections before setting the corresponding environment variables.

Compatibility: Applications using Vanguard directly have little to do. Internal extensions need review for createRecord() signature compatibility and for custom backup-writing paths that must call assertEncryptionReady(). Existing .tar archives and checksum behavior remain unchanged unless encryption is enabled. R2 requires the S3 Flysystem adapter and should not disturb an existing s three or application-declared vanguard-r2 disk.

Sequencing:

1. Upgrade with defaults unchanged and confirm backup/restore parity.
2. Run installer drift reporting and reconcile only behavior-changing missing keys.
3. Enable VANGUARD_PG_VERSION_CHECK=warn to surface PostgreSQL binary/server mismatch without blocking backups.
4. Add R2 only after confirming the Flysystem adapter and destination disk policy.
5. Introduce dedicated backup/restore connections where database role or RLS visibility requires them.
6. Adopt single-database tenancy mode only after confirming that files-only tenant restores meet recovery requirements.
7. Enable encryption last, with key custody, restore runbooks, and console-based restore drills in place.

Operational Impact

Maintenance: Default maintenance load is low because behavior is unchanged and the installer reports new optional settings separately. Maintenance increases with each opt-in: encryption adds key and binary lifecycle management; R2 adds storage dependency and credential management; dedicated connections add database-role configuration; PostgreSQL strict checks add upgrade coordination. The package’s loud-failure behavior is operationally preferable to silent fallback, but it requires runbooks.

Support: Support teams need clear guidance that encrypted archives are restored through the console, not the dashboard endpoint or restore job. The dashboard marks encrypted backups, and the 400 responses name the console command, which helps triage. Dashboard authentication remains application-owned beyond a logged-in user, so multi-tenant deployments should configure Vanguard::auth() and platform-operator access deliberately. Installer drift messaging reduces support ambiguity around missing versus optional settings.

Scaling: R2 offloads remote archive storage and is suitable for distributed environments. Dedicated backup connections improve correctness under PostgreSQL RLS by avoiding application-role visibility limits. Single-database tenancy reduces tenant database reads and backup fan-out for tenant data, but shifts recovery scope: tenant restores are files-only. Encryption adds CPU and key-handling overhead to archive creation, and pg_dump version checks help avoid subtle dump compatibility issues at scale.

Failure modes: Missing age binary or recipients fail backups before the dump, with no plaintext fallback. Encrypted restores through the endpoint or job are refused. Undeclared or mismatched dedicated connections fail loudly. A single-database tenant restore without restore_storage is refused by console, endpoint, and job. Missing Flysystem S3 adapter is surfaced by health and install checks. Strict PostgreSQL version checks block backups before dump when versions mismatch. Older published configs can silently miss nested opt-in keys until copied into the existing section. Subclass signature mismatches can cause PHP fatal errors.

Ramp-up: Ramp-up is low for teams staying on defaults: upgrade, verify, and use installer drift reporting. It is medium for R2 and PostgreSQL warning mode, and high for encryption and single-database tenancy because both change recovery procedures. Before broad rollout, require restore drills for encrypted archives, documented key custody, a clear statement that single-database tenant restores are files-only, and a reviewed authorization model for the dashboard.