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)
```bash
export DATABASE_URL="sqlite:database.db"
cargo run --bin server
```

### For PostgreSQL (Docker)
```bash
# 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)
```toml
[database]
url = "sqlite:database.db"  # Change this line for different databases
max_connections = 10
```

### Environment Variables (Recommended)
```bash
# 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:

```bash
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)
```bash
# 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):**
```bash
brew install postgresql
brew services start postgresql
createdb myapp
export DATABASE_URL="postgresql://$(whoami)@localhost:5432/myapp"
```

**Ubuntu/Debian:**
```bash
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):**
```bash
export DATABASE_URL="sqlite:dev.db"
cargo run --bin server
```

**Testing (In-memory):**
```bash
export DATABASE_URL="sqlite::memory:"
cargo test
```

**Production (PostgreSQL):**
```bash
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`:

```bash
# 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
```bash
# Connect to database
sqlite3 database.db

# Check tables
.tables

# Query users
SELECT * FROM users;

# Exit
.quit
```

### PostgreSQL Commands
```bash
# 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:**
```bash
# 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:**
```bash
# Check if PostgreSQL is running
docker ps  # for Docker
brew services list | grep postgres  # for Homebrew
sudo systemctl status postgresql  # for Linux
```

**Authentication Failed:**
```bash
# 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:**
```bash
# 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
```bash
# Simple file copy
cp database.db backup_$(date +%Y%m%d).db

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

### PostgreSQL Backup
```bash
# 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.