Migration Guide — Maree-DB Docs

1

Zero-Migration Switch — MySQL, PostgreSQL, SQL Server, Redis

Maree-DB implements the native wire protocols of MySQL, PostgreSQL, SQL Server (MS-TDS), and Redis. For most applications, migration is simply transferring the data and updating the connection string. Your application never knows it switched databases.

1

Install Maree-DB

See the Installation Guide. Run on the same server or a new server — both approaches work.

2

Transfer data using your existing tools

Data transfer commands

# MySQL → Maree-DB

$ mysqldump --single-transaction mydb | mysql -h mareedb-host -P 3306 mydb

# PostgreSQL → Maree-DB

$ pg_dump mydb | psql -h mareedb-host -p 5432 mydb

# SQL Server → Maree-DB (BCP bulk export/import)

$ bcp mydb.dbo.mytable out data.bcp -S sqlserver-host -T

$ bcp mydb.dbo.mytable in data.bcp -S mareedb-host -T

# Redis → Maree-DB (RDB snapshot)

$ redis-cli --rdb dump.rdb

$ maree-db-cli import-rdb dump.rdb --host mareedb-host --port 6379

3

Update your connection string

Change the host (and optionally the port) in your application's database configuration. No code changes required.

Connection string examples

# Before (MySQL)

mysql://root:pass@old-mysql-host:3306/mydb

# After (Maree-DB, same MySQL protocol)

mysql://root:pass@mareedb-host:3306/mydb

4

Done. Your application doesn't know the difference.

Maree-DB speaks the same protocol as your old database. Restart your application pointing at the new host. Monitor for 15 minutes. Decommission the old server when you're confident.

Troubleshooting: vendor-specific quirks

If you hit compatibility issues (stored procedure syntax, non-standard functions, driver-specific handshake quirks), run maree-db-cli compat-report --source mysql://old-host/mydb — it produces a compatibility report listing any SQL that may need adjustment before migration.

2

Oracle / MongoDB Escape — Migration Wizard

Oracle and MongoDB use proprietary APIs, schemas, and data models. Maree-DB's Migration Wizard handles the translation automatically: PL/SQL → stored procedures, CONNECT BY → recursive CTEs, BSON → JSONB, MQL → SQL+JSONPath.

1

Prerequisites

Network access from Maree-DB host to the source database
Read-only credentials on the source database
Sufficient disk space for the migration snapshot (roughly equal to source database size)

2

Dry run — validate before committing

bash

# Oracle

$ maree-db-server migrate --source oracle://user:pass@host:1521/ORCL --dry-run

Analysing schema... 147 tables, 38 stored procedures, 12 views

Translation report:

Tables: 147/147 translated automatically

Procedures: 36/38 translated (2 require review — see report)

Views: 12/12 translated

Dry run complete. Migration ID: MIG-001

# MongoDB

$ maree-db-server migrate --source mongodb://user:pass@host:27017/mydb --dry-run

Analysing collections... 23 collections, 4.2 GB

Schema inferred: 23/23 collections mapped to JSONB tables

Dry run complete. Migration ID: MIG-002

3

Execute the migration

bash

$ maree-db-server migrate --source oracle://user:pass@host:1521/ORCL --parallel 8

Phase 1: Schema translation... done (2.3s)

Phase 2: Data migration (8 parallel workers)...

Progress: 147/147 tables ████████████████████ 100%

Rows migrated: 42,847,291

Phase 3: Index rebuild... done (45s)

Phase 4: Integrity check... done. 0 discrepancies.

Migration MIG-001 complete. 42,847,291 rows migrated in 4m 22s.

4

Validate

bash

$ maree-db-cli migrate validate MIG-001

Comparing row counts, checksums, and index integrity...

Validation passed. Source and target match on all 147 tables.

$ maree-db-cli migrate report MIG-001

Full migration report written to migration-report-MIG-001.html

5

Cutover

Update your application connection string to point at Maree-DB. For Oracle, use the MySQL or PostgreSQL wire protocol. For MongoDB, use the REST API or MySQL wire protocol with JSON columns.

If needed, rollback is available until you explicitly confirm the migration:

Rollback (if needed)

$ maree-db-cli migrate rollback MIG-001

Rolling back migration MIG-001...

Rollback complete. Source database unchanged.

Oracle → Maree-DB Type Mapping

Oracle	Maree-DB	Notes
`NUMBER(p,s)`	`DECIMAL(p,s)`	Exact numeric preserved
`VARCHAR2(n)`	`VARCHAR(n)`	Direct mapping
`CLOB`	`TEXT`	No size limit
`BLOB`	`BLOB`	Direct mapping
`DATE`	`DATETIME`	Oracle DATE includes time component
`TIMESTAMP WITH TIME ZONE`	`TIMESTAMP WITH TIME ZONE`	Direct mapping
`CONNECT BY PRIOR`	Recursive CTE (`WITH RECURSIVE`)	Automatically translated
`ROWNUM`	`ROW_NUMBER() OVER()`	Automatically translated
`SYSDATE`	`NOW()`	Automatically translated
`NVL(a,b)`	`COALESCE(a,b)`	Automatically translated
`DUAL`	Omitted (not needed)	`SELECT 1` works directly
PL/SQL procedures	Stored procedures	36/38 translate automatically; complex DBMS_* calls flagged for review
`BULK COLLECT INTO`	Batch SELECT	Translated to batch operations

MongoDB → Maree-DB Type Mapping

MongoDB	Maree-DB	Notes
Collection	Table with `JSONB data` column + GIN index	Full document stored as JSONB; indexed fields extracted as columns
BSON document	`JSONB`	Native JSONB with path operators
`ObjectId`	`VARCHAR(24)`	Stored as hex string
`$lookup`	`LEFT JOIN`	Translated to standard SQL JOIN
`$match`	`WHERE`	MQL predicates → SQL WHERE with JSONPath
`$group`	`GROUP BY`	Aggregation pipeline → SQL aggregates
`$sort`	`ORDER BY`	Direct mapping
`$limit`	`LIMIT`	Direct mapping
Text index	Full-text index	Translated to GIN tsvector index
Geospatial index	Spatial R-Tree index	GeoJSON points/polygons → GEOMETRY type

3

Multi-Source Consolidation

Replace multiple separate databases with a single Maree-DB instance. Specify all sources in one command — the migration wizard migrates them in parallel and maps each to the appropriate Maree-DB data model.

Multi-source migration

$ maree-db-server migrate \

--source mysql://user:pass@mysql-host/appdb \

--source redis://redis-host:6379 \

--source mongodb://user:pass@mongo-host/sessiondb \

--parallel 12

MySQL: 147 tables → relational store

Redis: 2.1 M keys → key-value store

MongoDB: 23 collections → JSONB tables

All sources migrated. One connection string to rule them all.

Data model guidance: Structured transactional data → relational tables. Session/cache data → key-value store. Semi-structured documents → JSONB. Time-series events → time-series model. All are queryable together in a single SQL JOIN.

4

Live Migration (CDC) — Zero Downtime

Change Data Capture (CDC) allows you to migrate while the source database continues serving live traffic. Maree-DB continuously replicates changes from the source until you cut over. Zero downtime. Zero data loss.

1

Start CDC replication

bash

$ maree-db-server migrate --source mysql://user:pass@host/mydb --mode cdc

Initial snapshot: 42,847,291 rows migrated.

CDC active. Replicating changes from source. Lag: 0ms.

2

Monitor replication lag

bash

$ maree-db-cli migrate status MIG-001

Mode: CDC (live replication active)

Replication lag: 3ms

Changes replicated: 148,392 since initial snapshot

Ready for cutover when lag is consistently below 10ms.

3

Cutover

When you're ready, perform the cutover during a low-traffic window. The process takes seconds:

bash

$ maree-db-cli migrate cutover MIG-001

Draining remaining changes (lag: 1ms)...

Verifying integrity...

Cutover complete. Maree-DB is now primary. Update your connection string.

5

cPanel Migration — Automatic Socket Takeover

The Maree-DB cPanel plugin replaces MySQL on cPanel/WHM servers. The plugin intercepts the MySQL socket so existing hosted sites continue to work immediately — with zero configuration changes on any hosted site.

cPanel/WHM (root)

# curl -fsSLO https://dist.mareedb.com/maree-db-v1.0.0-cpanel-plugin.tar.gz

# /usr/local/cpanel/scripts/install_plugin mareedb-cpanel-plugin.tar.gz

Migrating existing MySQL databases...

247 databases migrated

MySQL socket intercepted at /var/lib/mysql/mysql.sock

All existing sites operational

cPanel migration complete. No site configuration changes required.

After installation, all existing WHM/cPanel database operations continue to work through the MySQL wire protocol. Maree-DB silently handles all requests. New sites are automatically provisioned in Maree-DB.