Oninit® Forensic Tools — Examples: dropping a dbspace

A worked run-through of the offline dbspace removal operation. For the operation's posture, constraints, and out-of-scope items, see Offline dbspace removal.

Worked example

A test instance with six dbspaces — rootdbs (1), sbspace (2), physdbs (3), encryptdbs (4), encryptdbs01 (5), encryptdbs02 (6). The exercise removes encryptdbs (dbsnum 4) and confirms the engine restarts cleanly with the remaining five dbspaces intact.

Step 1 — confirm current state

While the engine is still running, capture the dbspace list. This is both the baseline for verification and a sanity check that the dbsnum we're about to amputate is actually the one the operator means.

$ onstat -d | grep -E 'rootdbs|sbspace|physdbs|encryptdbs'
1   0x04030001 1 1 2048 N  BAE   informix rootdbs
2   0x04028001 2 1 2048 N  BAESS informix sbspace
3   0x05030001 3 1 2048 N  BAE   informix physdbs
4   0x10020001 4 1 2048 N  BAE   informix encryptdbs
5   0x10020001 5 1 2048 N  BAE   informix encryptdbs01
6   0x10020001 6 1 2048 N  BAE   informix encryptdbs02

Six dbspaces present, encryptdbs sitting at dbsnum 4. That is the row Step 5 expects to be absent.

Step 2 — quiesce the engine + take an image

$ onmode -ky
$ cp /home/informix/data/rootdbs /tmp/rootdbs.image
$ chmod 600 /tmp/rootdbs.image

The engine has to be stopped first. Editing rootdbs while the engine has it open invites torn writes — in-flight engine writes can race the offline edit. The standard recipe is to take a copy with the engine down, work against the copy, and put the edited copy back in place before restarting.

Step 3 — dry-run inspect the planned edit

ondebug rm-dbspace performs the edit (see the Subcommands section of the ondebug CLI page for the flag set). Dry-run is the default; pass --apply --backup in Step 4 to actually write.

$ ondebug rm-dbspace --dbsnum 4 /tmp/rootdbs.image
ondebug rm-dbspace summary
  target dbsnum : 4
  dbspace name  : 'encryptdbs'
  ds_flags      : 0x10020001
  owned chunks  : 1 (chunknum 4 -> /home/informix/data/encryptdbs)

  baseline integrity check: OK

ondebug: dry-run complete. Pass --apply --backup to write.

Confirm the target dbspace name + chunk-count look right before proceeding. If baseline integrity check fails, the rootdbs image was modified outside this workflow and needs to be re-captured from disk.

Step 4 — apply the edit with a backup

$ ondebug rm-dbspace --dbsnum 4 \
          --apply --backup /tmp/rootdbs.image
ondebug: backup written to /tmp/rootdbs.image.pre-edit-20260515-114210
… (summary block as in Step 3) …
ondebug: applied. dbsnum 4 removed from /tmp/rootdbs.image.

  post-edit integrity check: OK

The timestamped .pre-edit-… file is the rollback image — keep it until the engine is confirmed running. --apply without --backup is rejected; there is no engine-side transactional undo for offline edits.

Step 5 — restore, restart, verify

$ cp /tmp/rootdbs.image /home/informix/data/rootdbs
$ oninit -vw
$ onstat -
IBM Informix Dynamic Server Version 14.10.FC13W3 -- On-Line -- Up 00:00:12 -- 32768 Kbytes

$ onstat -d | grep -E 'rootdbs|sbspace|physdbs|encryptdbs'
1   0x04030001 1 1 2048 N  BAE   informix rootdbs
2   0x04028001 2 1 2048 N  BAESS informix sbspace
3   0x05030001 3 1 2048 N  BAE   informix physdbs
5   0x10020001 5 1 2048 N  BAE   informix encryptdbs01
6   0x10020001 6 1 2048 N  BAE   informix encryptdbs02

On-Line on the onstat - status line confirms the engine reached normal operating state on the edited rootdbs. onstat -d then shows the post-edit dbspace list: encryptdbs (dbsnum 4) is absent — the engine read the edited rootdbs on startup and proceeded without complaint. encryptdbs01 + encryptdbs02 remain at their original dbsnums (5 and 6); the operation removes, it does not renumber. Comparing the five rows here against Step 1's six-row baseline, the only change is the missing dbsnum 4 row.

If onstat - reports anything other than On-Line (Initialization, Recovery, Quiescent, or no response at all), or if the onstat -d output is missing expected rows, do not declare success — capture online.log for diagnostics, stop the engine if it did come up, and roll back from the Step 4 backup before retrying.

Step 6 — roll back to the pre-edit state

The Step 4 backup is the rollback path. Re-applying it returns rootdbs to its byte-for-byte original state; the engine restarts to the pre-edit dbspace list.

$ onmode -ky
$ cp /tmp/rootdbs.image.pre-edit-20260515-114210 /home/informix/data/rootdbs
$ oninit -vw
$ onstat -
IBM Informix Dynamic Server Version 14.10.FC13W3 -- On-Line -- Up 00:00:08 -- 32768 Kbytes

$ onstat -d | grep -E 'rootdbs|sbspace|physdbs|encryptdbs'
1   0x04030001 1 1 2048 N  BAE   informix rootdbs
2   0x04028001 2 1 2048 N  BAESS informix sbspace
3   0x05030001 3 1 2048 N  BAE   informix physdbs
4   0x10020001 4 1 2048 N  BAE   informix encryptdbs
5   0x10020001 5 1 2048 N  BAE   informix encryptdbs01
6   0x10020001 6 1 2048 N  BAE   informix encryptdbs02

All six dbspaces present, encryptdbs back at dbsnum 4 with its original BAE flag word — identical to the Step 1 baseline. The dbspace's chunk file was never touched by the edit (the operation only amends rootdbs metadata), so its contents are intact and the engine reads it as if the removal never happened. Demonstrates the operation is reversible up to the point a checkpoint runs on the edited state and engine-side writes drift the rootdbs forward; after that, the rollback path becomes less precise (the backup restores the metadata, but checkpoint-era engine writes are lost) and a forensic re-capture is preferred over a straight cp.