# Connection Issues

> Source: https://docs.synthesized.io/tdk/latest/user_guide/080_troubleshooting/common_issues/connection
> For the complete documentation index, see [llms.txt](https://docs.synthesized.io/llms.txt).

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:

```shell
# 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**:

```shell
# PostgreSQL
pg_isready -h hostname -p 5432

# MySQL
mysqladmin ping -h hostname
```

1. **Check connection string**:

```yaml
# 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**:

```shell
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**:

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

1. **Check password special characters**:

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

1. **Verify user permissions**:

```sql
-- 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**:

```shell
# 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**:

```yaml
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**:

```yaml
# 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):

```yaml
# 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**:

```yaml
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:

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

## See Also

- [Diagnostic Command](https://docs.synthesized.io/tdk/latest/user_guide/080_troubleshooting/debugging/diagnostic_command)
- [Database Configuration](https://docs.synthesized.io/tdk/latest/user_guide/070_integrations/databases/)
- [Inventory Configuration](https://docs.synthesized.io/tdk/latest/user_guide/040_reference/data_types/inventory)