xamxam/docs/DATABASE_CONFIG.md

Database Configuration

This document explains the centralized database configuration for the Post-ERG thesis management system.

Overview

Database paths are centralized in shared/config.php to provide a single source of truth for:

• Test database location (development)
• Production database location (deployment)
• Environment detection logic

Database Locations

database/
├── test.db        # Development/testing database
└── posterg.db     # Production database

Configuration File

The shared/config.php file defines:

// Test database (development)
DB_TEST_PATH = '/path/to/storage/test.db'

// Production database (server)
DB_PROD_PATH = '/path/to/storage/posterg.db'

How It Works

Automatic Detection

By default, the system automatically determines which database to use:

1. If storage/test.db exists → Use test database (development mode)
2. Otherwise → Use production database (production mode)

This means:

• Developers get test database automatically when it exists
• Production server uses production database (no test.db present)

Manual Override

You can force a specific database using the DB_ENV environment variable:

# Force test database
export DB_ENV=test
php apps/public/index.php

# Force production database
export DB_ENV=prod
php apps/public/index.php

Custom Path Override

You can also pass a custom database path directly:

// Use specific database file
$db = new Database('/custom/path/to/database.db');

// Or with singleton
$db = Database::getInstance('/custom/path/to/database.db');

Deployment Workflow

Development

When working locally:

# Create test database with fixtures
just create-fixtures

# Start development server (uses test.db automatically)
just serve-public
just serve-admin

Production

When deploying to server:

# Deploy applications and shared code (excludes test.db automatically)
just deploy

# The deploy command explicitly excludes:
# - test.db (test database)
# - *.db (all database files)
# - tests/ (test suites)
# - cache/ (temporary files)
# - *.md (documentation)

# Result: Only posterg.db exists on server
# Application automatically uses production database

Deploying Test Database (Explicitly)

If you need to deploy the test database to the server (for testing):

# This is a separate, explicit command
just test-deploy

# ⚠️  Warning: This will overwrite the remote test.db file

Deploying Database Structure Only

To deploy schema and fixtures without databases:

# Deploy schema.sql and fixtures/ only (excludes all .db files)
just deploy-database

Testing on Production

To test with production data locally:

# Download production database (optional)
scp posterg:/var/www/html/storage/posterg.db database/

# Remove test database to force production mode
rm database/test.db

# Or set environment variable
export DB_ENV=prod
php apps/public/index.php

Benefits of Centralized Configuration

1. Single source of truth - All database paths defined in one place
2. Environment-aware - Automatically detects development vs production
3. Override capability - Can force specific database when needed
4. Maintainable - Easy to update paths or add new environments
5. Safe deployment - Test database never deployed to production

Integration with Database Class

The Database class automatically uses this configuration:

require_once 'shared/Database.php';

// Automatically uses correct database based on environment
$db = new Database();

The path resolution order is:

1. Custom path (if provided)
2. DB_ENV environment variable
3. Auto-detection (test.db exists → test mode, otherwise → production)

Helper Functions

shared/config.php provides helper functions:

// Get current database path
$path = getDatabasePath();

// Check if running in test mode
if (isTestMode()) {
    echo "Using test database";
}

Notes

• Deployment safety: The deploy, deploy-public, and deploy-admin recipes explicitly exclude test.db and all *.db files
• Explicit test deploy: Use just test-deploy to explicitly deploy test.db when needed
• Git ignored: Test database is in .gitignore and never committed
• Backups: Production database should be backed up regularly
• Schema: Both databases use the same schema (storage/schema.sql)
• Verification: Run rsync --dry-run to preview what will be deployed before deploying