The Complete Guide to Safe OJS Upgrades & Journal Migrations
An authoritative manual for conducting safe, zero-risk upgrades and migrations across Open Journal Systems versions. Covers staging replication, CLI execution, schema migrations, and rollback plans.
Real Problem
Editorial teams attempting direct web-based upgrades on live production servers frequently trigger script execution timeouts, partial database schema updates, and broken article galleys.
Practical Solution
Execute upgrades via a disciplined staging environment methodology: snapshot production databases, mirror outside-webroot repositories, execute schema migrations via the PHP CLI tool, and audit metadata integrity prior to DNS cutover.
Why OJS Upgrades Require Extreme Caution
Open Journal Systems is not an off-the-shelf blog engine. It holds the authoritative scientific record of researchers, universities, and academic societies. Within its database are immutable submission timestamps, confidential double-blind reviewer critiques, Crossref DOI registrations, and published peer-reviewed galleys.
When upgrading between major OJS iterations (such as 3.2 to 3.3, or 3.3 to 3.4/3.5), the Public Knowledge Project introduces substantial schema overhauls: relational table structures are normalized, legacy ADOdb schemas are replaced with Laravel Eloquent migrations, and file repository hierarchies are remapped. Running an unverified upgrade on live systems risks permanent data loss.
The Cardinal Rule: Always Build an Isolated Staging Clone
Never perform an OJS upgrade directly on a production server. A proper upgrade workflow always starts with replicating your live instance onto a staging subdomain (e.g., staging.journal.edu):
1. Export production database:
mysqldump -u ojs_user -p --single-transaction --quick --default-character-set=utf8mb4 ojs_prod > /backup/ojs_prod_backup.sql
2. Sync the outside-webroot files directory using rsync:
rsync -avz --progress /var/ojs_files/ /var/ojs_files_staging/
3. Import the backup into an isolated staging database and point a fresh staging codebase at this replica in staging config.inc.php.
Pre-Upgrade Database Audit and Character Set Sanitation
Before running the upgrade binary, the database must be audited for collation mismatches and orphaned rows. Tables created across different OJS versions often mix latin1, utf8, and utf8mb4 encodings. Running an upgrade across mixed-collation tables causes foreign key constraints to fail catastrophically during column alteration.
Run an automated audit query to verify all tables use utf8mb4:
SELECT table_name, table_collation FROM information_schema.tables WHERE table_schema = 'ojs_database' AND table_collation != 'utf8mb4_unicode_ci';
Executing the Upgrade via the Terminal CLI
The only safe method to execute an OJS upgrade is through the PHP command-line interface. The CLI bypasses web server timeouts and provides real-time verbose output:
First, test readiness:
php tools/upgrade.php check
If the check succeeds and confirms the target upgrade version, execute the upgrade:
php tools/upgrade.php upgrade
Monitor the console for each schema migration step. When complete, the terminal will display:
Successfully upgraded to version 3.X.X-X.
Post-Upgrade Verification and Editorial Workflow Validation
Do not declare an upgrade successful simply because the CLI script exited cleanly. You must systematically verify:
- Editorial Stage Access: Log in as an Editor and navigate to Submissions, Copyediting, and Production tabs.
- Galley Streaming: Open past issues published 5, 10, and 15 years ago and verify that PDF, HTML, and XML galleys stream properly.
- Reviewer Forms: Confirm that peer review forms render correctly and blinded reviewer comments remain protected.
- Metadata Harvesting: Access /oai?verb=Identify and /oai?verb=ListRecords to ensure the OAI-PMH repository endpoint remains compliant.
Step-by-Step Action Plan
Replicate Production to Staging
Create an exact clone of the live database, web application files, and outside-webroot submission repository on an isolated staging server.
Verify PHP & Database Prerequisites
Ensure staging PHP and MySQL versions strictly match the target OJS release requirements before touching code.
Execute Database Schema Upgrade via CLI
Run php tools/upgrade.php check followed by php tools/upgrade.php upgrade in the terminal, monitoring output for foreign key or index conflicts.
Audit Galleys & Custom Plugins
Test PDF/HTML galley downloads, editorial assignment grids, and third-party plugin compatibility across multiple published issues.
Perform Low-Downtime Production Cutover
Place production in maintenance mode, sync incremental database changes and file additions, and execute the final CLI upgrade.
Questions People Usually Ask
Why should OJS upgrades never be executed via the web browser interface?
Web browser upgrades are subject to PHP max_execution_time limits and web server gateway timeouts (HTTP 504). If the browser times out midway through migrating a million-row metrics table, the database is left in a corrupted, half-migrated state.
Can I upgrade directly from OJS 2.4.8 to OJS 3.4?
No. Major architectural jumps require an intermediate stepping-stone. You must upgrade OJS 2.4.8 first to OJS 3.3 LTS, execute all database repair scripts, and then proceed with upgrading to OJS 3.4 or 3.5.
How can we guarantee zero loss of submitted manuscripts during migration?
By placing the source journal into read-only maintenance mode before exporting the final database dump and executing rsync with checksum verification on the outside-webroot files folder.
Planning an OJS Version Upgrade?
AcademiaTech provides zero-downtime OJS upgrade and migration services with full data validation and rollback guarantees.