Christian Galo
fb02411f35
Add a goose migration to create core and fedwiki schemas and move existing domain tables using ALTER TABLE IF EXISTS. Set connection search_path to "core, public" after successful DB ping. Update FedWiki SQL and sqlc.yaml to use fedwiki.sites and include db migrations for schema awareness. Add design docs, specs, and tasks for schema-namespacing and the migration plan.
80 lines
3.6 KiB
Markdown
80 lines
3.6 KiB
Markdown
# postgres-database
|
|
|
|
## Purpose
|
|
|
|
Defines PostgreSQL as the application database: connection via pgx, migrations via goose, and code generation via sqlc.
|
|
|
|
## Requirements
|
|
|
|
### Requirement: PostgreSQL connection via pgx driver
|
|
|
|
The system SHALL connect to PostgreSQL using the `pgx/v5` driver with stdlib compatibility mode (`pgx/v5/stdlib`). After establishing the connection, the system SHALL ensure `search_path = core, public` so domain tables resolve without schema qualification.
|
|
|
|
#### Scenario: Successful connection
|
|
|
|
- **WHEN** the application starts with a valid PostgreSQL DSN
|
|
- **THEN** a database connection pool is established and ready for queries
|
|
- **AND** the connection's `search_path` SHALL be set to `core, public`
|
|
|
|
#### Scenario: Connection failure
|
|
|
|
- **WHEN** the application starts with an invalid or unreachable PostgreSQL DSN
|
|
- **THEN** the application fails to start with a descriptive error message
|
|
|
|
#### Scenario: search_path failure
|
|
|
|
- **WHEN** the connection succeeds but `SET search_path` fails
|
|
- **THEN** the connection SHALL be closed
|
|
- **AND** the application SHALL fail to start with a descriptive error message
|
|
|
|
### Requirement: PostgreSQL connection string configuration
|
|
The system SHALL accept a PostgreSQL connection string via the `--db-dsn` flag in the format `postgres://user:password@host:port/dbname?sslmode=disable`.
|
|
|
|
#### Scenario: DSN from command line flag
|
|
- **WHEN** the application is started with `--db-dsn "postgres://user:pass@localhost:5432/mydb"`
|
|
- **THEN** the application connects to the specified PostgreSQL database
|
|
|
|
#### Scenario: DSN with SSL mode
|
|
- **WHEN** the DSN includes `?sslmode=require`
|
|
- **THEN** the connection uses SSL/TLS encryption
|
|
|
|
### Requirement: Connection pool configuration
|
|
The system SHALL configure the connection pool with sensible defaults for PostgreSQL (max open connections, max idle connections, connection lifetime).
|
|
|
|
#### Scenario: Default pool settings applied
|
|
- **WHEN** the application connects to PostgreSQL
|
|
- **THEN** the connection pool is configured with max open connections, max idle connections, and connection lifetime limits
|
|
|
|
### Requirement: Database migrations via goose
|
|
The system SHALL use goose to manage PostgreSQL database migrations with embedded migration files.
|
|
|
|
#### Scenario: Migrations run on startup
|
|
- **WHEN** the application starts and connects to PostgreSQL
|
|
- **THEN** pending migrations are automatically applied
|
|
|
|
#### Scenario: Migration CLI commands
|
|
- **WHEN** the user runs `migrate up`, `migrate down`, or `migrate status`
|
|
- **THEN** the corresponding goose operation is executed against the PostgreSQL database
|
|
|
|
### Requirement: sqlc code generation for PostgreSQL
|
|
The system SHALL use sqlc configured with `engine: "postgresql"` to generate type-safe Go code from SQL queries.
|
|
|
|
#### Scenario: Query generation
|
|
- **WHEN** `sqlc generate` is run
|
|
- **THEN** Go code is generated using PostgreSQL syntax and types
|
|
|
|
### Requirement: Schema with users, sites, and payments tables
|
|
The system SHALL maintain the existing data model with users, sites, and payments tables using PostgreSQL data types.
|
|
|
|
#### Scenario: Tables created by migration
|
|
- **WHEN** migrations are applied to a fresh database
|
|
- **THEN** the users, sites, and payments tables exist with appropriate columns, constraints, and indexes
|
|
|
|
#### Scenario: Foreign key constraints enforced
|
|
- **WHEN** a site or payment references a non-existent user
|
|
- **THEN** the database rejects the operation with a foreign key violation error
|
|
|
|
#### Scenario: Cascading deletes
|
|
- **WHEN** a user is deleted
|
|
- **THEN** their associated sites and payments are automatically deleted
|