Back up and restore PHP Ledger

A usable backup is one you can restore into the matching application and verify through real record reads.

What must a recoverable backup contain?

Keep the database, matching release, migration history and private configuration as one identifiable recovery set.

An accounting installation is more than a collection of PHP files. The database holds posted journal lines, source records, memberships, migration receipts and other operational state. The release interprets that schema. Private configuration identifies the database and preserves any keys needed by enabled integrations. A backup that omits one of these parts may restore a login page while leaving records unreadable or credentials invalid.

Label each set with the release version, source identity where available, database version, backup time and operator. Store that inventory without including passwords or private keys in an ordinary log. Protect backup access as carefully as live database access. The contents can expose business records and authentication material even when the file is compressed. Keep a copy away from the live server so that a disk or account failure does not remove both.

How should you take a pre-upgrade backup?

Pause all writers, confirm the intended database and capture the matched state before replacing code or running migrations.

Put the application into the operator’s maintenance arrangement and stop scheduled processes that could write. Keep the previous release available. Record the current migration state and verify that the backup target is the intended installation. Read the exact package UPGRADE instructions before preparing commands; a populated upgrade has different risks from installing into an empty database.

MySQL documents logical backups with mysqldump. Use a private option file or a trusted password prompt rather than embedding a password in shell arguments. Include the schema objects required by the application, including views and triggers. Check the utility’s exit status and inspect the resulting backup inventory. A nonempty dump file is not proof that the command completed successfully or that the file contains every required object.

A transaction-consistent dump of InnoDB tables can be useful, but it does not make concurrent schema changes safe. Coordinate backup, migration and writer shutdown. Do not run a second deployment while the first operator is capturing or changing the database. Keep the application’s release files and private configuration associated with the same backup, rather than assuming the latest files on disk are necessarily the correct match.

What changes with the currency-foundation upgrade?

Migration 013 adds metadata to populated journal lines while guarding the original posted values.

The upgrade fills domestic currency snapshots without rewriting the historical debit, credit or stored payload hash. During that operation, restrictive migration guards protect the original columns and prevent ordinary connections from inserting or filling metadata. This is a maintenance operation: the web application and scheduled writers should remain stopped until the chain finishes and the final guards are verified.

If the process stops mid-migration, preserve the failed state and its receipts. The installer rejects an applying receipt rather than pretending the database is current. Do not delete the receipt, disable all guards or issue broad journal updates to make startup proceed. Recovery means following the reviewed remaining-step procedure with the migration lock and guard conditions, or restoring the matched backup. MySQL DDL can commit independently, so a generic transaction rollback is not a complete recovery strategy.

Why do database view definers matter?

The restored source views need a valid definer account and sufficient access to their underlying tables.

Migration 016 introduces effective source views. Their default security model uses the account that created them as the definer. If installation used a temporary account and that account is later removed, normal source reads may fail. A dump can retain a definer name that does not exist on the destination server. Plan this before migration and again before restoration; do not discover it only when a user opens an expense.

Use a stable, reviewed account arrangement and verify the runtime account’s view reads after restoration. A restore performed with a highly privileged administrator may succeed while the restricted application account still cannot read the necessary objects. Test through the application as well as through the restoration utility. Do not casually rewrite view definitions or assign global privileges as a universal fix; preserve the intended schema and scope the account arrangement to this installation.

How do you rehearse a restore?

Restore into an isolated destination and check the data through the matching application before declaring the backup usable.

Identify the recovery set and verify its integrity and intended restore time.
Prepare an isolated database and release directory with private access.
Restore schema, data and required database objects using the documented procedure.
Restore private configuration and required keys for that isolated destination.
Run preflight, then check sources, reports, permissions and synthetic posting behavior.
Record elapsed recovery time and any corrections needed in the runbook.

php www/phpledger/install/preflight.php

The command above is a post-restore check from the matching package root, not a command that performs the restore. Keep the staging destination separate from live credentials. Disable any external delivery configuration in the isolated environment before allowing application activity. The current foundation has no installed connector, but an operator must still inspect the actual installation rather than assume every future setup is inert.

Compare a known journal, its source and a dated trial balance with the pre-backup evidence. Confirm the expected company and book memberships. Verify both effective source views using the restricted runtime account. A successful login and connectivity health check are insufficient because neither necessarily exercises the objects whose permissions changed during restoration.

How should you decide retention and recovery targets?

Set an acceptable data-loss window and recovery time based on the business’s working pattern.

Questions for the owner and operator
Decision	Evidence to retain
How much recent work could be re-entered?	Backup frequency and the latest successful backup time
How long can posting remain unavailable?	Measured restoration duration and an available operator
Where does a second copy live?	Private off-server location and access ownership
How long are older sets retained?	Retention policy and enough capacity to apply it
Who can recover if the usual operator is absent?	A tested handoff and securely available credentials

Do not choose targets only from the backup tool’s default schedule. A weekly copy may be unsuitable for a book with daily posting, while retaining every copy forever creates storage and access problems. Review the policy after a change in transaction volume, hosting or personnel. Test periodically and after material schema or configuration changes.

When is the backup plan insufficient?

A plan is insufficient when nobody has demonstrated recovery of a matched set.

What should you do next?

A provider snapshot, a green backup notification or a copied ZIP can each be useful, but none alone proves application recovery. If the provider cannot explain database consistency, object restoration and access to an older copy, add a reviewed recovery route. If no operator can perform the rehearsal, arrange support before storing business records. Finish with a written acceptance record rather than a promise to test when an incident happens.

Questions before you continue

Check these boundaries before applying the procedure to a business installation.

Is a code-only rollback enough after migration?

No. Restore a compatible database and release together using the matched recovery set.

Does a successful dump prove recovery?

No. Restore it into an isolated environment and verify schema objects, source reads, permissions and reports.

Sources and next steps

Technical references and project behavior were checked on 16 September 2026; hosting access remains plan-specific.

The linked project files describe the current preview. Follow the instructions inside your exact downloaded package if a later release changes a command. Technical testing does not establish statutory compliance or independent accounting acceptance. See the project and preview limits.