erik/slugkit
1
0
Fork 0
Code Issues 6 Pull requests Projects Releases 6 Packages Wiki Activity Actions

Add SQLite migration foundation #36

New issue
Closed
opened 2026-05-19 19:51:45 -05:00 by erik · 2 comments
erik commented 2026-05-19 19:51:45 -05:00
Owner
Copy link

Goal

Provide the SQLite configuration and migration runner foundation for the Slugkit template website without adding feature-specific tables yet.

Spec: docs/web-specs/01-database-schema-migrations.md

Scope

This is infrastructure/foundation work. Feature tables should be added later by the small vertical slice that implements the manually testable feature needing those tables.

Requirements

  • Add SQLite database configuration for the template website.
  • Add migration tooling and documented migration commands.
  • Add a migration runner that creates and uses a schema_migrations table.
  • Apply pending SQL migrations in deterministic order and make repeated runs safe.
  • Add a migration status/check command so the foundation can be manually verified.
  • Make tests run against isolated temporary test databases.
  • Document database path environment variables in .env.example.
  • Document the migration policy: migrations are a template implementation detail, and feature-specific tables are introduced by the vertical feature task that needs them.
  • Follow docs/CONTRIBUTING.md and docs/CODE_STANDARDS.md.

Out of scope

  • Posts, tags, contacts, sources, accounts, media, auth, social, ActivityPub, or Fedify tables.
  • Business logic for feature domains.
  • API routes that use persisted data.

Acceptance criteria

  • The migration command creates a SQLite database from scratch.
  • The migration runner records applied migrations in schema_migrations.
  • Re-running migrations is idempotent and does not reapply completed migrations.
  • A migration status/check command provides a manual verification path.
  • Test runs use isolated temporary databases and do not modify a developer database.
  • .env.example documents database configuration.
  • Documentation explains that feature-specific tables are added by future manually testable vertical slices.
  • Relevant lint/test checks pass.

Dependencies

  • task-d6397b57
## Goal Provide the SQLite configuration and migration runner foundation for the Slugkit template website without adding feature-specific tables yet. Spec: `docs/web-specs/01-database-schema-migrations.md` ## Scope This is infrastructure/foundation work. Feature tables should be added later by the small vertical slice that implements the manually testable feature needing those tables. ## Requirements - Add SQLite database configuration for the template website. - Add migration tooling and documented migration commands. - Add a migration runner that creates and uses a `schema_migrations` table. - Apply pending SQL migrations in deterministic order and make repeated runs safe. - Add a migration status/check command so the foundation can be manually verified. - Make tests run against isolated temporary test databases. - Document database path environment variables in `.env.example`. - Document the migration policy: migrations are a template implementation detail, and feature-specific tables are introduced by the vertical feature task that needs them. - Follow `docs/CONTRIBUTING.md` and `docs/CODE_STANDARDS.md`. ## Out of scope - Posts, tags, contacts, sources, accounts, media, auth, social, ActivityPub, or Fedify tables. - Business logic for feature domains. - API routes that use persisted data. ## Acceptance criteria - [ ] The migration command creates a SQLite database from scratch. - [ ] The migration runner records applied migrations in `schema_migrations`. - [ ] Re-running migrations is idempotent and does not reapply completed migrations. - [ ] A migration status/check command provides a manual verification path. - [ ] Test runs use isolated temporary databases and do not modify a developer database. - [ ] `.env.example` documents database configuration. - [ ] Documentation explains that feature-specific tables are added by future manually testable vertical slices. - [ ] Relevant lint/test checks pass. ## Dependencies - task-d6397b57
erik changed title from Add template database and migrations to Add SQLite migration foundation 2026-05-22 07:40:51 -05:00
erik commented 2026-05-22 08:17:30 -05:00
Author
Owner
Copy link

Synced from todu comment by @todu on 2026-05-22T13:16:22.537Z

PR Review: Approved

PR: #42

Summary

Reviewed PR #42 at commit 52a64d9. The PR adds a foundation-only SQLite migration setup using Node's built-in node:sqlite, with no feature-specific tables. It includes database path configuration, foreign-key-enabled connections, migration discovery/application/status tracking via schema_migrations, template scripts for db:migrate and db:status, isolated temp-database tests, and documentation for the vertical-slice migration policy.

Acceptance Criteria

  • The migration command creates a SQLite database from scratch.
  • The migration runner records applied migrations in schema_migrations.
  • Re-running migrations is idempotent and does not reapply completed migrations.
  • A migration status/check command provides a manual verification path.
  • Test runs use isolated temporary databases and do not modify a developer database.
  • .env.example documents database configuration.
  • Documentation explains that feature-specific tables are added by future manually testable vertical slices.
  • Relevant lint/test checks pass: make check, ./scripts/pre-pr.sh, manual migrate/status smoke, and Forgejo CI all passed.

Blocking Issues

None.

Warnings

  • Node currently prints an experimental warning for node:sqlite. This is acceptable for the foundation because the project already targets Node 24 and avoiding native SQLite dependencies keeps CI fast and reliable.

Verdict

Approved for merge.

_Synced from todu comment by @todu on 2026-05-22T13:16:22.537Z_ ## PR Review: Approved PR: https://forge.caradoc.com/erik/slugkit/pulls/42 ### Summary Reviewed PR #42 at commit `52a64d9`. The PR adds a foundation-only SQLite migration setup using Node's built-in `node:sqlite`, with no feature-specific tables. It includes database path configuration, foreign-key-enabled connections, migration discovery/application/status tracking via `schema_migrations`, template scripts for `db:migrate` and `db:status`, isolated temp-database tests, and documentation for the vertical-slice migration policy. ### Acceptance Criteria - [x] The migration command creates a SQLite database from scratch. - [x] The migration runner records applied migrations in `schema_migrations`. - [x] Re-running migrations is idempotent and does not reapply completed migrations. - [x] A migration status/check command provides a manual verification path. - [x] Test runs use isolated temporary databases and do not modify a developer database. - [x] `.env.example` documents database configuration. - [x] Documentation explains that feature-specific tables are added by future manually testable vertical slices. - [x] Relevant lint/test checks pass: `make check`, `./scripts/pre-pr.sh`, manual migrate/status smoke, and Forgejo CI all passed. ### Blocking Issues None. ### Warnings - Node currently prints an experimental warning for `node:sqlite`. This is acceptable for the foundation because the project already targets Node 24 and avoiding native SQLite dependencies keeps CI fast and reliable. ### Verdict Approved for merge.
erik 2026-05-22 08:22:45 -05:00
erik commented 2026-05-22 08:22:45 -05:00
Author
Owner
Copy link

Synced from todu comment by @todu on 2026-05-22T13:18:26.641Z

Closing Summary

PR #42 merged: #42

Acceptance criteria evidence:

  • The migration command creates a SQLite database from scratch: met — db:migrate creates the database file and parent directory, verified by tests and manual smoke.
  • The migration runner records applied migrations in schema_migrations: met — runner creates schema_migrations and records applied fixture migrations in tests.
  • Re-running migrations is idempotent and does not reapply completed migrations: met — idempotence test reruns migrations and verifies fixture rows are not duplicated.
  • A migration status/check command provides a manual verification path: met — db:status reports applied and pending migration counts.
  • Test runs use isolated temporary databases and do not modify a developer database: met — migration tests create temp directories/databases and clean them after each test.
  • .env.example documents database configuration: met — root and template env examples document DATABASE_PATH.
  • Documentation explains that feature-specific tables are added by future manually testable vertical slices: met — README and db README document the policy.
  • Relevant lint/test checks pass: met — make check, ./scripts/pre-pr.sh, PR CI, and main push CI passed.

Readiness: READY

_Synced from todu comment by @todu on 2026-05-22T13:18:26.641Z_ ## Closing Summary PR #42 merged: https://forge.caradoc.com/erik/slugkit/pulls/42 Acceptance criteria evidence: - The migration command creates a SQLite database from scratch: met — `db:migrate` creates the database file and parent directory, verified by tests and manual smoke. - The migration runner records applied migrations in `schema_migrations`: met — runner creates `schema_migrations` and records applied fixture migrations in tests. - Re-running migrations is idempotent and does not reapply completed migrations: met — idempotence test reruns migrations and verifies fixture rows are not duplicated. - A migration status/check command provides a manual verification path: met — `db:status` reports applied and pending migration counts. - Test runs use isolated temporary databases and do not modify a developer database: met — migration tests create temp directories/databases and clean them after each test. - `.env.example` documents database configuration: met — root and template env examples document `DATABASE_PATH`. - Documentation explains that feature-specific tables are added by future manually testable vertical slices: met — README and db README document the policy. - Relevant lint/test checks pass: met — `make check`, `./scripts/pre-pr.sh`, PR CI, and main push CI passed. Readiness: READY
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
release/slug-cli-v0.5.0
release/slug-cli-v0.4.0
release/slug-cli-v0.3.0
release/slug-cli-v0.2.0
release/slug-cli-v0.1.2
release/slug-cli-v0.1.1
feat/task-47be19ea-api-meta-route
feat/task-51eaa27f-swagger-api-docs
feat/task-0dbd25d3-site-config-homepage
feat/task-69937fe4-sqlite-migrations
feat/task-a3cd5595-cli-foundation
feat/task-c272cbda-openapi-health
feat/task-d6397b57-template-foundation
v0.5.0
v0.4.0
v0.3.0
v0.2.0
v0.1.2
v0.1.1
Labels
Clear labels   
activitypub

   
admin

   
api

   
articles

   
auth

   
bug

   
cleanup

   
cli

   
comments

   
compatibility

   
config

   
contacts

   
database

   
deployment

   
design

   
dev-env

   
docs

   
documentation

   
email

   
enhancement

   
feature

   
federation

   
feed

   
homepage

   
implementation

   
integration

   
media

   
openapi

   
priority:high

   
priority:low

   
priority:medium

   
proof

   
public-routes

   
public-ui

   
release

   
safety

   
social

   
sources

   
status:active

   
status:canceled

   
status:done

   
status:inprogress

   
status:waiting

   
syndication

   
tailwind

   
template

   
test

   
web
No labels
activitypub
admin
api
articles
auth
bug
cleanup
cli
comments
compatibility
config
contacts
database
deployment
design
dev-env
docs
documentation
email
enhancement
feature
federation
feed
homepage
implementation
integration
media
openapi
priority:high
priority:low
priority:medium
proof
public-routes
public-ui
release
safety
social
sources
status:active
status:canceled
status:done
status:inprogress
status:waiting
syndication
tailwind
template
test
web
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
erik/slugkit#36
No description provided.