Troubleshooting

The connection test verifies in four stages — TCP, SSH, TLS, then authentication — and shows which stage failed, along with a hint. Start by checking where it stopped.

A TCP failure points to the database service not running, a wrong host or port, or a firewall in the way; databases that aren’t reachable from your network need an SSH bastion configured. An authentication failure means checking the username and password — and on MySQL, whether the connecting host is allowed for that user (the Host column).

Private keys are supported in OpenSSH and PEM formats. PuTTY’s .ppk format needs to be converted to OpenSSH format first.

Mistyped bastion usernames, passwords and passphrases are common culprits too. With multi-hop setups, check that the hops are in the right order.

For servers with self-signed certificates, either register the CA certificate in the connection settings or turn off “Verify server certificate”. A hostname mismatch means the name in the certificate (SAN) doesn’t match the host you’re connecting to. An expired certificate needs to be renewed on the server side.

For managed databases configured to require TLS — Amazon RDS, Azure Database and the like — DiffyPick automatically attempts a TLS connection even when SSL isn’t configured on the profile.

Either the selected diffs include items tagged “manual fix required”, or the connected user lacks a needed privilege. The reason is shown in an alert on the confirmation screen.

“Manual fix required” items are operations DiffyPick deliberately keeps out of automated execution because they are unsafe to automate — destructive cross-dialect conversions, for example. Apply them by hand using the TODO comments in the generated SQL, or deselect them and run the rest. For missing privileges, ask your database administrator to grant what the message names.

SQL runs one statement at a time; on failure it stops on the spot and shows the result. On PostgreSQL, SQL Server and SQLite, the transaction rolls everything back to where you started.

MySQL and MariaDB implicitly commit after every DDL statement — an engine-level behavior — so changes made before the failed statement remain. On these two engines the confirmation screen warns you every time: take the pre-run backup it suggests, and you can restore from history right away.

This happens when existing data contains duplicates or NULLs. In most cases the preflight check counts the violations before execution and offers a workaround — helper SQL that fills NULLs, for example.

Deduplicating rows on MySQL / MariaDB can’t be automated safely, so no workaround is offered there. Resolve the duplicates by hand, then run the sync again.

Backups and restores for MySQL / MariaDB / PostgreSQL / SQL Server use each database’s official CLI (mysqldump, pg_dump, sqlcmd and so on). A missing or outdated CLI is the most common cause of failure.

You can set each CLI’s path manually in Settings, then use the verify button to confirm it works. On macOS, apps launched from the Dock or Finder don’t inherit your shell’s PATH; DiffyPick compensates automatically, but if a CLI still isn’t found, setting the path explicitly is the sure fix.

The SQLite file may be open in another process — a different database client, or a cloud-sync tool. Close the app in question, wait for cloud sync to finish, and run it again.

File permissions can also be the cause. If the error message points at permissions, check the access rights on the file and its folder.

On managed MySQL (Amazon RDS and similar), local_infile is off by default on the server, so DiffyPick automatically falls back from fast bulk loading to multi-row INSERTs. The result is identical but slower; turning local_infile on in the server parameters restores the fast path.

Sync also commits in chunks (10,000 rows by default, adjustable in Settings), so tables with many rows can take a few minutes.

When the destination’s character set (latin1, for example) can’t represent some characters, the behavior is your choice in Settings. The default is to skip that table; this symptom appears when “replace with ? and sync” was selected. The replacement can’t be undone.

The safe route is to change the destination table’s character set to something more capable, such as utf8mb4, and sync again.

One license can be active on one machine at a time. Open the license screen on the original machine, choose “Release this device”, then activate on the new one.

If the original machine is no longer accessible — a hardware failure, say — support can release it for you.

License validity is cached for 7 days from the last successful online check. Past that, an online re-check is required — connect to the network and relaunch the app.

DiffyPick detected that the system clock was rolled back. Set the OS clock correctly (automatic time is recommended) and reopen the app while online to clear it.

The free mode covers SQLite connections. Activating a license unlocks MySQL / MariaDB / PostgreSQL / SQL Server — the features themselves are never limited.

Details are recorded in the log file: ~/Library/Logs/DiffyPick/main.log on macOS, %APPDATA%\DiffyPick\logs\main.log on Windows. Attaching it to a support request speeds up the investigation a lot.

Connection passwords are encrypted with a key kept in the OS keychain (Keychain on macOS, the user credential protection system on Windows). Reinstalling the OS, moving to another machine or OS user account, or resetting the keychain makes that key inaccessible, so the profiles can no longer be decrypted. The app then switches to a dedicated error state and disables adding, editing and exporting so the existing data can’t be overwritten by mistake — only importing stays available.

If you have a password-protected export of your connections, restoring it via “Import connections” brings everything back and clears the protected state automatically. Without an export file, the stored data needs to be reset: quit the app, delete ~/Library/Application Support/DiffyPick/app.json on macOS or %APPDATA%\DiffyPick\app.json on Windows, then relaunch and re-register your connections (you may need to re-enter your license key). Before migrating machines, exporting your connections is a good habit.

The encryption key for your connection profiles lives in the macOS login keychain, and depending on what an update changes, macOS may ask you to confirm access.

Choose “Always Allow”. Choosing “Deny” blocks access to the key, leaving your saved connections unloadable. If you denied it by accident, just relaunch the app and choose “Always Allow” — everything recovers as is.

License data is encrypted with the same mechanism as connection profiles, so reinstalling the OS or migrating environments can make it unreadable, and the app shows as unactivated. The license itself has not expired.

Re-entering your license key restores it. You can find the key in your purchase email or in the Polar customer portal. If you hit the activation limit, release the original machine first — see “Can’t activate the license key on another machine” above.