---
title: "Persistence And Migrations"
description: "How executor stores source state today and how migration logic is intended to work."
---

Executor persistence is designed around durable runtime state, not just CRUD storage.

That means the database stores:

- installation and workspace identity
- source bindings
- recipes and revisions
- raw documents
- schema bundles
- operations
- credentials and auth sessions
- executions and interactions

## Why the storage is layered

The storage model is layered because these concerns have different reuse and ownership semantics.

Examples:

- raw documents are provenance
- revisions are compiled materializations
- operations are the hot-path query surface
- source bindings are workspace-local
- credentials are private and actor-scoped

Trying to collapse those into one table or one document shape causes churn quickly.

## What is normalized vs serialized

Executor intentionally uses both relational columns and serialized JSON.

Normalized:

- ownership
- ids and references
- search and lookup fields
- status and visibility
- auth/session ownership

Serialized:

- adapter-owned binding config
- source config blobs
- provider metadata
- some session payloads

This is deliberate.
The rule is to normalize what the core system queries and enforces, and serialize what belongs to adapter-specific contracts.

## Migrations philosophy

The intended migration model is:

- SQL migrations move structural schema into the new shape
- one-shot code migrations repair or rebuild data that SQL cannot derive sanely
- steady-state runtime paths should not carry compatibility branches forever

That last point matters.
Compatibility logic belongs in upgrade code, not in normal reads and writes.

## What is still acceptable in migration code

One-shot rebuilds are still acceptable when:

- the old data shape is structurally valid but not yet in the best compiled form
- the rebuild can be derived from already-stored documents
- the logic is ledgered and run once

What is not acceptable:

- provider-specific legacy fallbacks in steady-state runtime logic
- carrying old columns indefinitely because one path still reads them

## Why this supports extensibility

This persistence shape is meant to let new integrations land in one of two ways:

- add a new adapter that compiles into the same source model
- add a genuinely new top-level primitive if the thing is not really a source

That is how executor avoids turning every new integration into another schema redesign.