# Database

> For agents: start with the [agent guide](https://ratstack.sh/llms.txt). Every page is Markdown by default; add `Accept: text/html` for HTML.

New on /news: [Foldkit 0.171.0 requires result Message schemas](/news).

## What it does

The database [cartridge](/lore/cartridges), `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](/systems/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](/systems/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

1. [rat-stack/packages/database/src/run-log.ts at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/packages/database/src/run-log.ts)
   GitHub joelhooks/rat-stack. RunLog service; used for the storage boundary and typed failures. Accessed 2026-10-01.

2. [rat-stack/packages/database/src/vendor.ts at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/packages/database/src/vendor.ts)
   GitHub joelhooks/rat-stack. Vendor choice; used for D1 and Hyperdrive Postgres selection. Accessed 2026-10-01.

3. [rat-stack/packages/database/test/run-log.test.ts at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/packages/database/test/run-log.test.ts)
   GitHub joelhooks/rat-stack. Shared storage tests; used for the behavior checked on both vendors. Accessed 2026-10-01.

4. [rat-stack/packages/database/test/migration-paths.test.ts at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/packages/database/test/migration-paths.test.ts)
   GitHub joelhooks/rat-stack. Migration tests; used to verify loading outside the package. Accessed 2026-10-01.

## Lore on this page

- [Handle expected failures without hiding defects](/lore/error-model)
- [Workers answer requests; Durable Objects own named state](/lore/workers-answer-requests-durable-objects-own-named-state)
- [One schema, three surfaces](/lore/one-schema-three-surfaces)

## Linked from

- A clean playground → rat-stack does real work with packages that stay easy to add and remove. → [Read page](https://ratstack.sh/lore/a-clean-playground)

- Agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms.txt)

- Auth → Email and password sign-in through Better Auth, with the signed-in person provided to each RPC call. → [Read page](https://ratstack.sh/systems/auth)

- Build and run rat-stack (README.md) → What is in the repo, how the example works, and how to run it. → [Read page](https://ratstack.sh/README.md)

- Change log → What changed in the files served here, newest first. → [Read page](https://ratstack.sh/log)

- Durability → Seven durable Effect patterns, each with its seam, its fence, and the incident that taught it. → [Read page](https://ratstack.sh/systems/durability)

- Full agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms-full.txt)

- Infrastructure as effects → Sam Goodwin relates application operations to infrastructure requirements in one typed program. → [Read page](https://ratstack.sh/lore/infrastructure-as-effects)

- Rat Stack systems | rat-stack → The systems rat-stack ships, the standard each keeps, and how to check it. → [Read page](https://ratstack.sh/systems)

- 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. → [Read page](https://ratstack.sh/skills/security-audit)

- Source change history (log.md) → The generated change log as Markdown. → [Read page](https://ratstack.sh/log.md)
