Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

working-with-storage

/working-with-storage

Pilnuje zasad pracy z bazą SQLite: transakcje, outbox, migracje, testy i pragmy przy edycji magazynu danych.

Repozytorium
spur-board ↗
Licencja
MIT
Ostatnia zmiana repozytorium
13.11.2026

Ocena i bezpieczeństwo

90/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść25 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
5
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Pilnuje zasad pracy z bazą SQLite: transakcje, outbox, migracje, testy i pragmy przy edycji magazynu danych.

Oryginalny opis (EN)

Rules for the SQLite store (packages/core/src/store/) and outbox (packages/core/src/app/{outbox,sender}.ts) - transactions, outbox, migrations and tests, PRAGMAs. Use when you edit them or write to the store. Don't use for zod schemas, enums or event kinds (use working-with-contracts).

Jak działa

  1. When to use
  2. Transactions
  3. State, journal and outbox
  4. Migrations
  5. Testing a migration
  6. PRAGMAs and opening
  7. Changing these rules
  8. Checks
Sekcje z nagłówków SKILL.md, w oryginale · 87 linii, 614 słów
Podgląd SKILL.md
---
name: working-with-storage
description: Rules for the SQLite store (packages/core/src/store/) and outbox (packages/core/src/app/{outbox,sender}.ts) - transactions, outbox, migrations and tests, PRAGMAs. Use when you edit them or write to the store. Don't use for zod schemas, enums or event kinds (use working-with-contracts).
---

# Working with storage

`packages/core/src/store/` holds the SQLite store: one file, opened by `openStore`, schema in
numbered migrations. Where a test enforces a rule, the rule names it.

## When to use

- Any edit under `packages/core/src/store/`, `packages/core/test/store/` or the outbox
  (`packages/core/src/app/{outbox,sender}.ts`), and any code that writes to the
  store (`scanTransaction` or `store.transaction`).
- Not for zod schemas, enums or event kinds: use `working-with-contracts`. A migration that
  breaks stored data as users see it (its Breaking changes section lists the cases, a new required
  column and a tightened constraint among them) needs both skills: this one for the migration,
  that one for the break.

## Transactions

- Read references/transactions.md for the write entry point and scan replay,
  transaction scope, locking, rollback and command rules.

## State, journal and outbox

Read references/outbox.md for atomic state, journal and outbox writes; producer, sender, ordering,
retry and actor rules.

## Migrations

- A schema change is the next numbered file under `packages/core/src/store/migrations/` plus its
  pin in `PINS` in `packages/core/test/store/migrations.test.ts`; a missing pin fails with the
  line to add (`packages/core/test/store/migrations.test.ts`, `describe('migrate')`).
- Never edit a committed migration file. Changing the pin of an existing file is a review
  blocker (`packages/core/test/store/migrations.test.ts`, `describe('migration pins')`).
- In the same commit, update the row types in `packages/core/src/store/schema.ts`, `sampleRows`
  in `packages/core/test/store/sample-rows.ts` (in foreign key order), and `INDEXES` in
  `packages/core/test/store/migrations.test.ts` (`packages/core/test/store/store.test.ts`,
  `describe('openStore')`; `packages/core/test/store/migrations.test.ts`, `describe('migrate')`).
- When moving a row type out of `schema.ts`, check its package export: `packages/core/src/index.ts`
  re-exports schema types, not types moved to another file.
- The runner owns the transaction, `foreign_keys`, `user_version` and the backup (`migrate` in
  `packages/core/src/store/migrate.ts`). A migration file has no `BEGIN`, `COMMIT`, `PRAGMA` or
  `VACUUM`.
- Back up every file with a schema before migration with `copyDatabase`, even when
  `user_version` is zero; only an empty `sqlite_schema` needs no backup
  (`packages/core/src/store/migrate.ts`).
- Copy a database only through `copyDatabase` (`packages/core/src/store/copy.ts`): `VACUUM INTO` a
  `.partial` sibling created 0600, checkpoint a target that has a non-empty `-wal` (it can hold
  committed rows; a damaged target with a missing or empty WAL is not opened), hard-link the target
  aside, remove its empty `-wal` and `-shm`, rename, then remove the link. A kill at any step leaves
  a complete database at the target path; the caller creates the directory and holds the board lock
  (`packages/core/test/store/copy.test.ts`, `describe('copyDatabase')`).
- A change `ALTER TABLE` cannot make is a table rebuild in the same file. The runner turns
  foreign keys off and runs `foreign_key_check` before `COMMIT`.
- New tables are `STRICT` and follow the header of
  `packages/core/src/store/migrations/0001_init.sql`: timestamps as ISO-8601 UTC text, JSON as
  text checked by zod, flags as `CHECK (x IN (0, 1))` because SQLite bindings reject JS booleans.
  Enum columns are `TEXT` with no `CHECK`, so a new value needs no migration; a `CHECK` change
  would need a rebuild.
- Pair nullable identity columns in a partial unique index with per-entity non-null `CHECK`s:
  SQLite treats NULL values as distinct (`packages/core/src/store/migrations/0001_init.sql`).
- Store the token hash and approval metadata in `operator_token`, never the raw bearer value;
  verify the current row on every call so revocation is immediate.
- A migration that renames, removes or tightens stored data, adds a required column or changes
  what a value means is a user-visible break: follow `working-with-contracts` as well as these
  rules.
- A database newer than the code is refused by `assertNotNewer`
  (`packages/core/test/store/migrations.test.ts`, `describe('migrate')`).

## Testing a migration

What the migration tests cover and how to add a case for a migration that moves rows:
`references/testing-a-migration.md`.

## PRAGMAs and opening

Read references/opening.md for connection settings, file modes, backup pruning, newer-database
protection and openStore.

## Changing these rules

A PR that changes `packages/core/src/store/store.ts`, `packages/core/src/store/migrate.ts` or the
tests named here updates this skill in the same PR.

## Checks

- `pnpm check`.
Pliki w paczce (5)
  • SKILL.md 5 KB
  • references/opening.md 2 KB
  • references/outbox.md 4 KB
  • references/testing-a-migration.md 2 KB
  • references/transactions.md 4 KB

Wersje

W bazie nie ma innych skilli o nazwie working-with-storage.

Migawka bazy z 13.11.2026 · wersja paczki 5a9027c62d02 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 90building-messenger-connectors
    Pilnuje zasad bramek wiadomości: potwierdzeń, deduplikacji, odzysku luk i wyników wysyłki wychodzącej.
  • 90working-with-contracts
    Opisuje zasady zmian w pakiecie kontraktów: schematy zod, pola konfiguracji, enumy, zdarzenia dziennika i zmiany łamiące zgodność wsteczną.
  • 100ts-ddd-events
    Pomaga projektować zdarzenia domenowe w TypeScript, z magazynem zdarzeń tylko do dopisywania i wzorcem outbox.
  • 95expo-sqlite
    Obsługuje lokalne dane w aplikacjach Expo i React Native przez expo-sqlite: konfiguracja SQLite, zapytania SQL, migracje schematu, transakcje, SQLiteProvider i kv-store.
  • 90docs-outbox
    Porządkuje skrzynkę drobnych dokumentów: usuwa duplikaty, sprawdza styl i zbiera oczekujące notatki w jeden zbiorczy PR.
  • 85SQLite
    Prowadzi przez SQLite ze sterownikiem better-sqlite3 dla Node.js: konfigurację bazy, zapytania, transakcje, migracje, optymalizację wydajności i integrację z TypeScript.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.