Connection Issues

Troubleshoot database connection problems and network errors.

Cannot Connect to Database

Symptom

Error messages like: * "Connection refused" * "Connection timed out" * "Unknown host" * "Authentication failed"

Diagnosis

Test connection manually:

# PostgreSQL
psql -h hostname -p 5432 -U username -d database

# MySQL
mysql -h hostname -P 3306 -u username -p database

Common Solutions

  1. Verify database is running:

# PostgreSQL
pg_isready -h hostname -p 5432

# MySQL
mysqladmin ping -h hostname

  1. Check connection string:

# Correct format
url: jdbc:postgresql://hostname:5432/database

# Common mistakes
# ❌ Missing port
url: jdbc:postgresql://hostname/database

# ❌ Wrong protocol
url: jdbc:postgres://hostname:5432/database

  1. Test from platform container:

docker compose exec backend bash
# Then test connection from inside container
ping database-host
telnet database-host 5432

Authentication Failed

Symptom

"Access denied", "Authentication failed", "Invalid credentials".

Solutions

  1. Verify credentials:

# Test credentials directly
psql -h host -U username -d database
# Enter password when prompted

  1. Check password special characters:

# Escape special characters in YAML
password: "p@ssw0rd!"  # Use quotes

  1. Verify user permissions:

-- PostgreSQL
SELECT * FROM pg_user WHERE usename = 'tdk_user';

-- MySQL
SHOW GRANTS FOR 'tdk_user'@'%';

Network Timeout

Symptom

Connection attempts time out after 30-60 seconds.

Solutions

  1. Check firewall rules:

# Test port accessibility
telnet database-host 5432
nc -zv database-host 5432

  1. Verify security groups (Cloud):

    • AWS: Check RDS security groups

    • GCP: Check Cloud SQL authorized networks

    • Azure: Check firewall rules

  2. Increase timeout:

data_sources:
  input:
    url: jdbc:postgresql://host:5432/db?connectTimeout=60

SSL/TLS Issues

Symptom

"SSL connection required", "Certificate validation failed".

Solutions

  1. Enable SSL in connection string:

# PostgreSQL
url: jdbc:postgresql://host:5432/db?ssl=true&sslmode=require

# MySQL
url: jdbc:mysql://host:3306/db?useSSL=true

  1. Disable certificate validation (development only):

# PostgreSQL
url: jdbc:postgresql://host:5432/db?ssl=true&sslmode=require&sslrootcert=/dev/null

# MySQL
url: jdbc:mysql://host:3306/db?useSSL=true&requireSSL=false

  1. Provide certificate:

url: jdbc:postgresql://host:5432/db?ssl=true&sslrootcert=/path/to/ca.crt

Connection Pool Exhausted

Symptom

"Unable to acquire JDBC connection", "Connection pool exhausted".

Solution

Increase connection pool size:

spring.datasource.hikari.maximum-pool-size=20
spring.datasource.hikari.minimum-idle=5

See Also