How to Use MariaDB MaxScale’s NoSQL Protocol to Bridge MongoDB and MySQL

Introduction

MariaDB MaxScale includes a NoSQL protocol module that lets applications speak the MongoDB wire protocol while actually reading and writing to a MariaDB/MySQL backend.

Key Features

Protocol conversion: translates MongoDB queries and commands into SQL statements, allowing MongoDB drivers to communicate with MariaDB/MySQL.

Seamless integration: existing MongoDB applications can connect to MariaDB/MySQL without code changes, simplifying migration.

Application Scenario

Typical need: write the same data to both MongoDB and MySQL for operational analytics, creating a dual‑write mechanism without extensive code refactoring. The MaxScale NoSQL module enables this by routing MongoDB‑style writes to MySQL automatically.

Installation & Deployment

1. Download and install MaxScale

shell> wget https://dlm.mariadb.com/3843223/MaxScale/24.02.2/yum/centos/7/x86_64/maxscale-24.02.2-1.rhel.7.x86_64.rpm</code>
<code>shell> yum install maxscale-24.02.2-1.rhel.7.x86_64.rpm -y

2. Configure MaxScale to support the MongoDB protocol

环境: 192.168.176.204 - MaxScale
      192.168.198.239 - MariaDB

3. Create the MaxScale configuration file

shell> vim /etc/maxscale.cnf

[maxscale]
threads=auto
admin_secure_gui=false
admin_host=0.0.0.0

[server1]
type=server
address=192.168.198.239
port=4309
protocol=MariaDBBackend

[MariaDB-Monitor]
type=monitor
module=mariadbmon
servers=server1
user=admin
password=123456
monitor_interval=2s

[Read-Write-Service]
type=service
router=readwritesplit
servers=server1
user=admin
password=123456
enable_root_user=1

[Read-Write-Listener]
type=listener
service=Read-Write-Service
protocol=mariadbprotocol
port=4006

[MongoDB-Listener]
type=listener
service=Read-Write-Service
protocol=nosqlprotocol
nosqlprotocol.user=admin
nosqlprotocol.password=123456
nosqlprotocol.authentication_required=false
nosqlprotocol.authorization_enabled=false
port=17017

Note: On the first start set nosqlprotocol.authentication_required=false and nosqlprotocol.authorization_enabled=false so you can log in without authentication and create the MongoDB user.

4. Start MaxScale

shell> systemctl start maxscale</code>
<code>shell> systemctl status maxscale

5. Create a MongoDB‑compatible user shell> mongosh --port 17017 In the test database run:

use test</code>
<code>db.createUser({user:"admin",pwd:"123456",roles:[{role:"dbOwner",db:"test"}]})

After the user is created, edit the configuration to enable authentication:

nosqlprotocol.authentication_required=true</code>
<code>nosqlprotocol.authorization_enabled=true

Restart MaxScale for the changes to take effect: shell> systemctl restart maxscale 6. Connect via the MongoDB protocol

shell> mongosh mongodb://admin:[email protected]:17017/test --authenticationDatabase test

Insert a document:

db.t2.insert({"age":45,"name":"中年大叔","hobby":["美食","摩旅","游泳","电影","实现50岁退休"],"address":"北京"})

Check the underlying MySQL table: mysql> show create table t2\G Query the data using MySQL JSON functions:

SELECT JSON_UNQUOTE(JSON_EXTRACT(doc,'$.name')) AS name,
       JSON_EXTRACT(doc,'$.age') AS age,
       JSON_EXTRACT(doc,'$.hobby') AS hobby
FROM t2;

Conclusion

The MaxScale NoSQL protocol module provides a highly adaptable bridge between NoSQL and SQL worlds, allowing organizations to migrate or duplicate data from MongoDB to MySQL without altering existing application code. This reduces infrastructure complexity, lowers maintenance costs, and frees developers to focus on core business logic.