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.¶

Auth¹⁸ uses the selected database vendor in the web development backend and the optional private LearnFeedbackAuth Worker⁶⁰. AUTH_ENABLED controls the public feedback sign-in surface²⁶. The database foundation stays declared when that surface is off. See apps/site/src/auth/foundation.ts and apps/site/src/auth/private-worker.ts for the composition.¶

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.¶
A Hyperdrive Postgres query leases its pool for the query and releases it after 250 ms idle. A request never holds the pool across a provider wait. See Durability¹⁰.¶

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-11-08 in c11e293. 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.
Build and run rat-stack (README.md). What is in the repo, how the example works, and how to run it.
No account auth or database (auth and database, with protected feedback and browser dev identity):
Change log. What changed in the files served here, newest first.
Database — new page: Initial commit from joelhooks/rat-stack template
Durability. Seven durable Effect patterns, each with its seam, its fence, and the incident that taught it.
ts, used by the Hyperdrive Postgres run log.
Full agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.
Infrastructure as effects. Sam Goodwin relates application operations to infrastructure requirements in one typed program.
Read Database for its current callers and local verification commands.¶
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.
security-audit. Security guidance and vulnerability review for codebases, APIs, services, CLI tools, libraries, and daemons. Use for security questions, focused reviews, vulnerability research, security audits, or pen tests. Run the complete workflow only for explicit codebase audit or pen-test requests, full/comprehensive/end-to-end reviews, or requested report artifacts.
ts provides Better Auth over the selected database vendor.
Source change history (log.md). The generated change log as Markdown.
Database — new page: Initial commit from joelhooks/rat-stack template