Fix Mideye Database Connection Issues (MySQL/MSSQL)

Database connectivity problems prevent Mideye Server from starting or cause runtime failures. This guide covers common database issues and their resolution.

Overview

Mideye Server requires a database to store configuration, user tokens, authentication logs, and operational data. Connection failures during startup prevent the service from running, while runtime failures can cause authentication to fail.

Supported Databases:

• MariaDB (primary/recommended)
• MySQL
• Microsoft SQL Server

Common Error Messages

Error Message	Likely Cause
”Communications link failure”	Cannot connect to database server
”Connection refused”	Database not listening on configured port
”Access denied for user”	Invalid database credentials
”Unknown database”	Database doesn’t exist
”Waiting for changelog lock”	Database migration lock stuck
”Connection is not available”	Connection pool exhausted

---

Common Issues

1. Database Not Running

Symptoms:

• “Connection refused” errors
• “Communications link failure” errors
• Mideye Server fails to start

Diagnostic Steps:

Linux:

# Check database service status
systemctl status mariadb     # MariaDB
systemctl status mysql       # MySQL

# Check if database is listening
ss -tlnp | grep 3306        # MariaDB/MySQL
ss -tlnp | grep 1433        # SQL Server

Windows (PowerShell):

# Check database service
Get-Service *mysql*
Get-Service *mariadb*
Get-Service MSSQLSERVER

# Check if database is listening
Test-NetConnection -ComputerName localhost -Port 3306

Solution:

1. Start the database service:

   Linux:

   sudo systemctl start mariadb
   sudo systemctl enable mariadb    # Start on boot

   Windows:

   Start-Service MSSQLSERVER
   Set-Service MSSQLSERVER -StartupType Automatic

2. Test database connection:

   Linux:

   mysql -h localhost -u root -p mideyeserver

3. Restart Mideye Server:

   Linux:

   sudo systemctl restart mideyeserver6

   Windows:

   Restart-Service MideyeServer6

---

2. Invalid Database Credentials

Symptoms:

• “Access denied for user” errors
• Service fails to start immediately (not after timeout)

Diagnostic Steps:

1. Test credentials manually:

   mysql -h localhost -u root -p mideyeserver

2. Check configured credentials:

   sudo cat /opt/mideyeserver6/config/application-prod.yml | grep -A 5 datasource

   Caution

   Configuration file contains passwords. Handle securely.

Solution:

1. Update password in the application configuration file if it was changed in the database

2. If using special characters in the password, wrap it in single quotes in the configuration file: password: 'P@ssw0rd!'

3. Grant necessary permissions:

   GRANT ALL PRIVILEGES ON mideyeserver.* TO 'root'@'localhost';
   FLUSH PRIVILEGES;

4. Restart Mideye Server

---

3. Database Does Not Exist

Symptoms:

• “Unknown database” error
• Service fails to start
• Migration errors

Solution:

1. Create the database:

   -- MariaDB/MySQL
   CREATE DATABASE mideyeserver CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   
   -- SQL Server
   CREATE DATABASE mideyeserver;

2. Grant permissions:

   GRANT ALL PRIVILEGES ON mideyeserver.* TO 'root'@'localhost';
   FLUSH PRIVILEGES;

3. Restart Mideye Server — database tables will be created automatically

---

4. Database Migration Lock Stuck

Problem: Migration lock is held from a previous failed startup, preventing new migrations.

Symptoms:

• “Waiting for changelog lock” in logs
• Service startup hangs
• Cannot restart service successfully

Diagnostic Steps:

SELECT * FROM DATABASECHANGELOGLOCK;

If LOCKED = 1 and no Mideye Server process is running, the lock is stuck.

Solution:

1. Ensure Mideye Server is stopped:

   Linux:

   sudo systemctl stop mideyeserver6

   Windows:

   Stop-Service MideyeServer6

2. Release the lock:

   UPDATE DATABASECHANGELOGLOCK SET LOCKED=0, LOCKGRANTED=NULL, LOCKEDBY=NULL WHERE ID=1;

   Only release the lock if you are absolutely certain no migration is running!

3. Start Mideye Server:

   Linux:

   sudo systemctl start mideyeserver6

   Windows:

   Start-Service MideyeServer6

4. Monitor logs for successful startup

---

5. Network Connectivity to Remote Database

Problem: Database is on a remote server and network connectivity is an issue.

Symptoms:

• Works with localhost database, fails with remote
• “Connection timed out” errors
• Intermittent connectivity

Diagnostic Steps:

Linux:

# Test connectivity
nc -zv databaseserver.domain.com 3306

# Measure latency
time mysql -h databaseserver.domain.com -u root -p -e "SELECT 1"

Windows:

Test-NetConnection -ComputerName databaseserver.domain.com -Port 3306

Solution:

1. Allow database port through firewalls between Mideye Server and the database server

2. Ensure the database is configured to accept remote connections:

   # MariaDB/MySQL: check bind-address
   sudo grep bind-address /etc/mysql/mariadb.conf.d/*.cnf

   Change 127.0.0.1 to 0.0.0.0 for remote access.

3. Grant remote access for the database user:

   GRANT ALL PRIVILEGES ON mideyeserver.* TO 'root'@'mideyeserver-ip' IDENTIFIED BY 'password';
   FLUSH PRIVILEGES;

---

6. Connection Pool Exhaustion

Problem: All database connections are in use, causing new requests to fail.

Symptoms:

• “Connection is not available” errors
• Service becomes unresponsive under load
• Works initially then fails during peak usage

Solution:

1. Check current database connections:

   -- MariaDB/MySQL
   SHOW STATUS LIKE 'Threads_connected';
   SHOW VARIABLES LIKE 'max_connections';

2. Increase the database server’s max connections if needed:

   SET GLOBAL max_connections = 500;

3. Review the connection pool settings in the application configuration file and increase pool size if needed

4. Restart Mideye Server

---

7. Database Character Encoding Issues

Problem: Special characters (å, ä, ö, é, etc.) appear corrupted.

Symptoms:

• Usernames with special characters appear as garbage
• “Incorrect string value” errors

Diagnostic Steps:

-- Check database character set
SHOW VARIABLES LIKE 'character_set%';
SHOW VARIABLES LIKE 'collation%';

SELECT DEFAULT_CHARACTER_SET_NAME, DEFAULT_COLLATION_NAME
FROM INFORMATION_SCHEMA.SCHEMATA
WHERE SCHEMA_NAME = 'mideyeserver';

Solution:

Use UTF8MB4 for the database:

-- New database
CREATE DATABASE mideyeserver
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

-- Existing database
ALTER DATABASE mideyeserver
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

See also Character Encoding Issues.

---

Verification and Testing

After resolving database issues:

1. Verify service starts — Check service status
2. Check application logs — Look for database-related errors via Log Files
3. Test authentication — Verify authentication operations work
4. Check authentication logs — Ensure logs are being written to the database via Authentication Logs

---

Getting Help

If database issues persist:

1. Collect diagnostic information:

   • Database type and version
   • Error messages from logs
   • Database service status
   • Network connectivity test results

2. Sanitize configuration (remove passwords)

3. Contact Mideye Support with collected information