QuikData Archive and Restore Utility

Version 5.9.1

What the Archiving Tool does

The QuikData Archiving Tool packages a complete QuikData room — every related database row and every physical file — into a portable, checksummed archive, and can later restore that archive faithfully onto an empty target environment. In a single guided run it:

• Reads your site's environment and room list from the DRControl database.
• Walks the environment database to discover every row that belongs to the selected room(s), and shows you the result for review before anything is exported.
• Exports each table and verifies every row count against the discovery walk — if any table doesn't match, the run halts. No partial archive is ever accepted.
• Copies the room's physical files and search indexes, and bundles everything into spanned, SHA-256-checksummed 7-Zip volumes with a manifest describing exactly what is inside.
• On restore, verifies the package, checks the target is empty before touching it, rebuilds the schema, loads every table, re-keys the room, places the files, and only brings the room online after every check passes.

The archive workflow is read-only against your live site — nothing in the source environment is modified. The restore workflow is destructive to the target environment (see the warnings in the restore section).

Who should run it

A Site Administrator with access to the SQL Server. Specifically, you need:

• A login on the SQL Server that can read the DRControl database and the environment (project) databases. Either a SQL login (username + password) or your Windows account can be used. The same credentials are used for every environment server.
• For restore, the login additionally needs rights to drop and rebuild objects in the target environment database (in practice: sysadmin, or db_owner on the target plus rights to write room rows in DRControl).
• Access to the machine where the tool runs, with network connectivity to the SQL Server and to the room's file storage.

Credentials are used only for the session; the tool does not store your password.

What you will need

Gather these before you start:

Version note: an archive package records the schema version of the site it came from. You can restore it onto a site running the same or a newer QuikData version: the restore first rebuilds the target environment database at the archive's version, loads the data, and then automatically upgrades the restored environment to the target site's current version as part of the same run — no separate upgrade step is needed. Restoring an archive onto a site running an older version than the one it was created on is not supported, and the restore's pre-flight check aborts (with no changes made) when it detects this; upgrade the target site first with the QuikData Database Upgrade Application.

Sites without a QuikDataEnvTemplate database (for example, Azure SQL deployments): the automatic upgrade takes its list of current migrations from the QuikDataEnvTemplate database on the target SQL Server. If the target server has no such database, the restore still completes, but the restored environment is left at the archive's version, and the Restore page says so in an amber note — both before you start and under the success banner. In that case, if the site is newer than the archive, run the QuikData Database Upgrade Application against the restored environment immediately after the restore, before users open the room. See "After the restore" for how to tell which case applied.

Before you archive

• Recommended: take the room offline in QuikData before you start. Setting the room Offline blocks user access for the duration of the archive, which guarantees nobody uploads, tags, redacts, or otherwise changes the room between discovery and export. An offline room still appears in the tool's room list and archives exactly the same way. If the room is staying in service afterwards, bring it back online once the "Package written" banner appears.
• Make sure the room is quiet: no imports, productions, or other processing jobs should be writing to the room during the export. The export verifies row counts against the discovery walk, and a room that is actively changing can fail that verification (see "Reconciliation failed — export halted" under Troubleshooting).
• Confirm free disk space at the output folder — the package contains a full copy of the room's files.

The archive run itself makes no changes to the source environment, so the rest of the site — and every other room — can stay online and in use while it runs.

Archiving a room, step by step

Launch QuikData.ArchiveTool and follow the wizard. The step rail on the left shows where you are; use Next to advance and Back to revisit a step. Nothing is written to your output folder until the Export & reconcile step, and nothing in the source data is ever modified. (Discovery creates its own temporary working tables in the environment database and removes them again — your room data is only read.)

The Reconciliation bar. Once you have chosen a workflow, a Reconciliation bar appears across the top of the window with two indicator lights. They start grey and turn green as the run proves each safety check:

A run is only complete when both lights are green. Click the ▾ at the right of the bar to see the reconciled counts and timestamps.

1. Welcome

Summarizes what the tool will do. Click Next.

2. Connect to DRControl

• Enter the SQL Server name and the DRControl database name.
• Enter your Login and Password, or check Use Windows authentication.
• Click Test connection. Wait for the green "Connected — DRControl reachable" message before continuing. If the test fails, see Troubleshooting.

The tool reads the environment list from DRControl and reuses these credentials for each environment server. Next stays disabled until the connection test succeeds.

3. Choose a workflow

Two options:

• Archive — package a room's complete record set and files into a portable archive.
• Restore — load an archive package onto an empty target environment.

Select Archive and click Next. (The restore workflow is described later in this article.)

4. Select an environment

The tool lists every active environment from DRControl, with its server and database. Select the environment that contains the room(s) you want to archive and click Next.

5. Introspecting schema

Runs automatically — the tool reads the environment database's live structure (tables, columns, foreign keys) so it knows how to find everything that belongs to a room. Watch the live log if you're curious; when the status reads "Introspection complete", click Next.

6. Schema diagnostics

A read-only report of what introspection found: table and foreign-key counts, and anything unusual about the schema. Nothing here changes your database.

This page also checks whether the SQL Server command-line utilities (bcp/sqlcmd) are installed on this machine. If the banner reads "SQL Server command-line utilities missing", click Install utilities… now — the export step cannot run without them.

Use Save report… if you want to keep the diagnostics with your records, then click Next.

7. Select rooms & run discovery

• Check one or more rooms to archive. Each row shows the room's name, id, document count, and user count.
• Click Run discovery. The tool walks the database from those rooms and materializes the exact set of rows that belongs to them, with a live log of its progress.

Discovery can take a while on large rooms. Next is enabled only after discovery completes successfully for every selected room. If a red "Discovery did not complete" banner appears, see Troubleshooting.

8. Discovery review

A read-only review of what discovery found: every table that will be exported, why it was included, and the real row counts. This is your chance to confirm the archive will contain what you expect.

• Review the summary cards and the per-table manifest.
• Scroll to the bottom of the page (below the Load order list) and click Accept to proceed, or Abort to stop. Next stays disabled until you accept; accepting turns the Discovery-complete light green.

9. Pre-flight estimate

Shows the totals for the run — rooms, tables, database rows, file bytes, and an estimated duration.

• Click Choose folder… and pick the Archive output folder. The tool verifies it can write there.
• Click Next to move on to the export.

Row counts on this page are exact — they come from the completed discovery walk. Total file bytes is a best-effort scan of the room's storage folder: if it shows — and the room's status reads Bytes unavailable, the machine running the tool could not read that folder to size it. This is a warning only and does not block Next, but make sure the account you are running as can reach the room's file storage, because the packaging step needs to copy those files.

Nothing has been exported yet, and no source data is modified at this step. Plan free space at the output folder for roughly twice the totals shown while the run is in progress — the working copies are removed automatically once the package is verified.

10. Export & reconcile

• Click Start export. The tool first captures a Constraint snapshot (the exact state of every foreign key, check constraint and trigger, so restore can put them back identically) and scripts the database schema — this can take a minute or two before the first table appears. Each table is then exported and its copied row count is verified against the discovery walk; the per-table grid shows every table's Source rows, Copied rows and status as it completes.
• Wait for the green "All tables reconciled — export verified" banner.

If any table's copied count doesn't match, the run halts with a red "Reconciliation failed — export halted" banner. There is deliberately no way to proceed past a mismatch — no partial archive is accepted. See Troubleshooting.

11. Package archive

The final step bundles the verified database exports, the room's physical files, its search indexes, and the room's DRControl metadata into the package.

• Under How to deliver the package, choose one of:
  • Compress into .7z volumes (default) — the package is split into fixed-size, SHA-256-checksummed volumes. Best for removable media or transfers with size limits. Room documents are already compressed, so this mainly costs time, not size.
  • Copy the files directly (no archive) — delivers a plain, uncompressed folder tree. Much faster on a large room, and a restore reads it with no extraction step. Best when the destination is a NAS share or an attached drive.
• For .7z delivery, confirm the Span size (the package is split into volumes of this size, default 5 GB).
• Confirm the Package output folder (it defaults to the folder you chose at the pre-flight step).
• Leave On resume, trust the copy inventory unchecked unless you are resuming an interrupted run of a very large room and accept the trade-off described on the checkbox (faster, less safe).
• Click Start packaging and watch the live log as it moves through its stages (capturing, copying files, writing manifest, writing spans). Scroll down the page to see the progress and results.
• When the green "Package written" banner appears, review the summary (spans, total size, files, tables, schema version) and the Per-span checksums — each volume should read Verified — then click Open output folder to see the result.

While packaging runs, the tool stages a working copy in a temporary .stage folder inside the output folder. Once the spans are written and verified, the staging copy and the raw table exports are removed automatically — the finished output folder contains only the package.7z.* volumes, dbschema.7z and manifest.json.

If an amber "Files found outside the room's storage root" banner appears, the room has files stored outside its expected folder. Review the listed paths carefully; Override and include anyway copies them into the package and flags them in the manifest. Contact QuikData support if you are unsure.

Click Finish. The wizard returns to the Welcome page, ready for another run; close the window when you are done.

What's in an archive package

The output folder contains the spanned volumes plus the manifest:

Inside the volumes: the per-table database exports, the room's complete file tree, its search indexes, the database schema needed to rebuild the target, and a human-readable README.txt. No connection strings or credentials are ever written into a package.

Keep all volumes, dbschema.7z and manifest.json together — restore needs the complete set.

If you chose Copy the files directly (no archive), the output folder instead holds manifest.json alongside uncompressed db, schema, files and artifacts folders. Restore accepts either layout.

Before you restore

• The target environment must be empty. The tool verifies this before making any change; if the target already contains room data, the run aborts with nothing modified.
• Restore rebuilds the target environment database from the schema stored in the package. Do not point the tool at an environment you want to keep.
• The target site must be on the same or a newer QuikData version than the site the archive came from; the restore brings the restored environment up to the target site's current version automatically (see the version note above).
• The complete package (all package.7z.* volumes plus manifest.json) must be reachable from the machine running the tool.
• The staging folder (shown on the Restore page; default is .restore-stage beside the package) needs free space for the full uncompressed archive. It is removed automatically when the run ends.

Restoring a room, step by step

Launch the tool and complete the Welcome and Connect to DRControl steps as above (connect to the DRControl of the site you are restoring into), then:

1. Choose a workflow

Select Restore and click Next. The step rail on the left changes to the shorter restore sequence (Select an environment → Select a restore package → Select rooms to restore → Restore), and the Reconciliation bar switches to the Package integrity and Load reconciled lights.

2. Select an environment

Select the target environment the room(s) will be restored into and click Next. Remember: this environment's database will be rebuilt by the restore.

3. Select a restore package

• Click Browse… (or type/paste the path) to choose the archive package folder — the folder holding manifest.json alongside either the package.7z volumes or the uncompressed db, schema, files and artifacts folders — then click Load.
• The tool reads and verifies the manifest and shows a Package summary: source server and database, schema version, rooms, tables, row and file totals, and span count.
• Confirm the summary matches the archive you intend to restore, then click Next.

4. Select rooms to restore

Check the packaged room(s) to restore — only the rooms you select are created and loaded. Use Select all / Select none as needed, then click Next.

5. Restore

• Confirm the Staging folder (default: a .restore-stage folder beside the package). The package is extracted there before anything is loaded, so it needs free space for the full uncompressed archive; if the package folder is read-only, click Choose folder… and pick a writable location. The staging folder is cleaned up automatically when the run ends.
• Click Start restore and watch the progress and live log.
• The run verifies every volume and file checksum, pre-flights the target, rebuilds the schema at the archive's version, loads every table, re-keys the room to new ids, upgrades the restored database to the site's current version, restores constraints, places the physical files and index, and finally brings the room(s) online.
• The live log numbers the stages (Stage 2/14, 3/14, …) so you can see how far along the run is. The Package integrity light turns green once the package is verified, before anything in the target is touched; the schema rebuild that follows is usually the longest quiet stretch.
• Wait for the green "Restore complete — room(s) online" banner, which lists the new room id(s), and confirm both Reconciliation lights are green. Click Finish.

Three outcomes are possible:

⚠️ "Allow restore into a non-empty target (wipes it)" — this checkbox is an emergency recovery option only. It bypasses the empty-target check and wipes and rebuilds the entire target environment database, destroying everything in it. Do not use it unless QuikData support has instructed you to.

After the restore

1. Confirm the Restore page showed "Restore complete" and note the new room id(s).
2. Check whether the automatic version upgrade ran. If it did not, the Restore page shows an amber "Database upgrade still required" note under the green success banner (the same warning appears as "No automatic version upgrade on this target" when you first open the Restore page, before you click Start restore). You can confirm either case in the live log (use Copy log, or open the log file listed under Troubleshooting) on the line beginning "Pre-flight: schema-forward branch =":
   • SeedArchiveJournalThenUpgrade or SeedBaselineThenUpgrade — no amber note. The restored environment was upgraded to the site's current version during the run (the log also shows a "Forward-upgrade: …" line at Stage 8). Nothing more to do.
   • NoReseedNoUpgrade — amber note shown. The target server has no QuikDataEnvTemplate database (typical on Azure SQL), so no upgrade was applied and the environment is at the archive's version (the note names it). The rooms are online and the green banner is still accurate, but unless the site is at exactly the archive's version, run the QuikData Database Upgrade Application against the restored environment now, before users open the room.
3. Log in to QuikData, open the restored room, and spot-check it: browse documents, open a few natives, and run a search.
4. Room users are recorded in the package for reference, but review room access and re-grant users as appropriate for the target site.
5. Check the staging location. The staging folder is normally removed when the run ends, but if a .restore-stage folder is still present beside the package after a successful restore, it is safe to delete — it is only the extracted working copy, and can be as large as the uncompressed archive.

Troubleshooting

The tool writes a detailed log on the machine where it runs: C:\ProgramData\QuikData\ArchiveTool\logs\archive-YYYYMMDD.log Include this file whenever you contact QuikData support.

"Test connection" fails / cannot connect to the SQL Server

The message next to the Test connection button shows the underlying SQL error. Common causes:

"No environments found"

The DRControl database returned no environments. You most likely connected to the wrong database — go Back, confirm the DRControl database name, and Test connection again.

"SQL Server command-line utilities missing" / "bcp.exe was not found"

The export and restore steps require Microsoft's SQL Server command-line utilities (bcp). Click Install utilities… on the Schema diagnostics page (a Windows administrator prompt is expected), or install "Microsoft Command Line Utilities for SQL Server" manually, then return to the step that failed.

"Discovery did not complete"

Discovery found something about the room it could not safely classify, and stopped rather than risk an incomplete archive. The most common reason is "Classification gate FAILED — discovery BLOCKED. Unclassified … table(s): …": the environment database contains tables this version of the tool has not been told how to treat (for example, tables added by a newer QuikData feature). The check applies to the whole environment, so choosing a different room in the same environment will not help, and nothing has been exported or changed.

Click Copy log and contact QuikData support with the environment name and the full reason shown in the banner — the fix is an updated version of the tool, not something to change on your site.

A "Reclaim orphaned scratch" prompt appears

A previous archive run on this environment was interrupted and left temporary working tables behind. Answering Yes removes them — this is safe and only touches the tool's own temporary tables.

A "Clean up leftover run folders" prompt appears at startup

The tool found working folders from finished or dead runs under C:\ProgramData\QuikData\ArchiveTool (including large staging folders left behind by older versions of the tool). Answering Yes removes them and reclaims the disk space shown. Choose No only if another archive or restore run is currently in progress on the same machine.

"The restore staging folder is not writable"

The package is extracted into the staging folder before anything is loaded. The default location is a .restore-stage folder beside the package, which fails if the package lives on a read-only share or a drive without enough space. Click Choose folder… next to Staging folder and pick a writable location with free space for the full uncompressed archive, then start the restore again.

"Reconciliation failed — export halted"

A table's exported row count didn't match what discovery counted, most often because the room changed while the export was running (a processing job or user activity). Make sure nothing is writing to the room — if you have not already, take the room Offline in QuikData to block user access — then click Retry export — the run resumes from the last verified table. If it fails again on the same table, copy the log and contact QuikData support.

"Files found outside the room's storage root" during packaging

Some of the room's database records point at files stored outside the room's own storage folder. The tool blocks packaging by default so you can review the listed paths. If the files are legitimately part of the room, Override and include anyway copies them into the package (and records the override in the manifest). If you are unsure why files live outside the root, contact QuikData support before overriding.

"Pre-flight aborted" during restore

The target environment failed a safety check — most commonly it already contains room data, or it could not be reached. Nothing was changed. Pick a genuinely empty target environment, or resolve the connectivity problem, and start the restore again.

If the message begins "archive is newer than the target site", the archive was created on a newer QuikData version than the target site is running: its migration history lists scripts that the target server's QuikDataEnvTemplate database does not have (the message names them). Restoring onto an older site is not supported and there is no override. Upgrade the target site first with the QuikData Database Upgrade Application, then click Retry restore. This check runs only when the target server has a QuikDataEnvTemplate database; on servers without one (for example, Azure SQL) the tool cannot compare versions, so confirm the site version yourself before restoring.

"Restore failed — halted mid-pipeline"

The restore stopped partway. The rooms it was creating are left offline and invisible to users — the target site keeps working, minus the restore. Review the live log for the cause (disk space and connectivity are the usual suspects), resolve it, and click Retry restore; the tool cleans up its own offline rooms and restarts from the beginning of the run.

The tool closed or the machine rebooted mid-run

• During an archive: nothing in the source was modified. Start the tool again and re-run; if prompted about orphaned scratch, answer Yes to clean up the interrupted run.
• During a restore: any partially created rooms were left offline and are cleaned up automatically when you re-run the restore with the same package.
• Any temporary staging files the interrupted run left behind are offered for cleanup the next time the tool starts (the "Clean up leftover run folders" prompt); a leftover .stage / .restore-stage folder next to a package is also safe to delete manually once no run is using it.