What Really Happens to Your Data When You Type tdk up: A Sequence Diagram With the Database

The earlier diagrams followed the containers. Most real problems in a local stack are about data: a table that is missing, a seed that ran twice, a database that came back empty. This article extends the tdk up sequence to cover the database, so you can see where the data lives and what each step does to it.

The facts below come from TDK's data guide, which records what was run against a real Postgres container, and from the open issues. Where something is not verified, the article says so, and the diagram marks those steps.

The sequence

sequenceDiagram
    autonumber
    actor Dev as Developer
    participant CLI as tdk CLI
    participant Tilt as Tilt
    participant PG as Postgres container (one per project)
    participant Vol as Named volume
    participant Mig as migrator resource
    participant Seed as seed job (optional)
    participant API as API service (per stack)

    Dev->>CLI: tdk up
    CLI->>Tilt: start the project
    Tilt->>PG: start project_postgres on host port 15432 or TDK_POSTGRES_PORT
    PG->>Vol: mount database-management_project_postgres_data
    Vol-->>PG: existing data reused, or empty on first run
    PG-->>Tilt: ready to accept connections

    Note over Tilt,PG: DATABASE_URL points each service at project_stack

    Tilt->>Mig: run migrations once, in their own resource
    Mig->>PG: apply pending migrations in order
    PG-->>Mig: applied migrations recorded
    Mig-->>Tilt: done

    opt seed job is declared
        Tilt->>Seed: run seed as one-shot job, restart no
        Seed->>PG: insert fake data
        Note over Seed,PG: order against migrator and API not verified yet
    end

    Tilt->>API: start after dependencies
    API->>PG: connect with DATABASE_URL
    PG-->>API: queries served
    API-->>Tilt: health route answers

    Dev->>CLI: tdk down
    CLI->>Tilt: tear down
    Tilt->>PG: remove the container
    Note over PG,Vol: the named volume is kept, so the data survives

What lives where

TDK runs one Postgres container for the whole project. The container is named after the project, such as my_shop_postgres. Each stack gets its own database inside it, named from the project and the stack. Services in the same stack share that database, through the DATABASE_URL in their generated configuration.

The data sits in a named volume. The data guide checked that tdk down removes the container but keeps the volume, so the next tdk up starts Postgres on the same data. That is the most useful fact in this article, and also the most surprising one, because a fresh container does not mean a fresh database.

The host port defaults to 15432, or whatever TDK_POSTGRES_PORT says. The data guide gives 15432 as the host port, and an earlier scratch run chose it when 5432 was taken.

The migrator

Migrations run in their own resource, the migrator, which the repo's contributor guidance requires for new examples. It starts after Postgres is ready and before the API. Migrations are applied once, in order, and the migration tool records which ones have run, so a restart does not reapply them. The exact recording depends on the migration tool you choose.

If the database comes back empty after a reset, the migrator runs again on the next tdk up, or when you restart the migrator resource in Tilt. An empty database is not an error. It is the state before the migrations run.

Seeding

A seed loads fake data for development. The data guide suggests two options. A SQL file applied by hand is fine for a pilot. A one-shot resource is the other option: the seed runs as a bring-your-own job with --restart no, the same way as a migration.

The guide also says the order of the seed, the migrator, and the API is not verified. The safe answer is to make the seed idempotent, so running it in a different order does no harm. The open issue that would make startup order explicit for Postgres is #531.

Keep seed data fake. Never put production data in the repository.

Resetting the data

Two resets are covered by the guide. To reset everything, stop the stack, remove the volume, and start again. To reset one stack, drop and recreate its database while Postgres is running, using DROP DATABASE ... WITH (FORCE) so the service disconnects first.

Each reset has a cost. Removing the volume deletes every stack's data. Dropping one database deletes only that stack's data, but the services in that stack lose their state until the migrator runs again.

Snapshot and restore

The guide also describes a snapshot and restore for one database. Take the snapshot before a risky change, and test the restore once. A backup you have never restored is a guess.

What the diagram does not show

It does not show the exact order of the seed, the migrator, and the API, because that order is not verified in the guide. It does not show how a migration tool such as Prisma, Drizzle, Atlas, or Dbmate runs its own steps, since that depends on your choice. And it assumes one Postgres per project, which is how the data guide describes TDK.

Summary

One tdk up starts one Postgres for the project, mounts a volume that outlives the container, runs the migrator once, optionally runs a seed, and then starts the API against its stack's database. tdk down removes the container and keeps the data. Read the volume, not the container, when you ask where your data went.

Comments

[tdk-cli]

cool!