Mirth Connect & OIE Database Troubleshooting

Database connectivity is critical for Mirth Connect and Open Integration Engine (OIE) operations. Both platforms use the same JDBC-based database layer, so every solution in this guide applies equally whether you are running Mirth Connect or OIE.

This guide provides comprehensive, step-by-step solutions for common database connection issues across MySQL, SQL Server, Oracle, and PostgreSQL.

Quick Diagnosis

Connection Test Checklist

Before diving into database-specific issues, verify these basics:

1. Network Connectivity — Can you ping the database server?
2. Port Accessibility — Is the database port open and accessible?
3. Credentials — Are username and password correct?
4. Database Existence — Does the target database/schema exist?
5. Permissions — Does the user have necessary privileges?

Common Error Patterns

Error Pattern	Likely Cause
Connection refused	Database server down or port blocked
Login failed	Authentication issue
Timeout	Network or performance issue
Driver not found	JDBC driver missing or incorrect
Communications link failure	MySQL server unreachable
TNS:could not resolve	Oracle TNS misconfiguration

---

MySQL Troubleshooting

Communications Link Failure

Error Message:

MySQL communications error

com.mysql.cj.jdbc.exceptions.CommunicationsException:
Communications link failure

Causes and Solutions:

1. MySQL Server Down

   Check and start MySQL service

   # Check MySQL status
   sudo systemctl status mysql
   
   # Start MySQL if stopped
   sudo systemctl start mysql

2. Network Issues

   Test network connectivity to MySQL

   # Test connectivity to MySQL port
   telnet mysql-server 3306
   
   # Check firewall rules
   sudo ufw status

3. Connection Timeout

   Increase MySQL timeout values

   -- Increase timeout values
   SET GLOBAL wait_timeout = 600;
   SET GLOBAL interactive_timeout = 600;

Access Denied Errors

Error Message:

MySQL access denied error

java.sql.SQLException: Access denied for user 'username'@'host'

Solutions:

1. Verify User Exists

   Check if the MySQL user exists

   SELECT User, Host FROM mysql.user WHERE User = 'your_username';

2. Grant Proper Permissions

   Grant permissions to the Mirth Connect database user

   GRANT ALL PRIVILEGES ON database_name.* TO 'username'@'%';
   FLUSH PRIVILEGES;

   Security

   Using '%' as the host allows connections from any IP address. In production, restrict this to the specific IP or subnet of your Mirth Connect/OIE server.

3. Check Host Restrictions

   Create users with host restrictions

   -- Allow connections from any host
   CREATE USER 'username'@'%' IDENTIFIED BY 'password';
   
   -- Or restrict to a specific host
   CREATE USER 'username'@'192.168.1.100' IDENTIFIED BY 'password';

MySQL Connection Pool Settings

Recommended MySQL connection pool settings

# Recommended MySQL connection pool settings for Mirth Connect / OIE
initialPoolSize=5
minPoolSize=5
maxPoolSize=20
acquireIncrement=1
maxIdleTime=300

MySQL Server Configuration

/etc/mysql/mysql.conf.d/mysqld.cnf

[mysqld]
max_connections = 200
wait_timeout = 600
interactive_timeout = 600
max_allowed_packet = 64M

Connection Limits

Set max_connections high enough to accommodate your Mirth Connect/OIE connection pool plus other applications. A good rule of thumb: maxPoolSize per Mirth instance multiplied by the number of instances, plus a 20% buffer.

---

SQL Server Troubleshooting

Login Failed

Error Message:

SQL Server login failure

com.microsoft.sqlserver.jdbc.SQLServerException:
Login failed for user 'username'

Solutions:

1. Check Authentication Mode

   Enable mixed mode authentication

   -- Enable mixed mode authentication
   EXEC xp_instance_regwrite N'HKEY_LOCAL_MACHINE',
   N'Software\Microsoft\MSSQLServer\MSSQLServer',
   N'LoginMode', REG_DWORD, 2;

   Restart Required

   After changing the authentication mode, you must restart the SQL Server service for the change to take effect.

2. Enable SQL Server Authentication

   • Open SQL Server Management Studio
   • Right-click server, select Properties, then Security
   • Select “SQL Server and Windows Authentication mode”

3. Create or Modify User

   Create SQL Server login and user for Mirth Connect

   -- Create login
   CREATE LOGIN [username] WITH PASSWORD = 'password';
   
   -- Create user in database
   USE [database_name];
   CREATE USER [username] FOR LOGIN [username];
   
   -- Grant permissions
   ALTER ROLE db_datareader ADD MEMBER [username];
   ALTER ROLE db_datawriter ADD MEMBER [username];

   Permissions

   The db_datareader and db_datawriter roles cover most Mirth Connect/OIE operations. For schema changes during upgrades, the user may also need db_ddladmin.

Connection Timeout

Error Message:

SQL Server timeout error

java.sql.SQLTimeoutException: The connection has timed out

Solutions:

1. Increase Connection Timeout

   JDBC connection string with timeout

   jdbc:sqlserver://server:1433;databaseName=mydb;loginTimeout=30;

2. Check SQL Server Browser Service

   Start SQL Server Browser service

   # Start SQL Server Browser
   net start "SQL Server Browser"

3. Verify Port Configuration

   • Default port: 1433
   • Check SQL Server Configuration Manager
   • Ensure TCP/IP protocol is enabled

SQL Server Connection String Optimization

Optimized SQL Server JDBC connection string

jdbc:sqlserver://server:1433;databaseName=mydb;
selectMethod=cursor;
responseBuffering=adaptive;
loginTimeout=30;
socketTimeout=0;

---

Oracle Troubleshooting

TNS Resolution Error

Error Message:

Oracle TNS resolution error

java.sql.SQLException: ORA-12154:
TNS:could not resolve the connect identifier specified

Solutions:

1. Check TNS Names File

   $ORACLE_HOME/network/admin/tnsnames.ora

   MYDB =
     (DESCRIPTION =
       (ADDRESS = (PROTOCOL = TCP)(HOST = oracle-server)(PORT = 1521))
       (CONNECT_DATA =
         (SERVER = DEDICATED)
         (SERVICE_NAME = ORCL)
       )
     )

2. Use Direct Connection String (bypass TNS)

   Direct Oracle JDBC connection string

   jdbc:oracle:thin:@oracle-server:1521:ORCL

3. Test with SQL*Plus

   Test Oracle connection with SQL*Plus

   sqlplus username/password@oracle-server:1521/ORCL

Listener Not Running

Error Message:

Oracle listener error

ORA-12541: TNS:no listener

Solutions:

1. Start Oracle Listener

   Start and verify Oracle listener

   lsnrctl start

2. Check Listener Status

   Check Oracle listener status

   lsnrctl status

3. Verify Listener Configuration

   $ORACLE_HOME/network/admin/listener.ora

   LISTENER =
     (DESCRIPTION_LIST =
       (DESCRIPTION =
         (ADDRESS = (PROTOCOL = TCP)(HOST = oracle-server)(PORT = 1521))
       )
     )

Oracle Connection Pool Settings

Recommended Oracle connection pool settings

# Oracle-specific connection pool settings for Mirth Connect / OIE
initialPoolSize=3
minPoolSize=3
maxPoolSize=15
acquireIncrement=1
maxIdleTime=1800
testConnectionOnCheckout=true
preferredTestQuery=SELECT 1 FROM DUAL

Connection Testing

Setting testConnectionOnCheckout=true with preferredTestQuery=SELECT 1 FROM DUAL helps detect stale Oracle connections before they cause channel errors. This adds minimal overhead but prevents Connection reset errors.

---

PostgreSQL Troubleshooting

Connection Refused

Error Message:

PostgreSQL connection refused error

org.postgresql.util.PSQLException:
Connection to localhost:5432 refused

Solutions:

1. Check PostgreSQL Status

   Check and start PostgreSQL service

   sudo systemctl status postgresql
   sudo systemctl start postgresql

2. Verify Configuration

   /etc/postgresql/13/main/postgresql.conf

   listen_addresses = '*'
   port = 5432

   Listen Address

   By default, PostgreSQL only listens on localhost. If your Mirth Connect or OIE server is on a different machine, you must change listen_addresses to '*' or the specific network interface, then restart PostgreSQL.

3. Update pg_hba.conf

   /etc/postgresql/13/main/pg_hba.conf

   # Allow connections from the Mirth Connect / OIE server subnet
   host    all             all             0.0.0.0/0               md5

   Security

   The 0.0.0.0/0 CIDR allows connections from any IP. In production, restrict this to the specific IP or subnet of your Mirth Connect/OIE server (e.g., 192.168.1.0/24).

Authentication Failed

Error Message:

PostgreSQL authentication failure

org.postgresql.util.PSQLException:
FATAL: password authentication failed for user "username"

Solutions:

1. Create User

   Create PostgreSQL user for Mirth Connect

   CREATE USER username WITH PASSWORD 'password';
   GRANT ALL PRIVILEGES ON DATABASE database_name TO username;

2. Reset Password

   Reset PostgreSQL user password

   ALTER USER username PASSWORD 'new_password';

---

General Database Best Practices

These practices apply to all database platforms when used with Mirth Connect or OIE.

Connection Pool Configuration

1. Size Appropriately

   • Start with 5-10 connections per Mirth instance
   • Monitor usage and adjust based on peak load
   • Consider the total connection count across all instances

2. Set Timeouts

   • Connection timeout: 30 seconds
   • Query timeout: 60 seconds
   • Idle timeout: 300 seconds

3. Enable Connection Testing

   • Test connections on checkout to detect stale connections
   • Use simple validation queries (SELECT 1 or SELECT 1 FROM DUAL for Oracle)
   • Handle failed connections gracefully with automatic retry

Monitoring and Maintenance

1. Regular Health Checks

   • Monitor connection pool metrics (active, idle, pending counts)
   • Check database server status and availability
   • Review error logs for connection warnings

2. Performance Monitoring

   • Track query execution times — slow queries can bottleneck message processing
   • Monitor connection usage patterns to right-size pool settings
   • Identify and optimize slow queries with EXPLAIN plans

3. Preventive Maintenance

   • Schedule regular database maintenance windows (index rebuilds, statistics updates)
   • Optimize indexes on Mirth Connect message tables, especially d_m* tables
   • Run statistics updates after large message volume changes

Message Pruning

Both Mirth Connect and OIE store message data in the database. Configure message pruning (Settings > Data Pruner) to automatically remove old messages and prevent database growth from degrading performance. A common retention policy is 30 days for production and 7 days for development.

---

Getting Professional Help

When database issues persist or become complex, consider professional support:

• Saga IT Consulting — Expert Mirth Connect, OIE, and database integration support
• Database-Specific Support — Vendor support for your database platform (MySQL, SQL Server, Oracle, PostgreSQL)
• Community Resources — OIE GitHub Issues for open-source community help

Our team has resolved database connectivity issues for healthcare organizations running Mirth Connect and OIE on MySQL, SQL Server, Oracle, and PostgreSQL across AWS, Azure, and on-premise environments.

Contact Saga IT for database integration support | Mirth Connect services | OIE services