DocsConcepts

Seed cache

Content-addressed reproducibility — how seedkit decides whether to replay or regenerate.

The seed cache is the mechanism that makes seedkit seed --from-cache instant and byte-identical. This page explains how the cache key is computed and what causes hits vs. misses.

The key recipe

content_key = sha256(
  schema_normalized   // tables, columns, types, FKs — order-stable
  + seed_name         // the --seed value, e.g. "my-fixture"
  + generator_versions // pinned per release
)

schema_normalized is the schema after a normalization pass: column order is sorted, types are aliased to canonical forms (character varying(255) → varchar(255)), and FKs are reordered by referenced table.

That means renaming a column changes the key (we can't reuse the old SQL). Reordering columns does not.

Hit vs. miss

Action	Result
Run with same seed name + same schema	Hit. Cached SQL replayed in seconds. No LLM call.
Run with same seed, schema with one column renamed	Miss. Regenerated and re-cached under the new key.
Run with same seed, schema with columns reordered	Hit. Normalization absorbs the difference.
Run with `--reset` flag	Forced miss. Regenerate even if cached.
Major CLI version bump that changes generator versions	Miss. Regenerated and re-cached under the new key. The old key remains accessible to old CLI versions.

Listing what's cached

seedkit cache

KEY       SEED         SCHEMA  ROWS    HITS  LAST USED
9a2f4e01  my-fixture   a7f102  14,820  12    3m ago
1d88c0b2  demo-small   a7f102     500   4    2h ago

SCHEMA is the first 6 chars of the schema's normalized hash — useful for spotting "two seeds against the same schema."

Eviction

Free tier: LRU after 30 days of no hits.
Pro / Team: LRU after 90 days.
seedkit cache pin <name> — pin a seed indefinitely.

What about LLM cost?

Cache hits don't call the model. That's the point — the canonical CI pattern (seed --from-cache) is free of LLM cost on every run after the first.