Enhance database configuration documentation

Add comprehensive instructions for all database backends: SQLite: - When to use (development, testing, single-user) - When NOT to use (production with multiple users) - DATABASE_URL configuration - Pros and cons with detailed explanations - Zero-configuration setup instructions PostgreSQL: - When to use (production, multiple users, advanced features) - Complete installation and setup for Ubuntu/Debian and macOS - Database and user creation with PostgreSQL 15+ schema permissions - Connection pooling configuration - Performance tuning recommendations MySQL/MariaDB: - When to use (existing MySQL infrastructure, replication) - Installation for both MariaDB and MySQL - Secure installation steps - Alternative driver (PyMySQL) if mysqlclient fails - Performance tuning configuration Production Setup Guide updates: - All three database options in Step 2 - Database driver installation for each backend - .env examples for PostgreSQL, MySQL, and SQLite - Clear warnings about SQLite in production Each database section now includes installation, configuration, performance tuning, and clear guidance on appropriate use cases. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2025-12-22 18:21:05 -07:00
parent f6dff9c459
commit 21f201c552
1 changed files with 173 additions and 13 deletions
@@ -128,7 +128,9 @@ The application supports multiple database backends. Choose the one that fits yo

 #### SQLite3 (Default - Development)

-SQLite3 is the default database and requires no additional setup. It's perfect for development and single-user scenarios.
+SQLite3 is the default database and requires no additional setup. It's perfect for development, testing, and single-user scenarios.
+
+**No installation required** - SQLite comes bundled with Python.

 **Configuration in `config/settings/development.py`:**
 ```python
@@ -140,19 +142,49 @@ DATABASES = {
 }
 ```

+**Using DATABASE_URL in `.env`:**
+```bash
+DATABASE_URL=sqlite:///db.sqlite3
+```
+
+**When to use SQLite:**
+- ✅ Development and testing
+- ✅ Single-user deployments
+- ✅ Low-traffic personal projects
+- ✅ Quick prototyping
+- ✅ Embedded applications
+
+**When NOT to use SQLite:**
+- ❌ Production with multiple concurrent users
+- ❌ High-traffic websites
+- ❌ Applications requiring network database access
+- ❌ Heavy write operations
+
 **Pros:**
- Zero configuration
+- Zero configuration - works out of the box
 - No separate database server needed
+- Lightweight and fast for small datasets
 - Perfect for development and testing
+- Easy to backup (single file)

 **Cons:**
 - Not recommended for production with multiple users
- Limited concurrent write operations
+- Limited concurrent write operations (can cause database locks)
 - No network access (local file only)
+- Not suitable for high-traffic applications
+- Limited scalability

 #### PostgreSQL (Recommended for Production)

-PostgreSQL is the recommended database for production deployments.
+PostgreSQL is the recommended database for production deployments. It offers the best combination of performance, features, and reliability for Django applications.
+
+**When to use PostgreSQL:**
+- ✅ **Production environments** (highly recommended)
+- ✅ Applications with multiple concurrent users
+- ✅ Need for advanced features (JSONB, full-text search, etc.)
+- ✅ Complex queries and data integrity requirements
+- ✅ Scalability and performance are priorities
+- ✅ Geographic data (PostGIS extension)

 **1. Install PostgreSQL:**
 ```bash
@@ -161,6 +193,14 @@ sudo apt-get install postgresql postgresql-contrib libpq-dev

 # macOS
 brew install postgresql
+
+# Start PostgreSQL service
+# Ubuntu/Debian:
+sudo systemctl start postgresql
+sudo systemctl enable postgresql
+
+# macOS:
+brew services start postgresql
 ```

 **2. Create database and user:**
@@ -172,12 +212,20 @@ ALTER ROLE keepitgoing_user SET client_encoding TO 'utf8';
 ALTER ROLE keepitgoing_user SET default_transaction_isolation TO 'read committed';
 ALTER ROLE keepitgoing_user SET timezone TO 'UTC';
 GRANT ALL PRIVILEGES ON DATABASE keepitgoing TO keepitgoing_user;
+
+-- For PostgreSQL 15+, also grant schema permissions:
+\c keepitgoing
+GRANT ALL ON SCHEMA public TO keepitgoing_user;
 \q
 ```

 **3. Install Python driver:**
 ```bash
+# For production use:
 pip install psycopg2-binary
+
+# For development/if psycopg2-binary fails:
+# pip install psycopg2
 ```

 **4. Update settings:**
@@ -197,6 +245,7 @@ DATABASES = {
        'PASSWORD': 'your_secure_password',
        'HOST': 'localhost',
        'PORT': '5432',
+        'CONN_MAX_AGE': 600,  # Connection pooling
    }
 }
 ```
@@ -206,9 +255,38 @@ DATABASES = {
 python manage.py migrate
 ```

-#### MariaDB/MySQL
+**6. Performance tuning (optional):**

-MariaDB and MySQL are also supported for production use.
+Edit `/etc/postgresql/[version]/main/postgresql.conf`:
+```ini
+# Adjust based on available RAM (25% of total RAM)
+shared_buffers = 256MB
+
+# Effective cache size (50-75% of total RAM)
+effective_cache_size = 1GB
+
+# Maintenance work memory
+maintenance_work_mem = 64MB
+
+# Maximum connections
+max_connections = 100
+```
+
+Restart PostgreSQL:
+```bash
+sudo systemctl restart postgresql
+```
+
+#### MariaDB/MySQL (Alternative Production Database)
+
+MariaDB and MySQL are well-supported alternatives for production deployments. MariaDB is recommended over MySQL for better performance and features.
+
+**When to use MySQL/MariaDB:**
+- ✅ Production environments with multiple users
+- ✅ Applications requiring replication
+- ✅ Teams familiar with MySQL ecosystem
+- ✅ Need for specific MySQL features or tools
+- ✅ Integration with existing MySQL infrastructure

 **1. Install MariaDB:**
 ```bash
@@ -217,9 +295,23 @@ sudo apt-get install mariadb-server libmariadb-dev

 # macOS
 brew install mariadb
+
+# For MySQL instead of MariaDB:
+# Ubuntu/Debian: sudo apt-get install mysql-server libmysqlclient-dev
+# macOS: brew install mysql
 ```

-**2. Create database and user:**
+**2. Secure installation (recommended):**
+```bash
+sudo mysql_secure_installation
+# This will prompt you to:
+# - Set root password
+# - Remove anonymous users
+# - Disallow root login remotely
+# - Remove test database
+```
+
+**3. Create database and user:**
 ```bash
 sudo mysql
 CREATE DATABASE keepitgoing CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
@@ -229,12 +321,16 @@ FLUSH PRIVILEGES;
 EXIT;
 ```

-**3. Install Python driver:**
+**4. Install Python driver:**
 ```bash
 pip install mysqlclient
+
+# If mysqlclient installation fails, you can use PyMySQL as an alternative:
+# pip install pymysql
+# Then add to your settings: import pymysql; pymysql.install_as_MySQLdb()
 ```

-**4. Update settings:**
+**5. Update settings:**

 Add to your `.env` file:
 ```bash
@@ -259,11 +355,29 @@ DATABASES = {
 }
 ```

-**5. Run migrations:**
+**6. Run migrations:**
 ```bash
 python manage.py migrate
 ```

+**Performance tuning (optional):**
+Edit `/etc/mysql/mariadb.conf.d/50-server.cnf` (MariaDB) or `/etc/mysql/mysql.conf.d/mysqld.cnf` (MySQL):
+```ini
+[mysqld]
+# Increase buffer pool size (adjust based on available RAM)
+innodb_buffer_pool_size = 1G
+# Improve connection handling
+max_connections = 200
+# Enable query cache (MySQL 5.7 only, removed in MySQL 8.0)
+query_cache_type = 1
+query_cache_size = 64M
+```
+
+Restart database:
+```bash
+sudo systemctl restart mariadb  # or mysql
+```
+
 #### Database Migration Between Backends

 To migrate data from one database to another:
@@ -478,7 +592,14 @@ sudo apt install -y certbot python3-certbot-nginx

 #### Step 2: Database Setup

+Choose your database backend. PostgreSQL is recommended for production.
+
+**Option A: PostgreSQL (Recommended for Production)**
+
 ```bash
+# Install PostgreSQL
+sudo apt install -y postgresql postgresql-contrib libpq-dev
+
 # Create PostgreSQL database and user
 sudo -u postgres psql << EOF
 CREATE DATABASE keepitgoing;
@@ -491,6 +612,29 @@ GRANT ALL PRIVILEGES ON DATABASE keepitgoing TO keepitgoing_user;
 EOF
 ```

+**Option B: MySQL/MariaDB (Alternative Production Database)**
+
+```bash
+# Install MariaDB
+sudo apt install -y mariadb-server libmariadb-dev
+
+# Secure MariaDB installation
+sudo mysql_secure_installation
+
+# Create database and user
+sudo mysql << EOF
+CREATE DATABASE keepitgoing CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+CREATE USER 'keepitgoing_user'@'localhost' IDENTIFIED BY 'STRONG_PASSWORD_HERE';
+GRANT ALL PRIVILEGES ON keepitgoing.* TO 'keepitgoing_user'@'localhost';
+FLUSH PRIVILEGES;
+EXIT;
+EOF
+```
+
+**Option C: SQLite (Development/Testing Only)**
+
+No database server setup required. SQLite uses a local file and is configured automatically. **Not recommended for production with multiple users.**
+
 #### Step 3: Application Setup

 ```bash
@@ -508,7 +652,14 @@ source venv/bin/activate

 # Install dependencies
 pip install -r requirements.txt
-pip install gunicorn psycopg2-binary
+pip install gunicorn
+
+# Install database driver based on your choice from Step 2
+# For PostgreSQL:
+pip install psycopg2-binary
+# For MySQL/MariaDB:
+# pip install mysqlclient
+# For SQLite: no additional package needed

 # Create production environment file
 cat > .env << 'EOF'
@@ -519,10 +670,19 @@ ALLOWED_HOSTS=tasks.firebugit.com,localhost,127.0.0.1
 CSRF_TRUSTED_ORIGINS=https://tasks.firebugit.com
 SITE_DOMAIN=tasks.firebugit.com

-# Database
+# Database Configuration
+# Choose ONE of the following based on your database from Step 2:
+
+# Option A: PostgreSQL (Recommended)
 DATABASE_URL=postgresql://keepitgoing_user:STRONG_PASSWORD_HERE@localhost:5432/keepitgoing

-# Email Configuration (Gmail example)
+# Option B: MySQL/MariaDB (Alternative)
+# DATABASE_URL=mysql://keepitgoing_user:STRONG_PASSWORD_HERE@localhost:3306/keepitgoing
+
+# Option C: SQLite (Development/Testing only - Not for production!)
+# DATABASE_URL=sqlite:///db.sqlite3
+
+# Email Configuration (Gmail example - see Step 4 for other providers)
 EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
 EMAIL_HOST=smtp.gmail.com
 EMAIL_PORT=587