Migrate a previous database

The Standalone app for Windows can move selected records from an earlier CodeAchi database into a fresh Local setup. This workflow is available only to an organization administrator. It is not shown on Android or other operating systems and is not available in Cloud setup.

Before you begin

• Finish the initial organization and library setup, but do not add operational members, collections, loans, or account records.
• Keep the original database in a safe location and close the earlier software.
• Make sure the computer has free space for a working copy, a recovery backup, exported images, and the migrated database.
• Sign in as an administrator. Staff accounts cannot see, open, or run this workflow.

Analyze the previous database

1. Open Settings.
2. Open Migrate previous database.
3. Select the previous .sl3, .sqlite, or .db file.
4. Choose whether to migrate Members, Collections, or both. Choose Circulation only when the loan history is required; Libcodesk automatically includes Members and Collections because circulation records depend on them.
5. Wait while the bundled Windows migration component runs in the background, prepares a separate safe copy, and sends live progress to Libcodesk.
6. Review the source-to-ready counts, validation results, skipped records, and image totals.
7. If required, select Export migration report to save the analysis for review or support.

This analysis is a complete mapped dry run. It applies the same conversion and validation rules as migration, including image checks, without writing operational records to the current library. Preview image files are removed after analysis. The selected source file is never modified. If the structure is not recognized, Libcodesk stops before changing current records and offers a diagnostic report containing the safe schema fingerprint, tables, columns, counts, and detected problems.

Start the migration

1. Confirm that the analysis says Ready to migrate.
2. Select Start migration.
3. Keep the Standalone app open until the progress bar reports completion.
4. Review the completion summary, relationship validation, and migration report.

Before publishing records, Libcodesk creates and verifies a recovery backup. The migrated data is then written as one controlled operation. If publication fails, partially migrated operational records are not left visible.

Replace existing data and migrate

If the selected library already contains operational data, Start migration remains unavailable. An administrator may instead select Delete existing data and migrate.

1. Review the preview and confirm that the correct library and data areas are selected.
2. Select Delete existing data and migrate.
3. Read the permanent-deletion warning and type the displayed confirmation code.
4. Wait while Libcodesk creates and verifies a current recovery backup.
5. Watch the cleaning progress. Migration starts automatically only after the selected library is confirmed clean.

When a backup location is configured, the pre-cleaning snapshot is stored there. If no backup location has been configured, Libcodesk creates a Backup folder beside the current database and stores the snapshot there. Failure to create or verify this backup stops the workflow before any records are deleted.

Replacement removes the selected library's operational records, including dependent circulation and account records needed to prevent broken relationships. Organization settings, staff access, reusable defaults, and records belonging only to other libraries remain unchanged. The backup path is recorded in the migration result for recovery.

What is moved

Only the areas selected during analysis are published. Where the previous database contains valid supported data, the available areas include:

• member records and membership dates;
• catalogue titles and physical copies;
• accession and supported item identifiers;
• member and cover images;
• issue, renewal, and return history that can be linked safely;
• supported reservations that can be linked safely.

Organization profile details, licences, machine settings, passwords, and account/payment records are not changed by this selective workflow. Complete the normal organization setup first; existing organization and library details remain in place.

Images are exported into one managed Libcodesk media area and organized by migration and record type. The new database stores only the managed file reference; large embedded image data is not stored in database rows. The importer validates the image, uses a deterministic filename, prevents unsafe paths and overwrites, and reports a missing or invalid image without discarding the member or title. Previous passwords are not copied; affected members must set a new password.

Rows with missing relationships, invalid dates, duplicate identifiers, or an unsupported shape are reported for review instead of being guessed.

After migration

• Compare the summary counts with the earlier software.
• Open several member, title, copy, and circulation records.
• Review warnings in the migration report.
• Keep the exported JSON report with your upgrade records. It contains counts and technical diagnostics but excludes legacy passwords and known secret fields.
• Keep the original database and recovery backup until the organization accepts the migrated result.
• Ask members to set a new password before using member sign-in.

Do and don't

• Do use a fresh Local setup target.
• Do keep the app open while migration is running.
• Do review warnings and sample records after completion.
• Don't rename, edit, or replace the selected source after analysis.
• Don't try to merge a previous database into a library that already has operational records.
• Don't use replacement migration without reviewing the selected library and keeping the verified pre-cleaning backup.
• Don't delete the original database immediately after migration.

Troubleshooting

The database is not recognized

Do not edit the source. Keep the file unchanged and contact support with the displayed migration report. Do not send passwords or sensitive member information in an ordinary message.

Migration says the Local setup is not fresh

The safety check found operational records in the selected library. Use a fresh Local setup or keep the current records; migration does not silently merge or overwrite them.

An image was skipped

The previous image may be missing, invalid, unsafe to access, or larger than the supported migration limit. The member or catalogue record can still be reviewed and its image added later.

Can I run the same database again?

A completed source is identified and blocked from accidental duplicate migration. A failed publication can be reviewed and retried after the cause is corrected.

Select legacy database appears at the top of the migration workspace, before the data choices. In a narrow window the controls wrap to keep the title and action readable. While analysis or migration is running, the existing action and close restrictions remain in effect.