DarkSingularity/KeepItGoingServer
Internal
Public Access
2
0
Fork 0
Code Issues 3 Pull Requests Packages Projects Releases 1 Wiki Activity

Enhance database configuration documentation

Browse Source 
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>
This commit is contained in:
Keith Smith
2025-12-22 18:21:05 -07:00
co-authored by Claude Sonnet 4.5
parent f6dff9c459
commit 21f201c552
1 changed files with 173 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+173 -13
View File
@@ -128,7 +128,9 @@ The application supports multiple database backends. Choose the one that fits yo
#### SQLite3 (Default - Development) #### 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`:** **Configuration in `config/settings/development.py`:**
```python ```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:** **Pros:**
- Zero configuration - Zero configuration - works out of the box
- No separate database server needed - No separate database server needed
- Lightweight and fast for small datasets
- Perfect for development and testing - Perfect for development and testing
- Easy to backup (single file)
**Cons:** **Cons:**
- Not recommended for production with multiple users - 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) - No network access (local file only)
- Not suitable for high-traffic applications
- Limited scalability
#### PostgreSQL (Recommended for Production) #### 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:** **1. Install PostgreSQL:**
```bash ```bash
@@ -161,6 +193,14 @@ sudo apt-get install postgresql postgresql-contrib libpq-dev
# macOS # macOS
brew install postgresql 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:** **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 default_transaction_isolation TO 'read committed';
ALTER ROLE keepitgoing_user SET timezone TO 'UTC'; ALTER ROLE keepitgoing_user SET timezone TO 'UTC';
GRANT ALL PRIVILEGES ON DATABASE keepitgoing TO keepitgoing_user; 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 \q
``` ```
**3. Install Python driver:** **3. Install Python driver:**
```bash ```bash
# For production use:
pip install psycopg2-binary pip install psycopg2-binary
# For development/if psycopg2-binary fails:
# pip install psycopg2
``` ```
**4. Update settings:** **4. Update settings:**
@@ -197,6 +245,7 @@ DATABASES = {
'PASSWORD': 'your_secure_password', 'PASSWORD': 'your_secure_password',
'HOST': 'localhost', 'HOST': 'localhost',
'PORT': '5432', 'PORT': '5432',
'CONN_MAX_AGE': 600, # Connection pooling
} }
} }
``` ```
@@ -206,9 +255,38 @@ DATABASES = {
python manage.py migrate 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:** **1. Install MariaDB:**
```bash ```bash
@@ -217,9 +295,23 @@ sudo apt-get install mariadb-server libmariadb-dev
# macOS # macOS
brew install mariadb 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 ```bash
sudo mysql sudo mysql
CREATE DATABASE keepitgoing CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE DATABASE keepitgoing CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
@@ -229,12 +321,16 @@ FLUSH PRIVILEGES;
EXIT; EXIT;
``` ```
**3. Install Python driver:** **4. Install Python driver:**
```bash ```bash
pip install mysqlclient 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: Add to your `.env` file:
```bash ```bash
@@ -259,11 +355,29 @@ DATABASES = {
} }
``` ```
**5. Run migrations:** **6. Run migrations:**
```bash ```bash
python manage.py migrate 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 #### Database Migration Between Backends
To migrate data from one database to another: To migrate data from one database to another:
@@ -478,7 +592,14 @@ sudo apt install -y certbot python3-certbot-nginx
#### Step 2: Database Setup #### Step 2: Database Setup
Choose your database backend. PostgreSQL is recommended for production.
**Option A: PostgreSQL (Recommended for Production)**
```bash ```bash
# Install PostgreSQL
sudo apt install -y postgresql postgresql-contrib libpq-dev
# Create PostgreSQL database and user # Create PostgreSQL database and user
sudo -u postgres psql << EOF sudo -u postgres psql << EOF
CREATE DATABASE keepitgoing; CREATE DATABASE keepitgoing;
@@ -491,6 +612,29 @@ GRANT ALL PRIVILEGES ON DATABASE keepitgoing TO keepitgoing_user;
EOF 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 #### Step 3: Application Setup
```bash ```bash
@@ -508,7 +652,14 @@ source venv/bin/activate
# Install dependencies # Install dependencies
pip install -r requirements.txt 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 # Create production environment file
cat > .env << 'EOF' cat > .env << 'EOF'
@@ -519,10 +670,19 @@ ALLOWED_HOSTS=tasks.firebugit.com,localhost,127.0.0.1
CSRF_TRUSTED_ORIGINS=https://tasks.firebugit.com CSRF_TRUSTED_ORIGINS=https://tasks.firebugit.com
SITE_DOMAIN=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 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_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=smtp.gmail.com EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587 EMAIL_PORT=587