Zero Downtime Migrations

Zero downtime migrations allow a Frappe site to remain available during upgrades by temporarily switching it into read-only mode. Users can continue viewing pages and accessing data, while operations that modify the database are temporarily disabled until the upgrade is complete.

Overview

Instead of making the entire application unavailable during an upgrade, Frappe permits read operations while preventing writes. This significantly reduces user-facing downtime, especially for websites that primarily serve read-only content.

How Zero Downtime Migration Works

To enable read-only mode during upgrades, Frappe uses one of the following approaches depending on your infrastructure:

Method	Description
Read Replica	Read requests are served from a replica database while write operations remain disabled on the primary database.
Read-Only Database Transactions	The database itself enforces read-only transactions, preventing any modifications until maintenance is complete.

During the migration process:

Users can continue browsing website pages and reading existing data.
Forms and editable screens become read-only.
Any action that requires inserting, updating, or deleting records is temporarily blocked.
Normal functionality resumes automatically after maintenance mode is disabled.

Limitations

Important Considerations

Not every Frappe application automatically supports read-only mode. Apps that assume write access at all times may require additional development.
During schema updates, the frontend assets may be refreshed while users are still browsing the application. This can occasionally result in minor interface inconsistencies until the upgrade is completed.

Enable Read-Only Mode During Upgrades

To use zero downtime migrations, follow these steps:

Step 1: (Recommended) Configure a Read Replica

For the best user experience, configure a secondary read-only database replica before enabling this feature.

Step 2: Enable Read Access During Maintenance

Update your site’s configuration using the following command:

bench --site develop set-config allow_reads_during_maintenance 1

Once enabled, Frappe will automatically switch the site into read-only mode during supported maintenance operations.

Supporting Read-Only Mode in Custom Apps

If you’re developing a custom Frappe application, you should ensure it behaves correctly when the system enters read-only mode.

Server-Side Support

Use the frappe.flags.read_only flag to detect whether the application is currently running in read-only mode. This allows your code to skip database write operations.

@frappe.whitelist()
def log_visit():
    if frappe.flags.read_only:
        return

    doc = frappe.new_doc("Doc Visit")
    doc.insert()

In this example, the document is only created when the application is not in read-only mode.

Client-Side & Jinja Templates

Website templates automatically receive a read_only_mode variable in their rendering context. You can use this variable to display maintenance messages or temporarily disable interactive features.

<!-- some html page -->
{% if read_only_mode %}
    <div class="alert">
        Site is running in read only mode. Full functionality will be restored soon.
    </div>
{% endif %}

<!-- other content -->

This approach helps users understand why certain actions are temporarily unavailable while the upgrade is in progress.

Best Practice

Design custom applications to gracefully handle read-only mode by checking frappe.flags.read_only before performing write operations. Clearly inform users when the application is temporarily unavailable for updates, and always test zero downtime migrations in a staging environment before enabling them in production.

Rating: 0 / 5 (0 votes)