| name | add-diesel-migration |
| description | Use when adding or modifying SQLite schema, Diesel migrations, repository persistence, schema.rs, entities, mappers, or repository implementations. Safely update migrations and keep Soundome reference semantics intact. |
Add Diesel Migration
Use this skill when you need to add, modify, or debug a Diesel migration in Soundome.
When to use
- add a new table or column
- rename or reshape persisted fields
- update Diesel repositories after a schema change
- debug mismatches between migrations,
schema.rs, and repository code
Repository rules
- Migrations live under
packages/database/migrations/.
- The generated schema lives in
packages/database/src/schema.rs.
- Repository traits are defined in
packages/domain/src/ports/repositories.
- Preserve repository semantics such as
set_references: replace source/provider, merge durable metadata references.
Procedure
- Start from the narrowest schema need: table, column, index, or constraint.
- Identify the affected repository traits and Diesel implementations.
- Add or update the migration with both
up.sql and down.sql.
- Regenerate or update
packages/database/src/schema.rs if the change requires it.
- Update entities, mappers, repository structs, and transaction boundaries together.
- Check whether the change touches track, album, artist, playlist, or reference persistence semantics.
- Validate with the narrowest useful command first, then with a slightly wider DB-focused check if needed.
Validation checklist
- migration shape matches the intended model
schema.rs matches the database schema
- repositories compile against the updated schema
- transaction boundaries still cover multi-entity writes
- reference merge and replacement behavior is preserved
Useful files
packages/database/migrations/
packages/database/src/schema.rs
packages/database/src/repositories/
packages/domain/src/ports/repositories/