Admin Guide — Maree-DB Docs

CLI Reference — maree-db-cli

The maree-db-cli command-line tool is the primary administrative interface. It connects to the running server via the MySQL or REST wire protocol.

Command	Description
`maree-db-cli`	Launch the interactive SQL shell (connects to localhost:3306 by default).
`maree-db-cli status`	Show server status: uptime, connections, port bindings, TamperLock state, health.
`maree-db-cli verify`	Run the 5,574-check self-verification suite. Exits 0 on pass, non-zero on failure.
`maree-db-cli users list`	List all database users and their roles.
`maree-db-cli users create`	Create a new user with password and initial role assignments.
`maree-db-cli users delete <name>`	Delete a user. All sessions for that user are immediately terminated.
`maree-db-cli backup <path>`	Create a consistent online backup to the specified path.
`maree-db-cli restore <path>`	Restore from a backup. Server must be stopped first.
`maree-db-cli wal status`	Show WAL size, current LSN, checkpoint LSN, and replication lag.
`maree-db-cli wal checkpoint`	Force an immediate WAL checkpoint.
`maree-db-cli migrate --source <url>`	Run the migration wizard from a source database URL.
`maree-db-cli keygen --type <type>`	Generate a cryptographic key. Types: `aes256`, `ed25519`.
`maree-db-cli compat-report --source <url>`	Generate a compatibility report for a source database before migration.

Connection options: Use --host, --port, --user, --password, and --tls flags to connect to a remote instance. Or set MAREEDB_HOST, MAREEDB_PORT, MAREEDB_USER, MAREEDB_PASSWORD environment variables.

User Management

Maree-DB user management uses standard SQL CREATE USER, DROP USER, GRANT, and REVOKE statements compatible with both MySQL and PostgreSQL syntax.

maree-db-cli

-- Create a new application user

maree> CREATE USER 'appuser'@'%' IDENTIFIED BY 'str0ng-passw0rd';

Query OK.

-- Grant privileges on a database

maree> GRANT SELECT, INSERT, UPDATE, DELETE ON mydb.* TO 'appuser'@'%';

Query OK.

-- Create a read-only reporting user

maree> CREATE USER 'reporter'@'10.0.0.%' IDENTIFIED BY 'report-pass';

maree> GRANT SELECT ON mydb.* TO 'reporter'@'10.0.0.%';

-- Change a password

maree> ALTER USER 'appuser'@'%' IDENTIFIED BY 'new-str0ng-pass';

-- Drop a user

maree> DROP USER 'olduser'@'%';

Roles & RBAC

Maree-DB supports role-based access control with role inheritance, row-level security policies, and column masking. Built-in compliance roles are pre-configured:

Built-in Role	Permissions
`dba`	Full administrative access — all databases, all operations.
`readonly`	SELECT only on all databases (no DDL, no DML).
`gdpr_admin`	Execute `mareedb_gdpr_erase()` and `mareedb_gdpr_report()`.
`hipaa_admin`	Execute `mareedb_hipaa_access_report()` and access PHI audit logs.
`pci_admin`	Detokenise PANs. Access PCI audit logs.
`payment_processor`	Tokenise PANs. Read masked PAN columns.
`auditor`	Execute SOC 2 and ISO 27001 evidence functions. Read-only access to all audit data.
`privacy_officer`	Execute Australian Privacy Act residency check. Access PII map.
`dpo`	Full DPO access: PII map, GDPR reports, erasure, all compliance functions.

Custom role example

maree> CREATE ROLE analytics_reader;

maree> GRANT SELECT ON reporting.* TO analytics_reader;

maree> GRANT analytics_reader TO 'analyst1'@'%';

Query OK.

-- Row-Level Security policy

maree> CREATE POLICY orders_tenant_isolation ON orders

USING (tenant_id = current_user_tenant());

Policy created. Users only see rows matching their tenant.

Backup & Restore

Online backup (server running)

bash

# Full backup to directory

$ maree-db-cli backup /mnt/backups/mareedb-$(date +%Y%m%d)

Snapshot LSN: 84729341

Copying data files... 12.4 GB

Backup complete: /mnt/backups/mareedb-20260527 (12.4 GB, 4m 12s)

# Incremental backup (WAL-based, much faster)

$ maree-db-cli backup --incremental --base-lsn 84729341 /mnt/backups/incr-$(date +%Y%m%d)

Incremental backup complete. 47 MB (WAL since base snapshot).

Restore

bash

# Stop server, restore, restart

# systemctl stop mareedb

# maree-db-cli restore /mnt/backups/mareedb-20260527

Restoring 12.4 GB...

Restore complete. WAL replay will run on next server start.

# systemctl start mareedb

Maree-DB started. WAL replay complete. Ready.

Point-in-time recovery: To recover to a specific time, restore the last full backup and then replay WAL segments up to the target LSN using --replay-to-lsn <LSN> or --replay-to-time '2026-05-27 14:30:00'.

WAL Management

The Write-Ahead Log (WAL) is the foundation of Maree-DB's crash recovery and replication. Normal operation requires minimal WAL management — Maree-DB auto-checkpoints and auto-archives WAL segments.

bash

$ maree-db-cli wal status

Current LSN : 84,729,341

Checkpoint : 84,729,200

WAL size : 128 MB (2 segments)

Replication : 1 replica, lag 0ms

WAL healthy.

$ maree-db-cli wal checkpoint

Checkpoint complete at LSN 84,729,341. WAL size: 0 MB.

Monitoring

Prometheus metrics

Maree-DB exposes a Prometheus-compatible /metrics endpoint on port 9090 (configurable). Key metrics:

mareedb_connections_active — active client connections by protocol
mareedb_queries_per_second — query throughput
mareedb_query_latency_ms — latency histogram (p50, p95, p99)
mareedb_buffer_pool_hit_ratio — cache efficiency (target: >95%)
mareedb_wal_replication_lag_ms — replication lag per replica
mareedb_tamperlock_chain_length — TamperLock chain block count
mareedb_fortress_lock_events_total — security event counter

Health check via SQL

maree-db-cli

maree> SELECT * FROM HEALTH_CHECK();

component │ status │ value

────────────────┼─────────┼──────────────────

server │ ok │ Maree-DB 1.0.0

buffer_pool │ ok │ 94.2% hit ratio

wal │ ok │ lag 0ms

tamperlock │ ok │ 1,844 blocks

connections │ ok │ 42/500

All components healthy.