Upgrade Guide
ChurchCRM supports two upgrade paths: an in-app wizard (recommended) and a manual file replacement. Both automatically apply any pending database migrations on the next page load — no SQL scripts to run by hand.
Always take a database backup before upgrading. If something goes wrong, a backup is the only way to roll back cleanly. See Backup & Restore.
The upgrade changes how people sign in. Take a backup first: it is the only way back.
- Self-service logins are removed. Every user account that had Edit Self on and was not an administrator is deleted, whatever other rights it had. The person records stay, and each person's timeline gets the note Member Portal account removed by the upgrade from System Upgrade. Their calendar subscriptions keep working while member sign-in is off; once it is on, only for people the sign-in rules let in.
- Member sign-in is off until you turn it on at Admin → Member Portal → Sign-in. Members then sign in with their own email address, so ChurchCRM must be able to send email (Email Setup). If the upgrade removed any logins, the Admin Dashboard shows Member sign-in is off with how many people used to sign in, until you turn member sign-in on or click Dismiss.
- Family emails move to people. Each family email goes to the oldest head of household who has no email of their own, or else the oldest such spouse. Nothing moves when someone already has that address as their own email. When nobody can take it, the family's timeline gets a note, and Family emails not moved on Admin → Member Portal → Members lists the family. In a family of two or more people, a moved address can't be used to sign in until staff confirm it: Email needs attention on the same tab lists them, with Confirm selected.
- Staff sign in at
/admin/. Old/session/beginlinks and bookmarks still open the same sign-in form.
See Member sign-in → After the upgrade. If you upgrade from a release without the Member Portal, also read Member Portal → For administrators upgrading.
Option 1 — In-App Upgrade Wizard (recommended)
Step 1: Check for a new version
- Sign in at
/admin/as an administrator. - If a new version is available, a download icon appears in the top-right navbar.
- Click it and select New Release, or open the Admin Dashboard, then System Info, and click Upgrade. Upgrade is not in the Admin sidebar. The page title is System Upgrade.
- Click Refresh to fetch the latest release info.
Step 2: Back up
Click Create Backup on the wizard's backup step. Download and keep the file until you have verified the new version is working.
Step 3: Download & apply
The wizard downloads the latest release from GitHub and applies it to your installation. Database migrations run automatically after the new files are in place.
Step 4: Done
A Database Upgrade page asks you to keep it open while the database is updated. When it finishes, ChurchCRM signs you out and opens the staff sign-in page at /admin/ (after a one-step update it takes you straight back to the dashboard instead). Sign back in — you are on the new version.
File Integrity Check
The upgrade page also shows a File Integrity Check comparing your installed files against the official release. Use Force Re-install to re-download and restore the current version without upgrading (useful if a file was accidentally modified).
Option 2 — Manual Upgrade
Use this if the in-app wizard fails, or if your server doesn't have outbound HTTP access.
Step 1: Download the latest release
Download the zip from https://github.com/ChurchCRM/CRM/releases/latest.
Step 2: Back up everything
Before touching any files:
Database backup (via phpMyAdmin or command line):
mysqldump -u [username] -p [database_name] > churchcrm_backup_$(date +%Y%m%d).sql
Config file backup:
cp Include/Config.php Include/Config.php.bak
Optionally, snapshot the entire installation directory for a complete rollback option.
Step 3: Replace the application files
Extract the zip and copy the new files over your existing installation:
unzip ChurchCRM-X.Y.Z.zip -d /tmp/churchcrm-new
cp -r /tmp/churchcrm-new/churchcrm/* /var/www/html/churchcrm/
On cPanel / shared hosting: upload via FTP or File Manager, extract, and overwrite the existing files.
Step 4: Restore Config.php
If the upgrade overwrote your database connection file, restore it:
cp Include/Config.php.bak Include/Config.php
Step 5: Run the database migration
Open ChurchCRM in your browser. The system automatically detects the version mismatch and applies pending database migrations on the next page load. No manual SQL steps needed.
If your application files are older than the database schema (i.e., you accidentally rolled files back), the system stops and shows a warning rather than auto-migrating. Restore the correct version files to proceed.
Step 6: Verify
- Check the version number at the bottom of any page
- Browse People, Groups, and Finances to confirm data is intact
- Hard-refresh your browser (Ctrl+Shift+R / Cmd+Shift+R) to clear cached CSS and JS
Upgrading from version 5.x (or older)
The current release cannot upgrade a 5.x database directly. Go through the latest 6.x release first, then move to the latest release. Do not skip the 6.x stop.
This works on shared hosting (cPanel or similar). The in-app wizard is not available on 5.x, so the first hop uses a manual file upload. After upgrading to 6.x, use the in-app wizard or a manual upload for the second hop.
Step 1: Back up with the in-app backup
- On your current version, open the in-app backup and download it. On the current release that is Admin Dashboard → System Info → Backup — there is no Backup item in the Admin sidebar.
- Choose Full Backup. If the archive times out on your host, choose Database Only.
- Click Generate & Download Backup and keep the file on your own computer. The archive is deleted from the server after download.
- Also copy
Include/Config.phpand download a copy of the site folder, or take a full cPanel backup.
Step 2: Check your PHP and database versions
| Release | PHP | Database |
|---|---|---|
| Any 6.x release | 8.2 or higher (checked on every page load) | MySQL 8.4+ or MariaDB 10.11+ |
| 7.0.0 and later, including the latest release | 8.4 or higher (checked on every page load) | MySQL 8.4+ or MariaDB 10.11+ |
- The app checks the PHP version itself and shows a warning if it is too old. It does not check the database version, so confirm it in cPanel (MySQL Databases, or phpMyAdmin's home page) before you start.
- If your database is older than the table says, ask your host to upgrade it before Step 3. Restoring a backup into an older database can fail.
- In cPanel, open MultiPHP Manager and switch the site to the PHP version the next step needs.
- Also see the System Requirements for the required PHP extensions.
Stop at the latest 6.x release and stay on it. It is the newest release that runs on PHP 8.2 and 8.3. Do not click Upgrade on the Admin Dashboard there, because it installs the latest release, which needs PHP 8.4. Ask your host about PHP 8.4, or move to a host that offers it, before doing Step 4.
Step 3: Upgrade to the latest 6.x release
- On the GitHub releases page, find the newest release whose version starts with 6 and download its zip.
- Upload and extract it over your existing files. Overwrite everything, then restore your
Include/Config.php. - Open ChurchCRM in your browser. The database migrates on the first page load.
- Log in and check People, Families, Groups, and Finances.
- Take another backup from the Admin Dashboard (System Info → Backup) and download it. This is your restore point for the next step.
Step 4: Upgrade to the latest release
- Set PHP to 8.4 or higher (see Step 2).
- On the Admin Dashboard, click Upgrade under System Info, or follow Option 2 — Manual Upgrade if your host blocks outbound HTTPS. The wizard still has a Create Backup step. If it lists leftover files, Review & Delete opens Orphaned Files Management.
- Open the site. The remaining migrations run on the next page load.
- Check the version number at the bottom of any page and run the File Integrity Check on the upgrade page.
If something goes wrong
Put back the files you copied for that step, then open Restore Database from the Admin Dashboard (Advanced Operations → Restore) and click Restore Database. If the site no longer opens, restore the database dump from phpMyAdmin. See Rollback.
Make a second database and a subfolder, restore your backup into it, and run both steps there before touching the live site.
Upgrading from ChurchInfo
ChurchInfo 1.2.14, 1.3.0, 1.3.1 and 1.3.2 are supported by the in-app upgrader. Restore the ChurchInfo backup into a fresh ChurchCRM install and the upgrader brings the database forward to the latest release with no manual steps.
| Starting point | Supported by the in-app upgrader? |
|---|---|
| ChurchInfo 1.2.14 – 1.3.2 | Yes, straight to the latest release |
| ChurchCRM 2.x – 5.x | No. Follow Upgrading from version 5.x |
| ChurchCRM 6.0.0 and above | Yes |
The upgrader does nothing (and logs a warning) if it does not recognise your starting version, so your data is not at risk.
Step 1: Back up your ChurchInfo database
Export it as a .sql file using phpMyAdmin or your host's tools. Do this before anything else.
Step 2: Install ChurchCRM
Download the latest release and run the setup wizard. Allow about 10 minutes on shared hosting.
Step 3: Restore your ChurchInfo backup
During setup you are prompted to restore from a backup. Upload your ChurchInfo .sql file. ChurchCRM recognises the format and upgrades the schema automatically.
Step 4: Verify
Spot-check a few family records, confirm giving history, and configure email settings.
- Carried over: members and families, contact info, group memberships, donation and pledge history
- Set up fresh: user accounts and passwords, SMTP settings, church name and logo
Troubleshooting upgrades
| Symptom | Likely cause | Fix |
|---|---|---|
| White screen / 500 error after upgrade | PHP version too old, or missing extension | Check the System Requirements; review PHP error log |
| "Database Needs Upgrade" page won't go away | Config.php pointing to the wrong database | Verify Include/Config.php credentials |
| Old UI still showing after upgrade | Browser cached CSS/JS | Hard-refresh: Ctrl+Shift+R / Cmd+Shift+R |
| Permission errors on file write | Web server user lost write access after file copy | Run chown -R www-data:www-data churchcrm (Ubuntu) or chown -R apache:apache churchcrm (Rocky Linux) |
| In-app wizard says "no new version" | GitHub API rate-limited or server has no outbound HTTPS | Use manual upgrade; check server firewall |
| Rollback needed | Upgrade failed mid-way | Restore database from backup, restore files from backup — see Rollback |
How the database upgrade runs
The Database Upgrade page applies one upgrade file per page load and reloads itself until every file is done, so a large upgrade does not run into your host's time limit. ChurchCRM records each file as it finishes. The database version moves up only when every file for that version is finished.
If the page is closed or the connection drops between two files, open ChurchCRM again. Finished files are skipped and the upgrade carries on with the next one.
"Database Upgrade Failed" — what the error means
If the database migration fails, ChurchCRM shows a Database Upgrade Failed page with the current database version, the current software version, and the error in a red box. The wording of that error tells you which kind of failure it is:
- "Upgrade file ... failed or was interrupted." A file stopped part-way through, for example because the request timed out or the server restarted. Some of its changes may be in your database and some may not, so ChurchCRM stops on that file instead of running it again. The message names the file, and the app log (
logs/yyyy-mm-dd-app.log) has the error. Restore the database and files from the pre-upgrade backup (see Rollback), then run the upgrade again and keep the Database Upgrade page open until it finishes. - A SQL error naming a column or table, such as
Duplicate column name '...'orCOLUMN already exists. The migration tried to add something that is already in your database, usually left behind by an earlier attempt that stopped part-way. Do not edit the upgrade SQL files to work around it. Restore from your backup as above, then report the failure with the error text and your app log so the migration can be fixed — see Logging & Diagnostics.
Reloading the page does not fix either error. A failed or interrupted file has to be repaired or restored first.
Database stuck at 7.8.0
If Current DB Version shows 7.8.0 and the upgrade to 7.8.1 or 7.8.2 failed with a duplicate column or a general "attempted but failed" message, install the latest release. Its 7.8.1 step checks for changes that are already in place and adds only what is missing, so the upgrade finishes without a restore. Back up the database first all the same.
If the latest release then reports "Upgrade file /mysql/upgrade/7.8.1.sql failed or was interrupted", that file can safely run again from the start. Remove its checkpoint (below) and open ChurchCRM.
Clearing a checkpoint by hand
Restoring a backup is the safe way back. If you have no backup, or someone who knows the ChurchCRM schema has already finished or undone the named file's changes, you can let the upgrader run that file again. Its progress is kept in the database_upgrade_progress table, one row per file:
DELETE FROM database_upgrade_progress
WHERE script_path = '/mysql/upgrade/7.8.1.sql';
Use the file name from the error message. Delete only that row: the rows for finished files are what let the upgrade skip them. Open ChurchCRM and the upgrade starts that file again from the beginning. If you are unsure whether a file is safe to run twice, ask on Discord with the error text and your app log before you delete anything.
Auto-Upgrade on Boot
Pending database migrations start automatically on the next page load after new files are deployed, whether via the in-app wizard or a manual file copy. The Database Upgrade page then works through them one file at a time (see How the database upgrade runs).
A smart version check prevents old application code from running against a newer database schema. If the app files are older than the database, ChurchCRM stops and shows a clear warning rather than attempting a potentially destructive migration.
After upgrading
- Review Admin → Get Started for any new configuration options added in this version
- Check the changelog for feature notes
- The docs site version of this page reflects the current release — if something looks different, check the features overview
Can't find what you need? Ask in Discord, or open an issue on the ChurchCRM repository.