# Database Safety (STEP 05A)

This document records the automated-test database isolation and the
development-database safeguards added after the STEP 05 incident, plus the
safe commands for running tests and clearing configuration.

## What happened (STEP 05)

A cached Laravel configuration (`bootstrap/cache/config.php`) had the
development database name (`dham_seva_db`) baked into it. Cached config
bypasses `env()` entirely, so the intended test database
(`dham_seva_test` from `phpunit.xml` / shell env) was silently overridden.
`RefreshDatabase` then ran `migrate:fresh` against the **development**
database, dropping its tables.

Automated tests must never touch the development or production database.
The safeguards below make that impossible.

## 1. Dedicated test database enforced in `phpunit.xml`

`phpunit.xml` now pins the test connection with `force="true"` so neither a
shell environment variable nor an accidental default can redirect the suite:

```xml
<env name="DB_CONNECTION" value="mysql" force="true"/>
<env name="DB_DATABASE"  value="dham_seva_test" force="true"/>
<env name="DB_URL"       value="" force="true"/>
```

## 2. Runtime safety guard before any migration

`tests/Support/DatabaseGuard.php` is a pure, framework-independent check.
`tests/TestCase.php` calls it from an overridden `refreshApplication()`.

Laravel's test lifecycle runs `refreshApplication()` (app + config loaded)
**before** `setUpTraits()` (where `RefreshDatabase` triggers destructive
migrations). The guard therefore aborts a misconfigured run *before* any
`migrate:fresh` / `db:wipe` can execute.

The guard resolves the **effective** connection from loaded config (not
`env()`), so even a poisoned cached config is caught. It refuses to run when:

- the resolved driver is not `sqlite` **and**
- the resolved database is the development database (`dham_seva_db`), **or**
- the environment is `production`, **or**
- the database name is empty/unknown, **or**
- the database is anything other than `dham_seva_test`.

SQLite (in-memory or file) is always allowed because it is isolated from real
databases.

## 3. Automated safety test

`tests/Unit/DatabaseSafetyGuardTest.php` proves:

- SQLite is allowed; the dedicated test DB is allowed.
- The development DB, production env, empty name, and any unexpected DB are
  each rejected with a clear `TEST DATABASE SAFETY ABORT`.
- This suite actually resolves to `dham_seva_test`.
- `Tests\TestCase` overrides `refreshApplication()` (the guard is wired in).

## 4. Safe commands

Run the test suite (uses `dham_seva_test`; no env override needed):

```sh
php artisan test
```

If configuration is stale or you suspect a cached config is overriding your
settings, clear it — **do not re-cache in the development environment**:

```sh
php artisan config:clear
php artisan cache:clear
```

> **Never** run `php artisan optimize` or `php artisan config:cache` against
> the development environment. Caching config bakes the current database name
> into `bootstrap/cache/config.php`, which is exactly what caused the incident.

## 5. Verified outcome

- Guard proven end-to-end: with a dev-DB cached config present, the suite
  aborts with `TEST DATABASE SAFETY ABORT` and the development database is
  left untouched.
- Full suite green on the isolated test database.

## Manual recovery still required

The 24 manually created Place Entities (10 temples, 10 ghats, 4 kunds) were
not recoverable from any available source (see STEP 05A report). They must be
re-created through the admin UI with real, verified data. No coordinates or
details were invented.
