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

add-migration

/add-migration

Dodaje migrację do istniejącego potoku (schemat, snapshot, wektory sparse), aby uaktualnić trwały stan na dysku, np. przy nowym indeksie Qdrant czy zmianie formatu snapshotu.

Repozytorium
tearags-mcp ↗
Licencja
MIT
Ostatnia zmiana repozytorium
18.10.2026

Ocena i bezpieczeństwo

100/ 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ść35 / 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
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 18.10.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

Dodaje migrację do istniejącego potoku (schemat, snapshot, wektory sparse), aby uaktualnić trwały stan na dysku, np. przy nowym indeksie Qdrant czy zmianie formatu snapshotu.

Wyzwalacze z opisu

new Qdrant indexbackfill payload fieldsnapshot format changerebuild sparse vectorsновая миграция
Oryginalny opis (EN)

Add migration to existing pipeline (schema, snapshot, sparse) to upgrade persisted on-disk state. Triggers on "new Qdrant index", "backfill payload field", "snapshot format change", "rebuild sparse vectors", "новая миграция". NOT for code-only changes that don't touch persisted state on disk.

Jak działa

  1. Pick Template First (MUST decide before scrolling)
  2. Store Interface First (MUST do before any template)
  3. Step 0: Determine Pipeline
  4. Step 1: Determine Version Number
  5. Step 2: Create Migration File
  6. Step 3: Register in Runner
  7. Step 4: Extend Store Interface (if needed)
  8. Step 5: Update Factory (if needed)
  9. Step 6: Write Tests
  10. Step 7: Verify
Sekcje z nagłówków SKILL.md, w oryginale · 308 linii, 1 157 słów
Podgląd SKILL.md
---
name: add-migration
description:
  Add migration to existing pipeline (schema, snapshot, sparse) to upgrade
  persisted on-disk state. Triggers on "new Qdrant index", "backfill payload
  field", "snapshot format change", "rebuild sparse vectors", "новая миграция".
  NOT for code-only changes that don't touch persisted state on disk.
---

# Add Migration

## Pick Template First (MUST decide before scrolling)

| Migration intent                                            | Pipeline target | Template to use                                  |
| ----------------------------------------------------------- | --------------- | ------------------------------------------------ |
| Create new Qdrant index on existing collection              | schema          | Template A — Schema migration (index creation)   |
| Add a new schema migration that may be skipped by flag      | schema          | Template B — Schema migration (conditional)      |
| Backfill or transform a new payload field across all points | schema          | Template C — Schema migration (payload backfill) |
| Rebuild BM25 / sparse vectors with a new model              | sparse          | Template D — Sparse migration                    |
| Change snapshot file format on disk                         | snapshot        | Template E — Snapshot migration                  |

🛑 Pick ONE row before scrolling further. Do NOT merge templates.

## Store Interface First (MUST do before any template)

🛑 Migration needs new store capability (interface method) → STOP, add interface
FIRST. Migrations against missing interfaces silently no-op.

### Extend Store Interface (if needed)

Migration needs capabilities not in existing store interface:

1. Add method to interface in `src/core/domains/maintenance/migration/types.ts`
2. Implement in adapter:
   `src/core/domains/maintenance/migration/adapters/<store>-adapter.ts`
3. Update mock in tests

**Do NOT** inject `QdrantManager` or other concrete classes directly into
migrations.

### Update Factory (if needed)

Migration needs new constructor args → update
`src/core/api/internal/ingest-dependencies.ts` → `createIngestDependencies()` to
pass them (the `IngestDependencies` contract lives in
`src/core/domains/ingest/pipeline/dependencies.ts`).

Step-by-step process for adding a migration to one of three pipelines.

## Step 0: Determine Pipeline

| If you need to...                    | Pipeline   |
| ------------------------------------ | ---------- |
| Create/modify Qdrant index           | `schema`   |
| Backfill or transform payload fields | `schema`   |
| Enable/reconfigure sparse vectors    | `schema`   |
| Rebuild BM25 sparse vectors          | `sparse`   |
| Change snapshot file format          | `snapshot` |

## Step 1: Determine Version Number

Read runner constructor to find highest existing version:

| Pipeline   | Runner file                                                   |
| ---------- | ------------------------------------------------------------- |
| `schema`   | `src/core/domains/maintenance/migration/schema-migrator.ts`   |
| `snapshot` | `src/core/domains/maintenance/migration/snapshot-migrator.ts` |
| `sparse`   | `src/core/domains/maintenance/migration/sparse-migrator.ts`   |

New version = highest existing + 1.

## Step 2: Create Migration File

**File**:
`src/core/domains/maintenance/migration/<pipeline>_migrations/<pipeline>-v<N>-<description>.ts`

### Template — Schema migration (index creation)

```typescript
import type { IndexStore } from "../types.js";
import type { Migration, StepResult } from "../types.js";

export class SchemaV<N><PascalDescription> implements Migration {
  readonly name = "schema-v<N>-<description>";
  readonly version = <N>;

  constructor(
    private readonly collection: string,
    private readonly store: IndexStore,
  ) {}

  async apply(): Promise<StepResult> {
    await this.store.ensureIndex(this.collection, "<field>", "<type>");
    return { applied: ["<field>:<type>"] };
  }
}
```

### Template — Schema migration (conditional)

```typescript
import type { IndexStore } from "../types.js";
import type { Migration, StepResult } from "../types.js";

export class SchemaV<N><PascalDescription> implements Migration {
  readonly name = "schema-v<N>-<description>";
  readonly version = <N>;

  constructor(
    private readonly collection: string,
    private readonly store: IndexStore,
    private readonly enabled: boolean,
  ) {}

  async apply(): Promise<StepResult> {
    if (!this.enabled) {
      return { applied: ["<description> — skipped (<reason>)"] };
    }
    // ... actual migration logic
    return { applied: ["<what was done>"] };
  }
}
```

### Template — Schema migration (payload backfill)

```typescript
import type { EnrichmentStore } from "../types.js";
import type { Migration, StepResult } from "../types.js";

export class SchemaV<N><PascalDescription> implements Migration {
  readonly name = "schema-v<N>-<description>";
  readonly version = <N>;

  constructor(
    private readonly collection: string,
    private readonly store: EnrichmentStore,
  ) {}

  async apply(): Promise<StepResult> {
    const alreadyDone = await this.store.isMigrated(this.collection);
    if (alreadyDone) {
      return { applied: ["already migrated — skipped"] };
    }

    const points = await this.store.scrollAllChunks(this.collection);
    // ... transform and batch update
    await this.store.markMigrated(this.collection);
    return { applied: [`backfilled ${points.length} points`] };
  }
}
```

### Template — Sparse migration

```typescript
import type { SparseStore } from "../types.js";
import type { Migration, StepResult } from "../types.js";

export class SparseV<N><PascalDescription> implements Migration {
  readonly name = "sparse-v<N>-<description>";
  readonly version = <N>;

  constructor(
    private readonly collection: string,
    private readonly store: SparseStore,
    private readonly enableHybrid: boolean,
  ) {}

  async apply(): Promise<StepResult> {
    if (!this.enableHybrid) {
      return { applied: ["sparse rebuild — skipped (hybrid disabled)"] };
    }
    await this.store.rebuildSparseVectors(this.collection);
    return { applied: ["rebuilt sparse vectors"] };
  }
}
```

### Template — Snapshot migration

```typescript
import type { SnapshotStore } from "../types.js";
import type { Migration, StepResult } from "../types.js";

export class SnapshotV<N><PascalDescription> implements Migration {
  readonly name = "snapshot-v<N>-<description>";
  readonly version = <N>;

  constructor(private readonly store: SnapshotStore) {}

  async apply(): Promise<StepResult> {
    const data = await this.store.readV<prev>();
    if (data === null) {
      return { applied: ["no v<prev> data — skipped"] };
    }
    // ... transform data to new format
    // ... write new format
    return { applied: ["converted from v<prev> to v<N>"] };
  }
}
```

## Step 3: Register in Runner

Add new migration to runner constructor's `this.migrations` array.

**Schema** (`schema-migrator.ts`):

```typescript
this.migrations = [
  // ... existing migrations ...
  new SchemaV10NewfieldKeyword(collection, indexStore), // unconditional
  new SchemaV11SparseUpdate(collection, indexStore, options.X), // conditional on flag
];
```

**Conditional inclusion** (optional dependencies):

```typescript
...(enrichmentStore
  ? [new SchemaV12BackfillTimestamps(collection, enrichmentStore)]
  : []),
```

**Sparse** (`sparse-migrator.ts`):

```typescript
this.migrations = [
  // ... existing migrations ...
  new SparseV2VectorRebuild(collection, store, enableHybrid),
];
```

**Snapshot** (`snapshot-migrator.ts`):

```typescript
this.migrations = [
  // ... existing migrations ...
  new SnapshotV4ToCompact(store),
];
```

## Step 4: Extend Store Interface (if needed)

Hoisted to top under "Store Interface First" — not yet handled → STOP, complete
before continuing.

## Step 5: Update Factory (if needed)

Hoisted to top under "Store Interface First" — not yet handled → STOP, complete
before continuing.

## Step 6: Write Tests

**File**: `tests/core/domains/maintenance/migration/<pipeline>-migrator.test.ts`

Add to existing test file or create new one for the specific migration.

### Required test cases

1. **Happy path** — migration applies and returns correct `StepResult`
2. **Skip condition** — conditional migration returns skip message when disabled
3. **Idempotency** — re-run after success is safe (or handled by version check)
4. **Integration** — runner only applies migration when version > current

### Test pattern

```typescript
describe("SchemaV10NewfieldKeyword", () => {
  it("creates index on newField", async () => {
    const store = createMockIndexStore();
    const migration = new SchemaV10NewfieldKeyword(COLLECTION, store);

    const result = await migration.apply();

    expect(store.ensureIndex).toHaveBeenCalledWith(
      COLLECTION,
      "newField",
      "keyword",
    );
    expect(result.applied).toContain("newField:keyword");
  });

  it("skips when disabled", async () => {
    const store = createMockIndexStore();
    const migration = new SchemaV10NewfieldKeyword(COLLECTION, store, false);

    const result = await migration.apply();

    expect(store.ensureIndex).not.toHaveBeenCalled();
    expect(result.applied[0]).toContain("skipped");
  });
});
```

## Step 7: Verify

```bash
npx tsc --noEmit && npx vitest run
```

## Checklist

- [ ] Version number is next integer after highest existing in pipeline
- [ ] File name follows `<pipeline>-v<N>-<kebab-description>.ts` convention
- [ ] Class implements `Migration` interface with `name`, `version`, `apply()`
- [ ] Uses store interface (NOT concrete `QdrantManager`)
- [ ] `apply()` is idempotent (safe to re-run)
- [ ] Conditional migrations return descriptive skip message
- [ ] Registered in runner constructor (correct position in array)
- [ ] Factory updated if new constructor args needed
- [ ] Store interface extended + adapter updated if new capabilities needed
- [ ] Tests cover happy path, skip condition, idempotency
- [ ] `npx tsc --noEmit && npx vitest run` passes

Wersje

RepozytoriumWynikLicencja
Ta strona · artk0de/tearags-mcp100MIT
KyRocks19/divination-station-takeoff100AGPL-3.0
kadirguloglu/kg-devkit96MIT
kadirguloglu/kg-devkit96MIT

Migawka bazy z 13.11.2026 · wersja paczki 532307db1d69 (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

  • 90add-db-migration
    Wprowadza zmiany schematu bazy danych: nowe tabele i kolumny, indeksy, ograniczenia i uzupełnianie danych, z ostrożnością wymaganą przy ryzykownych migracjach.
  • 95database-migration
    Tworzy migrację bazy danych ze zmianami schematu i wycofaniem, gdy trzeba dodać tabelę albo zmodyfikować schemat.
  • 95qdrant-hybrid-search-prefetches
    Pomaga budować zapytania prefetch w hybrydowym wyszukiwaniu Qdrant, w tym konfiguracje BM25 z wektorami gęstymi i wielu pól, oraz wybrać metodę wyszukiwania leksykalnego, na przykład BM25 lub SPLADE.
  • 100qdrant-advanced
    Obejmuje bardziej złożone funkcje Qdrant: indeksowanie payloadu, kwantyzacja, wektory nazwane i rzadkie, multi-tenancy, snapshoty, sharding, gRPC, filtrowanie przed i po wyszukiwaniu oraz rescoring.
  • 90keep-why-schema-migration
    Obsługuje odczyt i zapis magazynu kontekstu projektu oraz migrację, gdy jego schemat różni się od zainstalowanego formatu wpisów.
  • 100backend-migration-writer
    Pisze bezpieczną, odwracalną migrację bazy danych: pliki up i down, plan uzupełnienia danych, analiza budżetu blokad i strategia wycofania.

Uwagi i zgłoszenia

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