Rustelo/docs/quick-database-setup.md

Quick Database Setup Guide

This guide shows you how to use both PostgreSQL and SQLite with your Rust application. The application automatically detects the database type based on the URL you provide.

TL;DR - Quick Start

For SQLite (Zero Setup)

export DATABASE_URL="sqlite:database.db"
cargo run --bin server

For PostgreSQL (Docker)

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

# Set URL
export DATABASE_URL="postgresql://postgres:password@localhost:5432/postgres"
cargo run --bin server

Database URL Formats

SQLite URLs

• sqlite:database.db - Creates database.db in current directory
• sqlite:///tmp/database.db - Absolute path
• sqlite::memory: - In-memory database (for testing)

PostgreSQL URLs

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

Configuration Files

The application uses TOML configuration files where you can set the database URL:

config.toml (Default)

[database]
url = "sqlite:database.db"  # Change this line for different databases
max_connections = 10

Environment Variables (Recommended)

# Override any config file setting
export DATABASE_URL="sqlite:my_app.db"
# or
export DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"

Setup Instructions

SQLite Setup

No setup required! Just set the URL and run:

export DATABASE_URL="sqlite:my_app.db"
cargo run --bin server

The database file will be created automatically when the application starts.

PostgreSQL Setup

Option 1: Docker (Recommended)

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

# Wait a moment for startup, then set URL
export DATABASE_URL="postgresql://postgres:mypassword@localhost:5432/myapp"
cargo run --bin server

Option 2: Local Installation

macOS (Homebrew):

brew install postgresql
brew services start postgresql
createdb myapp
export DATABASE_URL="postgresql://$(whoami)@localhost:5432/myapp"

Ubuntu/Debian:

sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo -u postgres createdb myapp
export DATABASE_URL="postgresql://postgres@localhost:5432/myapp"

Development Workflow

Use Different Databases for Different Environments

Development (SQLite):

export DATABASE_URL="sqlite:dev.db"
cargo run --bin server

Testing (In-memory):

export DATABASE_URL="sqlite::memory:"
cargo test

Production (PostgreSQL):

export DATABASE_URL="postgresql://user:pass@db-server:5432/prod_db"
cargo run --bin server --release

Switching Between Databases

You can switch databases at any time by changing the DATABASE_URL:

# Start with SQLite
export DATABASE_URL="sqlite:test.db"
cargo run --bin server

# Stop the server (Ctrl+C), then switch to PostgreSQL
export DATABASE_URL="postgresql://localhost:5432/mydb"
cargo run --bin server

The application will automatically:

• Detect the database type
• Create appropriate tables
• Use correct SQL syntax for each database

Common Commands

SQLite Commands

# Connect to database
sqlite3 database.db

# Check tables
.tables

# Query users
SELECT * FROM users;

# Exit
.quit

PostgreSQL Commands

# Connect to database
psql "postgresql://user:pass@localhost:5432/mydb"

# List tables
\dt

# Query users
SELECT * FROM users;

# Exit
\q

Troubleshooting

SQLite Issues

Permission Denied:

# Make sure directory is writable
chmod 755 .
chmod 644 database.db  # if file exists

Database Locked:

• Close any other connections to the database
• Make sure no other instances of your app are running

PostgreSQL Issues

Connection Refused:

# Check if PostgreSQL is running
docker ps  # for Docker
brew services list | grep postgres  # for Homebrew
sudo systemctl status postgresql  # for Linux

Authentication Failed:

# Check username/password in URL
# For Docker, use the password you set in POSTGRES_PASSWORD
# For local install, might need to check pg_hba.conf

General Database Issues

Tables Not Created: The application automatically creates tables on startup. If you're having issues:

1. Check the logs for error messages
2. Ensure the database user has CREATE privileges
3. For PostgreSQL, make sure the database exists

Environment Variable Not Working:

# Check if variable is set
echo $DATABASE_URL

# Make sure you're in the same terminal session where you set it
# Or add it to your shell profile (.bashrc, .zshrc, etc.)
export DATABASE_URL="sqlite:database.db"

Performance Considerations

SQLite

• Good for: Single-user apps, development, testing, small datasets
• Limitations: One writer at a time, no network access
• Tips: Use WAL mode, enable foreign keys

PostgreSQL

• Good for: Multi-user apps, production, large datasets, complex queries
• Benefits: Full ACID, concurrent writes, advanced features
• Tips: Tune connection pool, use indexes, monitor performance

Example .env Files

Create a .env file in your project root:

For Development (.env.development):

DATABASE_URL=sqlite:dev_database.db

For Production (.env.production):

DATABASE_URL=postgresql://user:password@db.example.com:5432/prod_db

For Testing (.env.test):

DATABASE_URL=sqlite::memory:

Security Notes

SQLite Security

• Set proper file permissions (600 or 640)
• Don't commit database files to version control
• Consider encryption for sensitive data

PostgreSQL Security

• Use strong passwords
• Enable SSL/TLS in production
• Restrict network access
• Keep PostgreSQL updated
• Use connection pooling

Backup Strategies

SQLite Backup

# Simple file copy
cp database.db backup_$(date +%Y%m%d).db

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

PostgreSQL Backup

# Database dump
pg_dump $DATABASE_URL > backup_$(date +%Y%m%d).sql

# Restore
psql $DATABASE_URL < backup.sql

Summary

• SQLite: Perfect for development, testing, and simple applications
• PostgreSQL: Best for production, multi-user, and complex applications
• Switching: Just change the DATABASE_URL environment variable
• No Code Changes: The application handles both databases automatically

The choice between SQLite and PostgreSQL depends on your specific needs, but you can always start with SQLite and migrate to PostgreSQL later as your application grows.