Database Configuration Guide

MySQLens supports saving database connection configurations so you don’t have to enter credentials every time.

📁 Configuration File

The database connections are stored in db-config.json at the project root.

⚠️ Security Note

db-config.json is automatically added to .gitignore to prevent committing credentials
This file contains passwords in plaintext on disk (use appropriate file permissions)
For production, consider using environment variables or secret management tools

🚀 Quick Start

Option 1: Manual Configuration

Copy the example file:

cp db-config.example.json db-config.json

Edit db-config.json with your database credentials:

{
  "connections": [
 {
   "name": "Production MySQL",
   "host": "your-mysql-host.com",
   "port": 3306,
   "user": "cdc_user",
   "password": "your_password_here",
   "database": "mysql",
   "is_default": true
 }
  ],
  "auto_connect": false
}

Start Docker Compose:
```
docker compose up -d
```

The db-config.json file is automatically mounted into the backend container.

Option 2: UI Configuration (Recommended)

Start the application:
```
docker compose up -d
```
Open http://localhost:3000
Enter your database credentials in the connection form
Click “Save Connection” (button will be added in UI)
The connection will be saved to db-config.json automatically

📊 Configuration Format

{
  "connections": [
    {
      "name": "Connection Name",         // Friendly name for this connection
      "host": "mysql-host.example.com",  // MySQL host (IP or hostname)
      "port": 3306,                      // MySQL port (default: 3306)
      "user": "mysql_user",              // MySQL username
      "password": "secret_password",      // MySQL password (stored plaintext)
      "database": "database_name",       // Default database to connect to
      "is_default": true                 // If true, this connection loads by default
    }
  ],
  "auto_connect": false                  // If true, auto-connects on startup
}

Multiple Connections

You can save multiple connections:

{
  "connections": [
    {
      "name": "Production",
      "host": "prod-mysql.example.com",
      "port": 3306,
      "user": "prod_user",
      "password": "prod_password",
      "database": "prod_db",
      "is_default": true
    },
    {
      "name": "Staging",
      "host": "staging-mysql.example.com",
      "port": 3306,
      "user": "staging_user",
      "password": "staging_password",
      "database": "staging_db",
      "is_default": false
    },
    {
      "name": "Development",
      "host": "localhost",
      "port": 3306,
      "user": "dev_user",
      "password": "dev_password",
      "database": "dev_db",
      "is_default": false
    }
  ],
  "auto_connect": true
}

🔌 API Endpoints

MySQLens provides API endpoints to manage saved connections:

Get All Saved Connections

GET /api/connection/saved

Returns all saved connections (without passwords).

Get Specific Connection

GET /api/connection/saved/{name}

Returns a specific saved connection (without password).

Save Connection

POST /api/connection/save?name=MyConnection&set_as_default=true
Content-Type: application/json

{
  "host": "mysql-host.example.com",
  "port": 3306,
  "user": "mysql_user",
  "password": "password",
  "database": "database_name"
}

Delete Connection

DELETE /api/connection/saved/{name}

Connect Using Saved Connection

POST /api/connection/connect-saved/{name}

Connects to MySQL using a saved connection.

🔒 Security Best Practices

File Permissions

Set restrictive permissions on db-config.json:

# Linux/Mac
chmod 600 db-config.json

# This ensures only the file owner can read/write

Environment Variables (Recommended for Production)

Instead of storing passwords in db-config.json, use environment variables:

Create connections without passwords in db-config.json:

{
  "connections": [
 {
   "name": "Production",
   "host": "${MYSQL_HOST}",
   "port": 3306,
   "user": "${MYSQL_USER}",
   "password": "${MYSQL_PASSWORD}",
   "database": "${MYSQL_DATABASE}",
   "is_default": true
 }
  ]
}

Set environment variables in .env:

MYSQL_HOST=prod-mysql.example.com
MYSQL_USER=prod_user
MYSQL_PASSWORD=secret_password
MYSQL_DATABASE=prod_db

Docker Secrets (Production)

For production deployments, use Docker secrets:

services:
  mysqlens-api:
    secrets:
      - mysql_password
    environment:
      - MYSQL_PASSWORD_FILE=/run/secrets/mysql_password

secrets:
  mysql_password:
    external: true

🔄 Auto-Connect on Startup

To automatically connect to the default database when the container starts:

Set "auto_connect": true in db-config.json
Set "is_default": true on your preferred connection
Restart the containers:
```
docker compose restart
```

The application will automatically connect to the default database on startup.

🐳 Docker Configuration

The docker compose.yml automatically mounts db-config.json:

volumes:
  - ./backend:/app
  - api_cache:/app/cache
  - ./db-config.json:/app/db-config.json  # ← Config file mounted here

Changes to db-config.json are immediately available to the container (no rebuild needed).

📝 Example Configurations

Remote RDS Connection

{
  "connections": [
    {
      "name": "AWS RDS Production",
      "host": "my-db.abc123.us-east-1.rds.amazonaws.com",
      "port": 3306,
      "user": "admin",
      "password": "my_rds_password",
      "database": "production",
      "is_default": true
    }
  ],
  "auto_connect": false
}

Local Development

{
  "connections": [
    {
      "name": "Local MySQL",
      "host": "host.docker.internal",
      "port": 3306,
      "user": "root",
      "password": "root",
      "database": "test",
      "is_default": true
    }
  ],
  "auto_connect": true
}

CDC User (Binlog Access)

{
  "connections": [
    {
      "name": "CDC User Connection",
      "host": "mysql-host.example.com",
      "port": 3306,
      "user": "cdc_user",
      "password": "cdc_password",
      "database": "mysql",
      "is_default": true
    }
  ],
  "auto_connect": false
}

🔧 Troubleshooting

Connection Saved But Not Loading

Check file permissions:
```
ls -la db-config.json
```
Check JSON syntax:
```
cat db-config.json | jq .
```
Check Docker logs:
```
docker compose logs -f mysqlens-api
```

File Not Found Error

Make sure db-config.json exists in the project root:

ls -la db-config.json

If missing, create from example:

cp db-config.example.json db-config.json

Passwords Not Working

Ensure special characters in passwords are properly escaped in JSON
Use double quotes, not single quotes
Escape backslashes: "my\\password"
Escape double quotes: "my\"password"

🎯 Next Steps

Start simple: Save one connection and test it
Add multiple environments: Production, staging, development
Enable auto-connect: For frequently used connections
Secure the file: Set proper file permissions
Regular backups: Keep backup of db-config.json (without committing to git)

📞 Support

If you have issues with database configuration:

Check the README for general setup
Review Deployment Guide for production tips
Open an issue: https://github.com/a-kash-singh/mysqlens/issues

**Built with 🔍 for better MySQL performance** ← Back to Home