Skip to main content

Database Issues

This section covers problems related to Mango's database layer, including the SQL database (H2, MySQL, or MariaDB) and the NoSQL point value store. Database issues can manifest as server errors, data loss, startup failures, or performance degradation.

Common Database Issues​

  • 500 Server Error -- Mango pages fail to load with an HTTP 500 error. Typically caused by a corrupted work directory, database connection failures, module crashes, or out-of-memory conditions.

  • H2 to MySQL Migration Issues -- Troubleshoot common problems when migrating from the embedded H2 database to MySQL or MariaDB, including SQL grammar errors, character encoding, column type mismatches, and connection failures.

  • Database Corruption Recovery -- Recover from H2 database corruption (error code 50100), NoSQL database corruption, and backup restoration procedures for Mango.

General Database Troubleshooting​

Identifying the Database Type​

Mango supports multiple database backends. Check which database your installation uses by looking at the env.properties or mango.properties file in <MA_HOME>:

# H2 (default, embedded)
db.type=h2

# MySQL
db.type=mysql
db.url=jdbc:mysql://localhost:3306/mango

# MariaDB
db.type=mysql
db.url=jdbc:mariadb://localhost:3306/mango

H2 Database Issues​

H2 is an embedded Java database used by default in Mango. While convenient (no external database server required), H2 is more susceptible to corruption from unclean shutdowns.

Common H2 problems:

  • Database file locked by another process -- only one Mango instance can access an H2 database at a time
  • Corruption after power failure or forced process termination
  • Database size growing uncontrollably due to insufficient purge settings

H2 recovery options:

  1. Set db.recover=true in env.properties and restart Mango. This triggers an automatic recovery attempt.
  2. Use the H2 web console to inspect the database directly (navigate to the H2 console port, typically accessible at http://localhost:8082).
  3. Restore from a backup if recovery fails.

MySQL / MariaDB Issues​

When using an external MySQL or MariaDB database:

  • Connection refused: Verify the database server is running and accessible from the Mango server. Check the host, port, username, and password in env.properties.
  • Access denied: Ensure the database user has the required privileges (SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, INDEX).
  • Packet too large: Increase the max_allowed_packet setting in the MySQL/MariaDB configuration for large data imports or JSON configuration operations.
  • Connection pool exhaustion: If Mango logs show "unable to acquire connection" errors, increase the connection pool size or investigate long-running queries that may be holding connections.

Database Backup and Recovery​

Regular backups are essential for database health. Mango provides built-in backup capabilities:

  • SQL backup: Navigate to Administration > System Settings > Database Backup to configure automatic SQL database backups.
  • NoSQL backup: The NoSQL database can be backed up by copying the database files while Mango is stopped.
  • Configuration backup: Use the JSON configuration export feature to back up data source, point, and event handler configurations independently of the database.

When restoring a database backup, always stop Mango first, replace the database files, and then start Mango. Never restore a database from a different Mango version without performing the proper upgrade procedure.