Skip to main content

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.

Back up before every upgrade

Always take a database backup before upgrading. If something goes wrong, a backup is the only way to roll back cleanly. See Backup & Restore.


Upgrading to a release with member sign-in

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/begin links 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.


Step 1: Check for a new version​

  1. Sign in at /admin/ as an administrator.
  2. If a new version is available, a download icon appears in the top-right navbar.
  3. 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.
  4. 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.

Downgrade detection

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​

  1. 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.
  2. Choose Full Backup. If the archive times out on your host, choose Database Only.
  3. Click Generate & Download Backup and keep the file on your own computer. The archive is deleted from the server after download.
  4. Also copy Include/Config.php and download a copy of the site folder, or take a full cPanel backup.

Step 2: Check your PHP and database versions​

ReleasePHPDatabase
Any 6.x release8.2 or higher (checked on every page load)MySQL 8.4+ or MariaDB 10.11+
7.0.0 and later, including the latest release8.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.
Your host cannot offer PHP 8.4?

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​

  1. On the GitHub releases page, find the newest release whose version starts with 6 and download its zip.
  2. Upload and extract it over your existing files. Overwrite everything, then restore your Include/Config.php.
  3. Open ChurchCRM in your browser. The database migrates on the first page load.
  4. Log in and check People, Families, Groups, and Finances.
  5. 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​

  1. Set PHP to 8.4 or higher (see Step 2).
  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.
  3. Open the site. The remaining migrations run on the next page load.
  4. 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.

Try it on a copy first

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 pointSupported by the in-app upgrader?
ChurchInfo 1.2.14 – 1.3.2Yes, straight to the latest release
ChurchCRM 2.x – 5.xNo. Follow Upgrading from version 5.x
ChurchCRM 6.0.0 and aboveYes

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​

SymptomLikely causeFix
White screen / 500 error after upgradePHP version too old, or missing extensionCheck the System Requirements; review PHP error log
"Database Needs Upgrade" page won't go awayConfig.php pointing to the wrong databaseVerify Include/Config.php credentials
Old UI still showing after upgradeBrowser cached CSS/JSHard-refresh: Ctrl+Shift+R / Cmd+Shift+R
Permission errors on file writeWeb server user lost write access after file copyRun 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 HTTPSUse manual upgrade; check server firewall
Rollback neededUpgrade failed mid-wayRestore 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 '...' or COLUMN 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.