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:

```php
// 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:

```bash
# 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:

```php
// 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:
```bash
# 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:
```bash
# 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):
```bash
# 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:
```bash
# Deploy schema.sql and fixtures/ only (excludes all .db files)
just deploy-database
```

### Testing on Production

To test with production data locally:
```bash
# 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:

```php
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:

```php
// 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