Rustelo/docs/database_configuration.md

Database Configuration Guide

This application supports both PostgreSQL and SQLite databases through SQLx's unified interface. The database type is automatically detected based on the connection URL.

Quick Start

SQLite (Recommended for Development)

[database]
url = "sqlite:database.db"

PostgreSQL (Recommended for Production)

[database]
url = "postgresql://username:password@localhost:5432/database_name"

Database URL Formats

SQLite URLs

• sqlite:database.db - Relative path to database file
• sqlite:///path/to/database.db - Absolute path to database file
• sqlite::memory: - In-memory database (testing only)

PostgreSQL URLs

• postgresql://user:password@host:port/database
• postgres://user:password@host:port/database

Environment Variables

You can override the database URL using environment variables:

export DATABASE_URL="sqlite:my_database.db"
# or
export DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"

Database-Specific Features

SQLite

• Pros:

  • Zero configuration setup
  • Single file database
  • Perfect for development and testing
  • No separate server process required
  • ACID compliant

• Cons:

  • Limited concurrent writes
  • No network access
  • Fewer advanced features
  • File-based storage

PostgreSQL

• Pros:

  • Full ACID compliance
  • Excellent concurrent access
  • Advanced features (JSONB, arrays, etc.)
  • Network accessible
  • Production-ready scalability

• Cons:

  • Requires PostgreSQL server
  • More complex setup
  • Resource overhead

Configuration Examples

Development Configuration

# config.dev.toml
[database]
url = "sqlite:dev_database.db"
max_connections = 5
min_connections = 1
connect_timeout = 30
idle_timeout = 300
max_lifetime = 1800

Production Configuration

# config.prod.toml
[database]
url = "postgresql://prod_user:${DATABASE_PASSWORD}@db.example.com:5432/prod_database"
max_connections = 20
min_connections = 5
connect_timeout = 30
idle_timeout = 600
max_lifetime = 3600

Connection Pool Settings

Setting	Description	SQLite	PostgreSQL
max_connections	Maximum pool size	1 (recommended)	10-50
min_connections	Minimum pool size	1	1-5
connect_timeout	Connection timeout (seconds)	30	30
idle_timeout	Idle connection timeout (seconds)	300	600
max_lifetime	Maximum connection lifetime (seconds)	1800	3600

Database Setup

SQLite Setup

No setup required! The database file will be created automatically when the application starts.

PostgreSQL Setup

Using Docker

# Start PostgreSQL container
docker run -d \
  --name postgres \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=myapp \
  -p 5432:5432 \
  postgres:15

# Connect to database
docker exec -it postgres psql -U postgres -d myapp

Using Local Installation

macOS (Homebrew):

brew install postgresql
brew services start postgresql
createdb myapp

Ubuntu/Debian:

sudo apt-get install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo -u postgres createdb myapp

Migration Support

The application automatically creates the necessary tables for both database types:

SQLite Tables

• Uses TEXT for IDs (UUID format)
• Uses DATETIME for timestamps
• Uses TEXT for JSON storage
• Uses BOOLEAN for boolean values

PostgreSQL Tables

• Uses UUID for IDs with gen_random_uuid()
• Uses TIMESTAMPTZ for timestamps
• Uses JSONB for JSON storage
• Uses BOOLEAN for boolean values

Switching Between Databases

You can switch between databases by simply changing the DATABASE_URL:

# Switch to SQLite
export DATABASE_URL="sqlite:database.db"

# Switch to PostgreSQL
export DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"

The application will automatically:

1. Detect the database type
2. Use appropriate SQL syntax
3. Create compatible table schemas
4. Handle data type differences

Performance Considerations

SQLite

• Best for:

  • Single-user applications
  • Development and testing
  • Small to medium datasets
  • Read-heavy workloads

• Optimization tips:

  • Use WAL mode: PRAGMA journal_mode=WAL
  • Set appropriate timeout: PRAGMA busy_timeout=5000
  • Use transactions for bulk operations

PostgreSQL

• Best for:

  • Multi-user applications
  • Production environments
  • Large datasets
  • High concurrency requirements

• Optimization tips:

  • Configure appropriate connection pool size
  • Use indexes on frequently queried columns
  • Monitor and tune PostgreSQL configuration
  • Use connection pooling (PgBouncer) for high traffic

Troubleshooting

Common SQLite Issues

• Database locked: Check for long-running transactions
• File permissions: Ensure write access to database file and directory
• Disk space: Verify sufficient disk space for database growth

Common PostgreSQL Issues

• Connection refused: Check PostgreSQL server status
• Authentication failed: Verify username/password and pg_hba.conf
• Too many connections: Adjust max_connections or use connection pooling

Debug Connection Issues

# Test SQLite connection
sqlite3 database.db "SELECT 1;"

# Test PostgreSQL connection
psql "postgresql://user:pass@localhost:5432/mydb" -c "SELECT 1;"

Environment-Specific Configuration

Development

# .env.development
DATABASE_URL=sqlite:dev_database.db

Testing

# .env.test
DATABASE_URL=sqlite::memory:

Production

# .env.production
DATABASE_URL=postgresql://user:${DATABASE_PASSWORD}@db.internal:5432/prod_db

Security Considerations

SQLite Security

• Protect database file permissions (600 or 640)
• Backup database files securely
• Consider encryption for sensitive data

PostgreSQL Security

• Use strong passwords
• Enable SSL/TLS connections
• Restrict network access
• Regular security updates
• Use connection pooling with authentication

Backup and Recovery

SQLite Backup

# Simple file copy
cp database.db database_backup.db

# Using SQLite backup command
sqlite3 database.db ".backup database_backup.db"

PostgreSQL Backup

# Database dump
pg_dump myapp > myapp_backup.sql

# Restore from dump
psql myapp < myapp_backup.sql

Monitoring and Maintenance

SQLite Maintenance

-- Analyze database
ANALYZE;

-- Vacuum database
VACUUM;

-- Check integrity
PRAGMA integrity_check;

PostgreSQL Maintenance

-- Analyze tables
ANALYZE;

-- Vacuum tables
VACUUM;

-- Check database size
SELECT pg_size_pretty(pg_database_size('myapp'));

Best Practices

1. Use environment variables for database URLs in production
2. Configure appropriate connection pools based on your workload
3. Monitor database performance and adjust settings as needed
4. Regular backups are essential for production databases
5. Test migrations on both database types if supporting both
6. Use transactions for data consistency
7. Index frequently queried columns for better performance
8. Monitor connection pool usage to prevent exhaustion

Feature Compatibility Matrix

Feature	SQLite	PostgreSQL
ACID Transactions	✅	✅
Concurrent Reads	✅	✅
Concurrent Writes	⚠️ Limited	✅
JSON Support	✅ (TEXT)	✅ (JSONB)
Full-text Search	✅ (FTS)	✅ (Built-in)
Network Access	❌	✅
Replication	❌	✅
Partitioning	❌	✅
Custom Functions	✅	✅
Triggers	✅	✅
Views	✅	✅
Stored Procedures	❌	✅

This guide should help you choose and configure the right database for your needs. Both options are fully supported and the application will work seamlessly with either choice.