Koovira Dev Docs
_tools/README.md

_tools/ — validation & generation scripts

Read-only scripts that keep this documentation validated against the live database. They are the practical arm of ../METHODOLOGY.md: if a fact can be read from the DB, read it — don't retype it from an audit file.

Requires the Laragon stack running (PHP 8.3 CLI + MariaDB reachable via config/baseconfig/config.php). Run everything from the repo root.

ScriptWhat it does
kv_docs_db.phpReusable read-only helpers: kv_docs_conn(), kv_docs_tbl_exists(), kv_docs_row_count() (exact COUNT(*)), kv_docs_columns(), kv_docs_foreign_keys(), kv_docs_like(), kv_docs_table_total(). require it from any probe.
gen_data_dictionary.phpGenerates ../90-database/tables/<table>.md + ../90-database/INDEX.generated.md from the live schema. Run with an optional LIKE pattern.

Examples

# Full data dictionary (all 1,797 tables — large; commit selectively)
php developer/docs/_tools/gen_data_dictionary.php

# Just one module's tables
php developer/docs/_tools/gen_data_dictionary.php 'order%'
php developer/docs/_tools/gen_data_dictionary.php 'kv_order_finance%'

Ad-hoc validation (put these in the scratchpad, not the repo)

<?php
require 'developer/docs/_tools/kv_docs_db.php';
$db = kv_docs_conn();
var_dump(kv_docs_row_count($db, 'commission_transactions'));  // exact, dated in your notes
print_r(kv_docs_columns($db, 'kv_order_finance_entries'));
print_r(kv_docs_like($db, '%settlement%'));

Rules

  • Read-only. These scripts never mutate. KVGuardedPDO also blocks DDL from non-migration

contexts, but the discipline is: documentation reads, never writes.

  • table_rows from kv_docs_like() is an estimate. For any number you quote in a page, use

kv_docs_row_count() (exact COUNT(*)) and date it.

  • The generated 90-database/tables/*.md are overwritten on every run. Never hand-edit them;

put table prose in the owning module's data-model.md.