Database Configuration

The database section configures the database connection. Code Search supports both PostgreSQL and MySQL.

Configuration

PostgreSQL

database:
  driver: "postgres"  # Optional - auto-detected from URL
  url: "postgres://user:password@localhost:5432/codesearch?sslmode=disable"
  max_open_conns: 25
  max_idle_conns: 5
  conn_max_lifetime: "5m"

MySQL

database:
  driver: "mysql"  # Optional - auto-detected from URL
  url: "mysql://user:password@localhost:3306/codesearch"
  max_open_conns: 25
  max_idle_conns: 5
  conn_max_lifetime: "5m"

Options

driver

Database driver type. If not specified, it’s auto-detected from the URL.

Property	Value
Type	string
Required	No (auto-detected)
Values	postgres, mysql
Environment	CS_DATABASE_DRIVER

url

Database connection string.

Property	Value
Type	string
Required	Yes
Environment	CS_DATABASE_URL

PostgreSQL

Format:

postgres://[user[:password]@]host[:port]/database[?param=value]

Examples:

# Local development
url: "postgres://codesearch:secret@localhost:5432/codesearch?sslmode=disable"

# Docker Compose
url: "postgres://codesearch:secret@postgres:5432/codesearch?sslmode=disable"

# Cloud (with SSL)
url: "postgres://user:[email protected]:5432/codesearch?sslmode=require"

# With connection options
url: "postgres://user:pass@host:5432/db?sslmode=verify-full&sslrootcert=/path/to/ca.pem"

MySQL

URL Format:

mysql://[user[:password]@]host[:port]/database[?param=value]

DSN Format (also supported):

user:password@tcp(host:port)/database?parseTime=true

Examples:

# URL format (recommended)
url: "mysql://codesearch:secret@localhost:3306/codesearch"

# With options
url: "mysql://codesearch:secret@localhost:3306/codesearch?charset=utf8mb4&parseTime=true"

# DSN format
url: "codesearch:secret@tcp(localhost:3306)/codesearch?parseTime=true"

# Docker Compose
url: "mysql://codesearch:secret@mysql:3306/codesearch"

# Cloud (AWS RDS, etc.)
url: "mysql://user:[email protected]:3306/codesearch?tls=true"

Tip

Always include parseTime=true for proper timestamp handling in MySQL.

Tip

Always use environment variables for the database URL in production to avoid exposing credentials in configuration files.

max_open_conns

Maximum number of open connections to the database.

Property	Value
Type	integer
Default	25
Environment	CS_DATABASE_MAX_OPEN_CONNS

Set this based on your PostgreSQL max_connections setting and number of Code Search instances.

max_idle_conns

Maximum number of idle connections to keep in the pool.

Property	Value
Type	integer
Default	5
Environment	CS_DATABASE_MAX_IDLE_CONNS

conn_max_lifetime

Maximum lifetime of a connection before it’s closed and recreated.

Property	Value
Type	duration
Default	"5m"
Environment	CS_DATABASE_CONN_MAX_LIFETIME

SSL/TLS Configuration

PostgreSQL

PostgreSQL supports several SSL modes:

Mode	Description
disable	No SSL
allow	Use SSL if available
prefer	Prefer SSL, but connect without if unavailable
require	Require SSL connection
verify-ca	Require SSL and verify server certificate
verify-full	Require SSL, verify certificate and hostname

Production recommendation: Use require or verify-full.

MySQL

MySQL TLS options:

Parameter	Description
tls=true	Enable TLS
tls=skip-verify	TLS without certificate verification
tls=preferred	Use TLS if available

Example:

url: "mysql://user:pass@host:3306/db?tls=true"

Production recommendation: Use tls=true with proper certificates.

Environment Variables

# Driver (optional - auto-detected from URL)
CS_DATABASE_DRIVER="postgres"  # or "mysql"

# Connection string
CS_DATABASE_URL="postgres://user:pass@host:5432/codesearch?sslmode=require"
# or for MySQL:
# CS_DATABASE_URL="mysql://user:pass@host:3306/codesearch?parseTime=true"

# Connection pool settings
CS_DATABASE_MAX_OPEN_CONNS="25"
CS_DATABASE_MAX_IDLE_CONNS="5"
CS_DATABASE_CONN_MAX_LIFETIME="5m"

Database Requirements

PostgreSQL

Code Search requires PostgreSQL 14 or later.

Required Extensions

No additional extensions are required. All functionality uses standard PostgreSQL features.

Recommended Settings

For production PostgreSQL servers:

# postgresql.conf
max_connections = 100           # Adjust based on number of Code Search instances
shared_buffers = 256MB          # 25% of available RAM (up to 8GB)
effective_cache_size = 768MB    # 75% of available RAM
work_mem = 64MB
maintenance_work_mem = 128MB

MySQL

Code Search requires MySQL 8.0 or later (or MariaDB 10.5+).

Required Settings

Ensure these settings in your MySQL configuration:

# my.cnf
[mysqld]
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
max_connections = 100
innodb_buffer_pool_size = 256M

Character Set

Code Search uses utf8mb4 for full Unicode support. Ensure your database is created with:

CREATE DATABASE codesearch
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

Connection Pooling

For high-traffic deployments, consider using a connection pooler:

PostgreSQL (PgBouncer)

database:
  # Connect to PgBouncer instead of PostgreSQL directly
  url: "postgres://user:pass@pgbouncer:6432/codesearch"
  max_open_conns: 100  # Can be higher with connection pooling

MySQL (ProxySQL)

database:
  # Connect to ProxySQL instead of MySQL directly
  url: "mysql://user:pass@proxysql:6033/codesearch"
  max_open_conns: 100  # Can be higher with connection pooling

Database Schema

Code Search manages its own database schema using migrations. Migrations run automatically on startup.

Tables created:

• repos - Repository metadata
• connections - Code host connections
• jobs - Background job queue
• schema_migrations - Migration tracking

Troubleshooting

Connection refused

failed to connect to database: connection refused

• Verify the database server is running
• Check host and port are correct
• Ensure the database is listening on the correct interface

Authentication failed

PostgreSQL

password authentication failed for user

• Verify username and password
• Check PostgreSQL pg_hba.conf allows connections from Code Search

MySQL

Access denied for user

• Verify username and password
• Check user has correct privileges:

  GRANT ALL PRIVILEGES ON codesearch.* TO 'user'@'%';
  FLUSH PRIVILEGES;

SSL required

PostgreSQL

SSL is required

Add sslmode=require or sslmode=disable to your connection string.

MySQL

TLS required

Add tls=true or tls=skip-verify to your connection string.

Driver auto-detection

Code Search automatically detects the database driver from the URL:

URL Pattern	Detected Driver
postgres://...	PostgreSQL
postgresql://...	PostgreSQL
mysql://...	MySQL
...@tcp(...)...	MySQL (DSN format)

If auto-detection fails, explicitly set driver: postgres or driver: mysql.