QuikData Archive and Restore Utility

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, and a restore rebuilds the target environment database at that same version. Restore an archive onto a site running the same QuikData version it was created on. If the site has since been upgraded, restore the archive first and then bring the environment forward with the QuikData Database Upgrade Application.

Before you archive

• 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.
• 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 site does not need to be taken offline.

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. Nothing is written anywhere until the Export & reconcile step, and nothing in the source is ever modified.

1. Welcome

Summarizes what the tool will do. Click Next.

📷 [Screenshot: Welcome page]

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.

📷 [Screenshot: Connect to DRControl page with a successful test]

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.)

📷 [Screenshot: Choose a workflow page]

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.

📷 [Screenshot: Select an environment page]

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.

📷 [Screenshot: Introspecting schema page, completed]

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.

📷 [Screenshot: Schema diagnostics page]

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.

📷 [Screenshot: Select rooms & run discovery page with discovery running]

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.
• Click Accept to proceed, or Abort to stop. Next stays disabled until you accept.

📷 [Screenshot: Discovery review page]

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 begin the export.

Nothing has been exported yet, and no source data is modified at this step.

📷 [Screenshot: Pre-flight estimate page with an output folder chosen]

10. Export & reconcile

• Click Start export. Each table is exported and its copied row count is verified against the discovery walk; the per-table grid shows every table's 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.

📷 [Screenshot: Export & reconcile page, all tables verified]

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.

• Confirm the Span size (the package is split into volumes of this size, default 5 GB — useful when copying to media or transferring in pieces) and the Package output folder.
• Click Start packaging and watch the progress through its stages (capturing, copying files, writing manifest, writing spans).
• When the green "Package written" banner appears, review the span checksums and click Open output folder to see the result.

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.

📷 [Screenshot: Package archive page with the success banner and checksums]

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 and manifest.json together — restore needs the complete set.

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 should be on the same QuikData version as the site the archive came from (see the version note above).
• The complete package (all package.7z.* volumes plus manifest.json) must be reachable from the machine running the tool.

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.

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.

📷 [Screenshot: Select an environment page (restore)]

3. Select a restore package

• Click Browse… and choose the archive package folder (the folder holding the package.7z volumes and manifest.json), 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.

📷 [Screenshot: Select a restore package page with a loaded summary]

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.

📷 [Screenshot: Select rooms to restore page]

5. Restore

• 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, loads every table, re-keys the room to new ids, restores constraints, places the physical files and index, and finally brings the room(s) online.
• Wait for the green "Restore complete — room(s) online" banner, which lists the new room id(s). 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.

📷 [Screenshot: Restore page with the success banner]

After the restore

1. Confirm the Restore page showed "Restore complete" and note the new room id(s).
2. Log in to QuikData, open the restored room, and spot-check it: browse documents, open a few natives, and run a search.
3. Room users are recorded in the package for reference, but review room access and re-grant users as appropriate for the target site.

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. Copy the live log and contact QuikData support with the room name and the reason shown in the banner.

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.

"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, 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.

"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.