Church Cashbook Maintenance Manual
Document schema freeze and change management.
Principles
Church Cashbook handles financial data subject to HMRC requirements and Charity Commission oversight. Changes to the live system — whether code, schema, or configuration — must be controlled, tested, and documented. The core principle is: never deploy untested code to production, and always have a rollback plan.
Types of change
- Code deployment: PHP file changes, new pages, bug fixes. These are the most frequent changes and carry the lowest risk provided the test suite passes.
- Schema migration: Changes to the database structure — adding tables, columns, or indexes. These require careful planning, a tested migration script, and a pre-migration backup. See the Schema Manual for invariants that must not be broken.
- Configuration change: Changes to
config.php,.htaccess, or site settings. Low frequency, moderate risk — a misconfiguration can take the site offline. - Server/hosting change: PHP version upgrade, MariaDB upgrade, SSL certificate renewal. These must be coordinated with Rochen and tested in MAMP first.
Before any change to production
- ☐ All changes tested in MAMP development environment
- ☐ Full test suite passing: run.php (447), stress.php (65), pentest.php (93), PHPUnit (162)
- ☐ Database backup taken and verified
- ☐ Rollback plan documented (what to restore if the deployment fails)
- ☐ Change logged in the maintenance log with date, description, and who approved it
MariaDB/MySQL compatibility rule
The development environment uses MySQL 8.0 (MAMP) and production uses MariaDB 11.4 (Rochen). All SQL must be compatible with both. Specifically: never use VALUES() in ON DUPLICATE KEY UPDATE clauses (use row alias syntax instead); never use utf8mb4_0900_ai_ci collation (use utf8mb4_unicode_ci); never use DATABASE() in information_schema queries (use the literal schema name 'church_accounts'). A passing test in MAMP does not guarantee production compatibility.
Schema freeze
Once the system is live with parish data, schema changes require extra care. Any migration that modifies columns used in Gift Aid claim exports, transaction records, or audit logs must be reviewed against HMRC record-keeping requirements before deployment. The Schema Manual documents the invariants that must not be broken.
Dev-only files — must not be deployed to production
The following files and directories exist in the development environment only. They must never be present on the live Rochen server — they serve no purpose in production and increase the attack surface.
tests/— entire test harness directory (run.php, stress.php, pentest.php, unit tests)vendor/— Composer dependencies including PHPUnit (dev tooling only)composer.jsoncomposer.lockphpunit.xml.phpunit.result.cache
Before any production deployment, confirm none of the above are present on the server. The tests/ directory in particular contains SQL insert statements and known test credentials that must not be accessible on a live server.