Doctor¶

decentdb doctor inspects a DecentDB database and returns a deterministic health report for humans, automation, and support workflows. It is read-only by default and can optionally run a small, explicit catalog of safe repair actions with --fix.

Use Doctor when you want to answer questions like:

• Is this database readable by the current engine?
• Is the WAL growing because checkpoints are blocked or delayed?
• Are indexes stale or logically inconsistent?
• Is the file fragmented enough to justify a vacuum workflow?
• Which findings should fail CI or deployment checks?
• Which safe maintenance action should be run next?

Doctor is a diagnostic and maintenance assistant. It is not a backup tool, does not replace recovery testing, and does not perform destructive compaction or source-file replacement.

Quick start¶

Run the default human-readable report:

decentdb doctor --db app.ddb

Write a machine-readable report:

decentdb doctor --db app.ddb --format json > doctor-report.json

Fail CI when warnings or errors are present:

decentdb doctor --db app.ddb --format json --fail-on warning

Verify all indexes up to the default cap:

decentdb doctor --db app.ddb --verify-indexes

Run the safe v1 fix catalog:

decentdb doctor --db app.ddb --fix

Command shape¶

decentdb doctor --db <path> [options]

Category names accepted by --checks are:

header,storage,wal,fragmentation,schema,statistics,indexes,compatibility

Use all to run every available category:

decentdb doctor --db app.ddb --checks all

Run only WAL and index checks:

decentdb doctor --db app.ddb --checks wal,indexes --verify-indexes

Exit codes¶

The default threshold is error, so warning and info findings do not fail the command unless you choose a stricter threshold.

Examples:

# Only fail on errors.
decentdb doctor --db app.ddb --fail-on error

# Fail on warnings and errors.
decentdb doctor --db app.ddb --fail-on warning

# Fail on any finding, including informational findings.
decentdb doctor --db app.ddb --fail-on info

Report status and severity¶

Doctor findings use three severities:

Findings are sorted deterministically by severity, category, and finding ID, so JSON reports are stable enough for automation and diffing.

Markdown output¶

Markdown is the default output and is intended for terminals, support tickets, and human review:

decentdb doctor --db app.ddb

The report contains:

1. Overall status.
2. Database summary.
3. Severity summary.
4. Fix records when --fix is used.
5. Findings with evidence and recommendations.

Example shape:

# DecentDB Doctor Report

## Status

Overall status: WARNING

## Database

| Field | Value |
|---|---|
| Path | app.ddb |
| Format version | 10 |
| Page size | 4096 |
| Page count | 128 |
| Schema cookie | 4 |

## Summary

| Severity | Count |
|---|---:|
| Error | 0 |
| Warning | 1 |
| Info | 1 |

JSON output¶

Use JSON when another tool needs to parse Doctor results:

decentdb doctor --db app.ddb --format json

Top-level fields:

Minimal example:

{
  "schema_version": 1,
  "mode": "check",
  "status": "warning",
  "database": {
    "path": "app.ddb",
    "wal_path": "app.ddb.wal",
    "format_version": 10,
    "page_size": 4096,
    "page_count": 128,
    "schema_cookie": 4
  },
  "summary": {
    "info_count": 1,
    "warning_count": 1,
    "error_count": 0,
    "highest_severity": "warning",
    "checked_categories": ["header", "storage", "wal", "fragmentation", "schema", "statistics", "indexes", "compatibility"]
  },
  "pre_fix_findings": [],
  "findings": [],
  "fixes": [],
  "collected": {
    "storage": {},
    "header": {},
    "schema": {},
    "indexes_verified": []
  }
}

Using Doctor in CI¶

For CI, prefer JSON plus an explicit --fail-on threshold:

decentdb doctor --db app.ddb --format json --fail-on warning > doctor.json

A common policy is:

• Development smoke checks: --fail-on error
• Release gates: --fail-on warning
• Strict observability baselines: --fail-on info

When paths in CI logs should not expose workspace or tenant names, combine JSON with --path-mode basename or --path-mode redacted:

decentdb doctor \
  --db /var/lib/my-app/customer-123/app.ddb \
  --format json \
  --path-mode redacted \
  --fail-on warning

Path rendering modes¶

--path-mode controls paths in the report:

Use basename for local logs where the file name is helpful but the full directory is not. Use redacted for multi-tenant logs, support bundles, or any environment where paths may contain customer identifiers.

Recommendations¶

By default, findings include safe recommendation text and, when useful, command snippets:

decentdb doctor --db app.ddb

Suppress recommendations when a machine consumer only needs finding IDs, severities, and evidence:

decentdb doctor --db app.ddb --format json --include-recommendations=false

Suppressing recommendations does not suppress findings, evidence, fixes, or exit-code behavior.

Index verification¶

Normal Doctor runs use metadata and do not perform a full logical scan of every index. Add index verification when you need stronger index-integrity evidence.

Verify one index:

decentdb doctor --db app.ddb --verify-index users_email_idx

Verify several indexes:

decentdb doctor \
  --db app.ddb \
  --verify-index users_email_idx \
  --verify-index orders_user_id_idx

Verify all indexes up to the default cap:

decentdb doctor --db app.ddb --verify-indexes

Raise the cap for large schemas:

decentdb doctor --db app.ddb --verify-indexes --max-index-verify 128

When the all-index request exceeds the cap, Doctor reports index.verify_skipped_limit and verifies only the capped subset. This prevents a surprise full-schema verification from turning a quick health check into a long maintenance job.

Verified index summaries appear in JSON under:

{
  "collected": {
    "indexes_verified": [
      {
        "index": "users_email_idx",
        "expected_entries": 1000,
        "actual_entries": 1000
      }
    ]
  }
}

If verification fails, Doctor emits an index.verify_failed error with expected and actual entry counts. In --fix mode, this finding is eligible for fix.rebuild_invalid_index.

Fix mode¶

Doctor is read-only unless --fix is provided:

decentdb doctor --db app.ddb --fix

Fix mode follows this sequence:

1. Collect facts and run selected checks.
2. Store the initial findings in pre_fix_findings.
3. Plan only v1-supported fix actions.
4. Execute the planned fix actions.
5. Re-collect facts and re-run selected checks.
6. Store current findings in findings.
7. Store every planned/applied/skipped/failed action in fixes.

Fix records use these statuses:

Auto-fixable findings in v1¶

Doctor does not auto-vacuum fragmented databases. The safe vacuum workflow writes a separate output database, so Doctor recommends an explicit command instead:

decentdb vacuum --db app.ddb --output app-vacuumed.ddb

Doctor also does not replace the source database, delete files, rewrite the file format, or run unsafe compaction.

Recommended fix workflow¶

For production databases:

1. Take or verify a backup using your normal backup process.
2. Run Doctor without fixes and save the report.
3. Review the findings and planned safe actions.
4. Run Doctor with --fix.
5. Run Doctor again without --fix and compare the report.

Example:

decentdb doctor --db app.ddb --format json > before.json
decentdb doctor --db app.ddb --fix --format json > fixed.json
decentdb doctor --db app.ddb --format json --fail-on warning > after.json

Common findings¶

Troubleshooting¶

Doctor exits with code 2¶

Exit code 2 means Doctor completed and found something at or above your --fail-on threshold. Inspect findings in JSON or the Findings section in Markdown. Lower the threshold only if your policy allows it:

decentdb doctor --db app.ddb --fail-on error

A large WAL finding remains after --fix¶

fix.checkpoint is skipped when active readers are present. Close long-running readers and rerun:

decentdb doctor --db app.ddb --fix --checks wal

Index verification takes longer than a normal Doctor run¶

Index verification is opt-in because it performs stronger logical checks than metadata-only diagnostics. Use named verification for targeted checks:

decentdb doctor --db app.ddb --verify-index users_email_idx

The report hides paths¶

Check --path-mode. basename intentionally removes parent directories and redacted intentionally replaces paths with <redacted>.

Recommendations are missing¶

Check whether the command used:

--include-recommendations=false

When disabled, findings and evidence remain present but recommendation text and commands are omitted.