Database

What it does

The database cartridge³⁶, packages/database, is a package for one job, with its implementation and required infrastructure. It gives callers one service, RunLog. A service is a named interface for one job.¶

RunLog records a capability run with its outcome and lists a person’s recent runs. A capability is one named action with shared value definitions and a server-side implementation.¶

DatabaseVendor chooses where rows are stored: Cloudflare D1, or Postgres through Hyperdrive.¶

D1 is Cloudflare’s SQL database. Hyperdrive connects Workers to a Postgres database through pooled connections.¶

The chosen implementation includes its resources, Drizzle table definitions, and database migrations. Drizzle defines and queries tables in TypeScript. Migrations change the database structure.¶

Effect describes work with typed failures³⁶ and required services. Schema describes accepted values and their runtime checks.¶

The database’s one caller is auth¹⁶, which today runs only in the web app’s dev server. The deployed ratstack.sh Worker does not use it. A clone that needs people and history starts here.¶

The standard

Callers use RunLog and never see SQL, Drizzle, or the chosen implementation.¶
Choosing an implementation is one DatabaseVendor value.¶
Every input passes its Schema check before it reaches storage. Bad input fails as InvalidDatabaseInput, and a storage failure fails as DatabaseError.¶
Run ids use UUIDv7, a time-ordered identifier format. Times come from the Effect clock, so tests control both.¶
The same tests pass on both implementations.¶
Migrations load when the process starts outside the package.¶

How to check

pnpm --filter @rat-stack/database test runs the RunLog tests twice, against D1 on local SQLite and against Postgres on PGlite. They cover both outcome variants, filtering by person, limits, ordering by time then id, and rejected limits. A second test loads the migrations from outside the package.¶

Sources

rat-stack/packages/database/src/run-log.ts at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. RunLog service; used for the storage boundary and typed failures. Accessed 2026-10-01.
rat-stack/packages/database/src/vendor.ts at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. Vendor choice; used for D1 and Hyperdrive Postgres selection. Accessed 2026-10-01.
rat-stack/packages/database/test/run-log.test.ts at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. Shared storage tests; used for the behavior checked on both vendors. Accessed 2026-10-01.
rat-stack/packages/database/test/migration-paths.test.ts at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. Migration tests; used to verify loading outside the package. Accessed 2026-10-01.

Last changed 2026-10-07 in f77853d. Source on GitHub. Change log.

Linked from

A clean playground. rat-stack does real work with packages that stay easy to add and remove.
Its database cartridge owns a RunLog service and Layers for two database implementations.¶
Agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.
Database — One interface records action runs and their outcomes in either Cloudflare D1 or Postgres through Hyperdrive.
Auth. Email and password sign-in through Better Auth, with the signed-in person provided to each RPC call.
It uses the implementation chosen by the database cartridge.
Change log. What changed in the files served here, newest first.
Database — edited: feat(learn): teach cards 83 to 111 and finish the deck’s plain lines
Full agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.
Rat Stack systems | rat-stack. The systems rat-stack ships, the standard each keeps, and how to check it.
Database — One interface records action runs and their outcomes in either Cloudflare D1 or Postgres through Hyperdrive.
Source change history (log.md). The generated change log as Markdown.
Database — edited: feat(learn): teach cards 83 to 111 and finish the deck’s plain lines