Skip to content

Reference Data

Seed reference data with r.referenceData.

  • Declarative reference rows loaded at boot
  • Idempotent seeding for lookup tables

Feature entry point: src/feature.ts.

Needs the Postgres from the repo root’s docker-compose.yml (docker compose up -d); TEST_DATABASE_URL defaults to postgresql://kumiko:kumiko@localhost:15432/kumiko_test.

Terminal window
cd samples/recipes/reference-data
bun test

The feature entry point — embedded straight from the source file, so the code here is exactly what runs. Multi-file samples keep their remaining files next to it on GitHub (link below):

// Reference Data Sample
// Shows: r.referenceData() for static seed data with upsert logic
import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
export const categoryEntity = createEntity({
name: "category",
table: "read_sample_categories",
fields: {
code: createTextField({ personal: false, reason: "is_reference_data", required: true }),
name: createTextField({ personal: false, reason: "is_reference_data", required: true }),
description: createTextField({ personal: false, reason: "is_reference_data" }),
},
});
// Read-model table for direct DB queries in tests
export const categoryTable = buildEntityTable(categoryEntity);
export const categoryFeature = defineFeature("catalog", (r) => {
r.entity(categoryEntity);
// Static reference data — seeded on boot, upserted on changes
r.referenceData({
entity: "category",
data: [
{ code: "electronics", name: "Electronics", description: "Phones, laptops, tablets" },
{ code: "clothing", name: "Clothing", description: "Shirts, pants, shoes" },
{ code: "books", name: "Books", description: "Fiction and non-fiction" },
{ code: "food", name: "Food & Drinks", description: "Groceries and beverages" },
],
upsertKey: "code",
});
});

📄 On GitHub: samples/recipes/reference-data/src/feature.ts