Syncopate Bundle Laravel Package

Getting Started

Syncopate is a Symfony bundle for database synchronization between environments — the v1.6.0 release adds truncate features, which is the first thing to look at if your previous workflow required manually emptying tables before a sync.

First steps:

1. Install via Composer and register the bundle in config/bundles.php (Symfony) — note this is not a Laravel package, so in a Laravel app you'll be pulling it in as a standalone library and wiring the services yourself rather than relying on package auto-discovery.
2. Publish/review the bundle configuration (connection credentials for source and target, table allow/deny lists, and now truncate behaviour).
3. Run the bundle's console command against a scratch database first — the day-one use case is refreshing a local or staging database from a sanitized dump without stale rows surviving.

Because the prior assessment record is empty, treat this as a baseline: there is no documented upgrade path to compare against, so validate the truncate defaults against your own schema before running it anywhere that matters.

Implementation Patterns

• Pre-sync truncation: the headline v1.6.0 capability. Use it to guarantee a clean target table set before import, which removes the "delete then insert" dance and avoids primary-key collisions on repeated runs.
• Local refresh workflow: script the truncate-and-sync step as a Composer script or a make db:refresh target so developers get a deterministic database in one command.
• Table-scoped truncation: keep the truncate list explicit and narrow. Enabling truncation globally is convenient until it wipes a table you expected to preserve (lookup tables, seeded config, audit logs).
• CI/staging integration: pair truncation with the sync step in a pipeline job rather than as two separate manual invocations, so a failed sync doesn't leave you with an empty target.
• Laravel-specific wiring: if you're using this from a Laravel app, wrap the bundle's services behind an artisan command of your own rather than exposing Symfony console commands directly. This keeps the interface consistent with php artisan conventions and gives you one place to add environment guards.

Gotchas and Tips

• Framework mismatch is the main pitfall. This is a Symfony bundle; Laravel's service container, config publishing, and auto-discovery do not apply. Budget time for manual service registration and config translation.
• Truncation is destructive and non-transactional. TRUNCATE typically can't be rolled back inside a transaction on MySQL, so a mid-sync failure leaves you with empty tables. Take a dump first, or sync into a shadow schema and swap.
• Foreign keys: truncation order and FOREIGN_KEY_CHECKS handling matter. Verify the release handles constraint ordering, or your sync will fail on any relational schema.
• Environment guards: add an explicit check that refuses to truncate when APP_ENV=production. The bundle cannot know your intent; you have to encode it.
• Upgrade check: v1.6.0 is additive per the changelog (single PR, no deprecations or breaking changes listed), so bumping from v1.5.0 should be low risk — but re-read your config for newly honoured truncate keys, since additive config options can change behaviour if defaults are permissive.
• Debugging: when a sync silently skips tables, the cause is almost always the allow/deny list rather than the truncate logic — verify the resolved table list before assuming a bug.