Schema & Caching

Every generation run starts by introspecting the source database — reading its schemas, tables, columns, and constraints. On a large or remote database this phase can take seconds. Weavori avoids repeating it by caching the introspected schema on disk and checking whether the schema has changed on every run.

How schema caching works

On the first run against a database, Weavori introspects the full schema and writes it to the cache. On subsequent runs, it checks whether the schema has changed:

• Schema unchanged — the cached schema is used and the introspection phase is skipped entirely.
• Schema changed — Weavori re-introspects automatically and refreshes the cache entry.

No manual action is needed for invalidation: creating or dropping tables and columns, altering constraints, or changing enum types is detected automatically on the next run.

What gets cached

Cache entries live in ~/.weavori/cache — one file per database:

~/.weavori/cache/

Each entry contains only the database identity (host, port, database, user) and the introspected schema. Passwords never touch the cache — they are stripped before any cache key or file is derived, so connection credentials are never written to disk.

Safe by design

Three properties make the cache safe to leave on:

• Versioned — cache entries are tied to the CLI's on-disk format. When a new release changes the format, old entries are ignored automatically; no manual cleanup after upgrades.
• Atomic — entries are written atomically, so parallel runs against the same database never see a half-written cache.
• Best-effort — cache problems never block generation. If an entry is missing or unreadable, Weavori falls back to a full introspection.

Bypassing the cache with --no-cache

The --no-cache flag on weavori generate skips both the cache read and the cache write — forcing a full re-introspection and leaving no entry behind:

Because automatic invalidation already handles schema changes, --no-cache is not needed for correctness after DDL edits. Use it when you want an explicit fresh start:

• CI pipelines — deterministic fresh introspection on every run, regardless of what state the runner's home directory is in.
• Ephemeral environments — scratch containers or throwaway VMs where nothing is worth persisting.
• Debugging — ruling out the cache when generation behaves unexpectedly.

Clearing the cache with weavori cache clear

The cache command has a single subcommand that deletes every entry in the cache directory:

Output

2026-08-11T09:00:00Z INFO  Cleared 3 cached schema(s).

weavori cache clear is safe to run at any time:

• Entries regenerate automatically on the next run — clearing costs nothing but one re-introspection.
• It is the right response if you suspect stale behavior, for example after switching branches or CLI versions.
• If nothing has been cached yet, it prints a notice and exits successfully.

Best practices by environment

Where the cache lives

The cache directory is created on first use and contains only Weavori cache entries. Removing the whole directory is equivalent to running weavori cache clear.