mirror of
https://github.com/zvx-echo6/central.git
synced 2026-05-21 18:14:44 +02:00
docs: add test database setup, restore geom to test fixture
- Add docs/test-database.md with one-time setup, DSN convention, reset instructions, and explanation of why PostGIS is not in migrations - Update docs/migrations.md with "Extensions are not in migrations" section explaining superuser requirement - Restore geom GEOMETRY(Geometry, 4326) column to test fixture now that central_test has PostGIS installed - Add CREATE EXTENSION IF NOT EXISTS postgis to test fixture for self-bootstrap (central_test is superuser) - Add Testing section to README.md pointing to docs/test-database.md Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
71c73b4eb1
commit
83b1e45fa8
4 changed files with 113 additions and 2 deletions
83
docs/test-database.md
Normal file
83
docs/test-database.md
Normal file
|
|
@ -0,0 +1,83 @@
|
|||
# Test Database Setup
|
||||
|
||||
Central's integration tests require a PostgreSQL database. This document
|
||||
covers one-time setup and maintenance of the test database.
|
||||
|
||||
## DSN Convention
|
||||
|
||||
Tests default to:
|
||||
|
||||
```
|
||||
postgresql://central_test:testpass@localhost/central_test
|
||||
```
|
||||
|
||||
Override via the `CENTRAL_TEST_DB_DSN` environment variable:
|
||||
|
||||
```bash
|
||||
export CENTRAL_TEST_DB_DSN="postgresql://myuser:mypass@localhost/mydb"
|
||||
```
|
||||
|
||||
## One-Time Setup
|
||||
|
||||
Run these commands once on a fresh PostgreSQL installation:
|
||||
|
||||
```bash
|
||||
# Create the test user (as postgres superuser)
|
||||
sudo -u postgres createuser -s central_test
|
||||
sudo -u postgres psql -c "ALTER USER central_test PASSWORD 'testpass'"
|
||||
|
||||
# Create the test database
|
||||
sudo -u postgres createdb -O central_test central_test
|
||||
|
||||
# Install required extensions
|
||||
sudo -u postgres psql central_test -c "CREATE EXTENSION IF NOT EXISTS postgis"
|
||||
```
|
||||
|
||||
**Note:** The `central_test` role is created as a superuser (`-s` flag).
|
||||
This allows test fixtures to self-bootstrap extensions like PostGIS via
|
||||
`CREATE EXTENSION IF NOT EXISTS`. Production uses a non-superuser role.
|
||||
|
||||
## Required Extensions
|
||||
|
||||
| Extension | Version | Purpose |
|
||||
|-----------|---------|---------|
|
||||
| postgis | 3.4+ | Geometry types for geospatial event data |
|
||||
|
||||
## Why PostGIS Is Not in Migrations
|
||||
|
||||
PostGIS requires superuser privileges to install. The production `central`
|
||||
role is intentionally not a superuser for security reasons. Therefore:
|
||||
|
||||
- **Production:** A DBA must run `CREATE EXTENSION postgis` before the
|
||||
first `migrate.py` run. This is a one-time bootstrap step.
|
||||
- **Test:** The `central_test` role is a superuser, so test fixtures can
|
||||
self-bootstrap PostGIS via `CREATE EXTENSION IF NOT EXISTS`.
|
||||
|
||||
This divergence is documented rather than "fixed" because granting
|
||||
superuser to production roles creates security risk, and the PostgreSQL
|
||||
packaging on Ubuntu does not mark PostGIS as a trusted extension.
|
||||
|
||||
## Resetting the Test Database
|
||||
|
||||
If the test database gets into a bad state:
|
||||
|
||||
```bash
|
||||
# Drop and recreate
|
||||
sudo -u postgres dropdb central_test
|
||||
sudo -u postgres createdb -O central_test central_test
|
||||
sudo -u postgres psql central_test -c "CREATE EXTENSION IF NOT EXISTS postgis"
|
||||
```
|
||||
|
||||
Test fixtures handle their own table creation and cleanup, so this is
|
||||
rarely needed.
|
||||
|
||||
## Running Tests
|
||||
|
||||
```bash
|
||||
cd /opt/central
|
||||
uv run pytest tests/ # all tests
|
||||
uv run pytest tests/test_config_store.py -v # specific file
|
||||
```
|
||||
|
||||
Tests that require the database will skip gracefully if the connection
|
||||
fails, though most integration tests will fail without a working DB.
|
||||
Loading…
Add table
Add a link
Reference in a new issue