Manual Configuration

When zero-config auto-discovery isn't available for your environment, DevDb Pro supports manual configuration via a .devdbrc file.

When to Use Manual Configuration

Use a .devdbrc configuration file when:

• Your environment isn't supported by zero-config
• You have custom database setups
• You need to connect to remote databases
• Your credentials are stored in non-standard locations
• You want to connect to multiple databases explicitly

Configuration File Location

Create a .devdbrc file in your project root (workspace root):

my-project/
├── .devdbrc          ← Configuration file
├── src/
├── package.json
└── ...

File Format

The .devdbrc file is a JSON array of database connection objects:

[
  {
    "name": "My Database",
    "type": "mysql",
    "host": "127.0.0.1",
    "port": "3306",
    "username": "root",
    "password": "secret",
    "database": "myapp"
  }
]

Configuration Helpers

DevDb provides tools to make configuration easy:

JSON Schema Validation

The .devdbrc file has automatic validation:

• Real-time error checking
• Required field indicators
• Type validation

IntelliSense Support

DevDb provides intelligent autocompletion:

• All available fields
• Database types
• Valid values

Snippets

Quick configuration templates:

Snippet	Description
devdb mysql	MySQL configuration
devdb mariadb	MariaDB configuration
devdb postgres	PostgreSQL configuration
devdb sqlite	SQLite configuration
devdb mssql	Microsoft SQL Server configuration

Usage:

1. Create .devdbrc file
2. Type snippet name (e.g., devdb mysql)
3. Press Tab
4. Fill in your credentials

Database-Specific Configuration

MySQL / MariaDB

{
  "name": "My MySQL Database",
  "type": "mysql",
  "host": "127.0.0.1",
  "port": "3306",
  "username": "root",
  "password": "secret",
  "database": "myapp"
}

Optional Fields:

{
  "options": {
    "connectTimeout": 10000,
    "ssl": {
      "rejectUnauthorized": false
    }
  }
}

PostgreSQL

{
  "name": "My PostgreSQL Database",
  "type": "postgres",
  "host": "localhost",
  "port": "5432",
  "username": "postgres",
  "password": "secret",
  "database": "myapp"
}

Optional Fields:

{
  "options": {
    "ssl": true,
    "connectionTimeoutMillis": 5000
  }
}

SQLite

{
  "name": "My SQLite Database",
  "type": "sqlite",
  "path": "/absolute/path/to/database.sqlite"
}

Relative Paths

For portability, use workspace-relative paths:

{
  "type": "sqlite",
  "path": "${workspaceFolder}/database/app.db"
}

Microsoft SQL Server

{
  "name": "My MSSQL Database",
  "type": "mssql",
  "host": "localhost",
  "port": "1433",
  "username": "sa",
  "password": "YourPassword123",
  "database": "master"
}

Common Options:

{
  "options": {
    "trustServerCertificate": true,
    "encrypt": true,
    "instanceName": "SQLEXPRESS"
  }
}

Multiple Connections

Configure multiple databases in a single file:

[
  {
    "name": "Main Database",
    "type": "mysql",
    "host": "127.0.0.1",
    "port": "3306",
    "username": "root",
    "password": "secret",
    "database": "main_db"
  },
  {
    "name": "Analytics Database",
    "type": "postgres",
    "host": "localhost",
    "port": "5432",
    "username": "postgres",
    "password": "secret",
    "database": "analytics"
  },
  {
    "name": "Cache Database",
    "type": "sqlite",
    "path": "${workspaceFolder}/cache.db"
  }
]

All databases appear in the DevDb sidebar.

Environment Variables

Use environment variables for sensitive data:

Using VS Code Variables

{
  "type": "mysql",
  "host": "${env:DB_HOST}",
  "port": "${env:DB_PORT}",
  "username": "${env:DB_USER}",
  "password": "${env:DB_PASSWORD}",
  "database": "${env:DB_NAME}"
}

Supported Variable Patterns

Pattern	Description	Example
${workspaceFolder}	Workspace root path	/path/to/project
${env:VAR_NAME}	Environment variable	${env:DB_HOST}
${env:VAR_NAME:default}	With fallback	${env:DB_HOST:localhost}

Security Best Practices

Don't Commit Credentials

Add .devdbrc to .gitignore:

# .gitignore
.devdbrc

Use Environment Variables

Store credentials in environment variables:

1. Create .env (also in .gitignore):

DB_HOST=127.0.0.1
DB_USER=root
DB_PASSWORD=secret
DB_NAME=myapp

2. Reference in .devdbrc:

{
  "type": "mysql",
  "host": "${env:DB_HOST}",
  "username": "${env:DB_USER}",
  "password": "${env:DB_PASSWORD}",
  "database": "${env:DB_NAME}"
}

Share Configuration Template

Create .devdbrc.example for your team:

[
  {
    "name": "Main Database",
    "type": "mysql",
    "host": "${env:DB_HOST}",
    "port": "3306",
    "username": "${env:DB_USER}",
    "password": "${env:DB_PASSWORD}",
    "database": "${env:DB_NAME}"
  }
]

Commit this and document required environment variables in README.

Remote Databases

SSH Tunnel

For databases behind SSH:

1. Create SSH tunnel first:

ssh -L 3307:localhost:3306 user@remote-server

2. Configure DevDb to use tunnel:

{
  "type": "mysql",
  "host": "127.0.0.1",
  "port": "3307",
  "username": "root",
  "password": "secret",
  "database": "remote_db"
}

VPN Connection

For databases on VPN:

1. Connect to VPN first
2. Use internal host in config:

{
  "type": "postgres",
  "host": "db.internal.company.com",
  "port": "5432",
  "username": "developer",
  "password": "secret",
  "database": "staging"
}

Troubleshooting

Configuration Not Loaded

If .devdbrc isn't detected:

1. Check file location - Must be in workspace root
2. Verify JSON syntax - Use VS Code's JSON validator
3. Reload window - Cmd+Shift+P → "Reload Window"
4. Check DevDb output panel for errors

Connection Fails

If connection doesn't work:

1. Test credentials manually (e.g., mysql -h host -u user -p)
2. Verify database is running
3. Check firewall rules
4. Review connection options

Environment Variables Not Resolved

If ${env:VAR} doesn't work:

1. Verify variable is set: echo $VAR (Unix) or echo %VAR% (Windows)
2. Restart VS Code after setting env vars
3. Use .env file and a dotenv extension
4. Check variable name spelling

Validation Errors

If you see validation errors:

1. Read error message - It indicates what's wrong
2. Check required fields for the database type
3. Verify field types (strings, numbers, etc.)
4. Use snippets for correct structure

Advanced Configuration

Connection Pooling

Configure connection pool options:

{
  "type": "mysql",
  "host": "127.0.0.1",
  "username": "root",
  "password": "secret",
  "database": "myapp",
  "options": {
    "connectionLimit": 10,
    "queueLimit": 0,
    "waitForConnections": true
  }
}

SSL Connections

For secure connections:

PostgreSQL:

{
  "type": "postgres",
  "host": "secure-db.example.com",
  "username": "user",
  "password": "secret",
  "database": "myapp",
  "options": {
    "ssl": {
      "rejectUnauthorized": true,
      "ca": "/path/to/ca-cert.pem"
    }
  }
}

MySQL:

{
  "type": "mysql",
  "host": "secure-db.example.com",
  "username": "user",
  "password": "secret",
  "database": "myapp",
  "options": {
    "ssl": {
      "ca": "/path/to/ca-cert.pem"
    }
  }
}

Read-Only Connections

For safe production inspection:

{
  "name": "Production (Read-Only)",
  "type": "mysql",
  "host": "prod-db.example.com",
  "username": "readonly_user",
  "password": "secret",
  "database": "production",
  "options": {
    "readOnly": true
  }
}

Configuration Schema

Full field reference:

Common Fields (All Types)

Field	Type	Required	Description
name	string	No	Connection display name
type	string	Yes	Database type
options	object	No	Database-specific options

MySQL/MariaDB/PostgreSQL/MSSQL

Field	Type	Required	Description
host	string	Yes	Database host
port	string/number	Yes	Database port
username	string	Yes	Database user
password	string	Yes	User password
database	string	Yes	Database name

SQLite

Field	Type	Required	Description
path	string	Yes	Path to database file

Next Steps

• Supported Databases - Database compatibility
• Zero-Config Discovery - Auto-configuration
• Database Client - Using the interface