Nova Data Sync Laravel Package

Getting Started

• Install with composer require coreproc/nova-data-sync, then publish the config and any migrations with php artisan vendor:publish --tag="nova-data-sync-config" (check the package README for the exact tag in 3.x).
• Read config/nova-data-sync.php first — this is where source/target connections, model mappings, and the bulk import chunk size live. Almost every day-to-day behaviour is driven from here rather than from code.
• Register the Nova tool/actions in app/Nova/NovaServiceProvider.php (tools([...]) and/or the resource-level actions the package exposes). If the tool does not appear, that registration is the usual culprit.
• First use case: add a sync action to a single Nova resource, point it at one source connection, and run it against a small seeded dataset (10–50 rows) before touching production. Watch the Laravel log and confirm row counts on both sides.
• If you are multi-tenant, verify the landlord connection name is explicitly set in config before your first run — that is precisely the area 3.0.2 changes.

Implementation Patterns

• Config-driven resource mapping. Declare each syncable resource with its model, source connection, and column map in the config, then reuse a single generic Nova action across resources. This keeps the day-to-day workflow to "add a config block" rather than "write a sync class".
• Always run bulk imports through the queue. BulkImportProcessor is designed to churn through large sets; wrapping it in a job keeps Nova responsive and gives you retries. Pass the tenant/connection context explicitly into the job payload rather than relying on ambient state.
• Chunk deliberately. Set the chunk size based on row width, not row count — wide models with JSON columns will blow memory long before the row count looks scary. Start at 500 and tune.
• Per-tenant imports. In a multi-tenant app, iterate tenants and dispatch one import job per tenant, each job initialising its own connection. Do not attempt to process multiple tenants inside a single processor run; the connection-switching cost and the state-leak risk are not worth it.
• Test the connection boundary. Write a feature test that runs an import inside a tenant context and then asserts DB::connection('landlord')->getName() (or a trivial select 1) still works. This is the regression 3.0.2 fixes, so it is worth a permanent test in your suite.
• Upgrade path. 3.x is a major line — if you are coming from 2.x, diff the config file on publish and read the upgrade notes before assuming your existing mappings still apply.

Gotchas and Tips

• The 3.0.2 fix matters if you are multi-tenant. Prior to 3.0.2, BulkImportProcessor could leave the landlord connection in a switched/dirty state after processing, so subsequent landlord queries in the same request or worker silently hit the wrong database. If you are on 3.0.1 in a tenant setup, treat this as a priority upgrade, and re-run any import jobs that executed around the time you noticed inconsistent data.
• Long-lived workers retain connection state. Even with the fix, call DB::purge() / re-establish connections in queue workers between tenants, and restart workers on deploy. A worker that has served tenant A is not a clean slate for tenant B by default.
• Connection names are literal. The package looks up connections by the string in your config; a typo or a connection defined only at runtime (e.g. inside a tenancy bootstrapper) will fail with a confusing "database not configured" error rather than a helpful one. Confirm names against config/database.php and any dynamically registered connections.
• Debugging tip: log DB::getDefaultConnection() and DB::connection()->getName() at the start and end of an import. If those two lines differ, you have a leak — that is the fastest way to reproduce the class of bug 3.0.2 addresses.
• Authorisation is yours. Nova actions are visible to anyone who can see the resource unless you gate them; bulk imports that write across databases deserve an explicit canRun / policy check.
• Extension point: if the built-in processor does not cover a transform, prefer a custom action that composes the package's config and processor over forking the package — connection handling is the part most likely to keep receiving fixes, and you want those for free.