WebSQL Removal and How It Affects Your Mendix PWAs

Update 2 (March 2024): The removal of WebSQL in Chromium-based browsers is resolved in the following versions of Mendix:

• Mendix 9.24.18
• Mendix 10.6.6
• Mendix 10.9.0

Offline-first progressive web apps built with these or newer versions of Mendix no longer use WebSQL to store offline data. The offline database is migrated automatically the first time a user opens the updated app. To avoid data loss, please ensure that the migration happens before WebSQL is finally removed when Chromium 124 is adopted by your users’ browsers.

Update (March 2024): The Chromium team has announced that support for WebSQL using the Origin Trial will be dropped with version 124, which is expected to be released on April 16th. This is more than a month earlier than initially announced. On the upside, we are finalizing the fix for Mendix to move away from WebSQL and plan to release it this month. To prepare your Mendix offline-first PWA, update it to the latest version of Mendix 9.24 or 10.6 now. Once we announce the release of the fix, update the application to that version and publish it. This way, the final update will most likely be seamless, meaning, no manual adjustment is needed. The same is true for your users: the fix will automatically be applied, and all offline data will be migrated. Just ensure that your users access the app before updating their browsers.

Chromium is an open source web browser that is used in multiple popular web browsers including Google Chrome, Microsoft Edge, and the default web browser of the Android operating system. In this blog post, the team maintaining Chromium has announced that they will drop support for WebSQL in Chromium 119, to be released on October 31st. This change will be adopted by future versions of the above browsers as soon as they update to that version of Chromium. While Chrome and Edge are updated frequently, the Android web browser is updated typically only when updating the operating system. That means that the change is only applied if the device is updated to an Android version released after October 31st.

Mendix supports building web-based, offline-first apps by using one of the Offline PWA navigation profiles. These apps use WebSQL under the hood to store all objects that are synchronized to the device and available for offline use. Consequently, these apps will no longer work once their users’ web browsers have been updated to Chromium 119. Hybrid offline-first apps and Native apps built with Mendix are not affected.

Extending Support for WebSQL

As a first measure, we recommend extending support for WebSQL if your app is used from Chrome or Edge. This is not needed if your app is only accessed via Android web browsers. To implement this measure, two steps are needed:

1. Register for the Origin Trial “WebSQL” and receive a trial token.
2. Add a custom header to the web server hosting the Mendix application.

We explain these steps in detail below.

Origin Trial Registration

Origin Trials are managed by Google and Microsoft. They allow developers to activate new features or request extended support on removed features in Chromium-based browsers. Follow these instructions to register for the Origin Trial with Google:

1. You need a Google account to register for a token. If you don’t have one, create an account here.
2. Access the Origin Trial registration website from Chrome and sign in with your Google account.
3. Find the trial for WebSQL and click Register.
4. Fill in the URL of the environment running your offline PWA under Web Origin.
5. Do not select “Third-party matching” or “I need a token to match all subdomains”.
6. Select the expected usage of your app per day.
7. Check the four check boxes at the bottom.
8. Click Register.
9. Redeploy the app and start the environment for the changes to take effect

It is also possible to register for an Origin Trial with Microsoft. It is not necessary to do both (either token will work in both the Chrome and Edge web browsers).

WebServer Configuration

To enable the Origin Trial and extend support for WebSQL you must add the token obtained above as a custom header to the web server that serves the static content of a Mendix application.

Origin-Trial: YOUR_TOKEN

Here are instructions for the Mendix Cloud, NGINX, and Microsoft IIS.

Mendix Cloud

1. Access the Developer Portal and open your app.
2. Select Environments from the navigation on the left.
3. Click on Details for the environment you want to enable the Origin Trial for.
4. Select Network from the tab bar on the top.
5. Click Add in the HTTP Headers section.
6. Select Origin-Trial as a Header from the list.
7. Enter your trial token in the Value field.
8. Click Save.
9. Redeploy the environment for the changes to take effect. Restarting is not sufficient and will lead to an error.

Mendix CloudFoundry Buildpack and Docker Mendix Buildpack

For the Mendix CloudFoundry Buildpack and the Docker Mendix Buildpack, we have a similar update like the Mendix Cloud Portal update planned on October 26.

With this update, you can enable the Origin Trial by setting an HTTP response header using this command:

cf set-env <YOUR_APP> HTTP_RESPONSE_HEADERS '{"Origin-Trial": "YOUR_TOKEN"}'

NGINX

Add add_header Origin-Trial "YOUR_TOKEN"; to the location where Mendix client files are served (replace YOUR_TOKEN with the token obtained above). Below is a complete example:

server {
    listen 80 default_server;
    listen [::]:80 default_server;
    root /var/www/html;
    index index.html index.htm index.nginx-debian.html;
    server_name _;
    location / {
        add_header Origin-Trial "YOUR_TOKEN";
        try_files $uri $uri/ =404;
    }
}

Microsoft IIS

Follow this guide to add a custom header to the web site serving the Mendix client files. Set the Name to Origin-Trial and the Value to your trial token. Restart the web server afterwards.

Validate the token

You can check that the token is accepted and WebSQL remains available in the developer tools provided by Chrome and Edge:

1. Open your offline-first PWA in Chrome or Edge.
2. Open the Developer Tools (Press F12).
3. Select the Application tab.
4. Select top under Frames in the list on the left.
5. Verify that WebSQL is listed under Origin Trials.

Outlook

We are working on replacing WebSQL with the alternative solution suggested by the Chromium team. This solution will be released in the near future for Mendix 9.24 and Mendix 10. We will inform you in the release notes when this is done.

Once the solution is released and your offline-first PWA is migrated to that version, it no longer relies on WebSQL to store offline data. That means the WebSQL origin trial is no longer needed and you can remove the token.