How to Migrate from a Legacy Installation
This guide imports your existing data from an older HandyCafe V3 or V4 installation into a modern HandyCafe server. The migration is non-destructive to the source: the original files are not modified or deleted.
Database migration runs on Windows only. Runtime support for legacy clients to connect over the original protocol works on every platform (see Legacy Clients Settings).
What You Will Need
- A Windows machine with both the legacy installation and the modern HandyCafe server on the same system, or access to the legacy database file.
- Admin access to the HandyCafe Server.
- The legacy server stopped. The source database should not be actively written during migration.
- Free disk space at least equal to the size of the legacy database (for the new HandyCafe database copy).
- 10 to 30 minutes of uninterrupted time. Migrations on large datasets can take several minutes. Do not close HandyCafe during the run.
Step 1: Stop the Legacy Server
Open the legacy HandyCafe server application. Stop all sessions and exit the application. If the legacy server runs as a Windows service, stop the service from services.msc.
Expected result: The legacy server process is no longer running. The database file is not held open.
Step 2: Open the Legacy Clients Settings Page
- Launch HandyCafe.
- Open Settings in the sidebar.
- Click Legacy Clients.
- Scroll to the Database Migration section.
Expected result: If the system detects a legacy installation, the page displays the install path, database path, server version, and INI file count. If nothing is detected, the page says "No legacy installation detected." In that case, verify that the legacy files exist in a standard location such as Program Files\HandyCafe or C:\HandyCafe.
Step 3: Review the Detected Installation
Verify the detected values match your known legacy installation:
| Field | What to Check |
|---|---|
| Install Path | Points to the correct HandyCafe folder. |
| Database Path | Points to the legacy database file inside the install folder. |
| Server Version | Matches the version of your legacy server (for example 3.4.01 or 4.0.10). |
| INI File Count | Non-zero. A healthy installation has multiple INI files for different configurations. |
If any field is wrong, close HandyCafe, fix the installation, and reopen.
Step 4: Check the Encoding Field
Before running migration, confirm the Encoding field in the Runtime Protocol section is set correctly for your source data. This is in the same settings page, higher up.
| Source Locale | Recommended Encoding |
|---|---|
| Turkish | cp1254 |
| Western European (English, French, German, Spanish, Italian, Portuguese) | cp1252 |
| Other | cp1254 (the server accepts this as a default fallback) |
If you change the encoding, click Save before continuing.
Expected result: Source strings will decode cleanly during migration, which avoids a completed_with_warnings outcome.
Step 5: Start the Migration
- Click Start Migration.
- A progress modal opens. It displays the current phase and the number of rows processed so far.
- Do not close HandyCafe or put the computer to sleep.
- Wait for completion. Small datasets finish in under a minute. Larger datasets can take 5 to 10 minutes.
Expected result: The progress modal closes and the status changes to completed or completed_with_warnings. A notification appears confirming the run.
Step 6: Review the Migrated Counts
After completion, the page displays the migrated record counts:
| Count | Meaning |
|---|---|
| Members | Customer records imported. |
| Pricing | Pricing tables and schedule entries imported. |
| Products | Product catalog entries imported. |
| Orders | Historical orders imported. |
| Transactions | Ledger entries imported. |
| Logs | Audit and warning logs imported. |
| Warnings | Records that were skipped during import. Only appears when the status is completed_with_warnings. |
Click the Details expander to see the full breakdown. Verify that the counts look reasonable against your expectations.
Expected result: All four categories (members, products, orders, transactions) show non-zero counts if your source had data in those tables.
Step 7: Handle Warnings (If Any)
If the status is completed_with_warnings, expand the warnings list and review the skipped records.
Common warnings and their fixes:
| Warning | Cause | Fix |
|---|---|---|
| Encoding decode error | The source text contains bytes that do not decode in the configured encoding. | Run Undo, change the Encoding field to match the source locale, and re-run migration. |
| Malformed date | A legacy record has an invalid time stamp (for example 0000-00-00). |
These are safely skipped. No action needed. |
| Duplicate key | A record with the same identifier already exists in HandyCafe. | If this was an unintended second migration, run Undo and Re-run. If you are merging databases, accept the skip. |
Expected result: You either accept the warnings as known-acceptable losses or fix the underlying issue and re-run.
Step 8: Spot-Check Imported Data
Before retiring the legacy server, manually verify a sample of each record type.
- Open Members in the sidebar. Search for a member you know from the legacy system. Confirm name, balance, and contact info.
- Open Settings > Pricing. Confirm hourly rates match the legacy schedule.
- Open Products. Confirm product names and prices.
- Open Cash Report for a recent historical day. Confirm totals match what you expect from the legacy system.
Expected result: Random samples match the legacy source. If a particular record is wrong, note the issue. Minor formatting differences are normal. Major value mismatches suggest an encoding or data integrity problem worth investigating before going live.
Step 9: Enable Legacy Client Runtime Support (Optional)
If you want your existing V3 or V4 client machines to keep connecting while you transition, enable the runtime protocol now.
- Scroll to the top of the Legacy Clients settings page.
- Toggle Enable Legacy Client Support on.
- Confirm the listener ports (UDP 710, TCP 712, file transfer 717) do not conflict with anything else on your network.
- Click Save.
Expected result: Legacy clients on the LAN appear in the Admin Panel within 5 to 10 seconds. See Legacy Clients for how to manage them from the panel.
How to Undo a Migration
If the migration produced unexpected results, you can roll it back completely. The original legacy database is untouched.
- Open Settings > Legacy Clients.
- Scroll to the Database Migration section.
- Click Undo Migration.
- Confirm in the dialog.
Every migrated row is deleted from HandyCafe. The status reverts to never. You can then fix the underlying issue (encoding, source data cleanup, etc.) and run Start Migration again.
How to Re-run a Migration
Re-running replaces migrated data with fresh data from the source.
- Open Settings > Legacy Clients.
- Click Re-run Migration (the button relabels from Start Migration after the first completed run).
- The flow is identical to the initial run.
Re-run is safe to use as many times as you need. It does not duplicate data because it replaces the existing migration output.
Common Mistakes to Avoid
- Running migration while the legacy server is active. The source database may be locked or may contain partial writes. Always stop the legacy server first.
- Ignoring the Encoding field. Running with the wrong encoding corrupts member names and log messages. Fixing this after the fact requires Undo and Re-run.
- Closing HandyCafe during migration. The run is interrupted and partial data is written. Recovery requires Undo. Always let the progress modal complete.
- Skipping the spot-check step. Trusting the record counts without verifying sample data misses subtle issues such as locale mismatches or rounding errors.
- Deleting the legacy installation too soon. Keep the source files for at least one full pay cycle after migration. If a discrepancy surfaces on a monthly report, you can reference the original records.
- Migrating without a backup. Copy the legacy installation folder before the first migration. While the source is not modified by migration, disk issues or accidents can happen. A backup is cheap insurance.