# db

Postgres schema and durable state: responsibilities, supported exports and extension points.

## Purpose [#purpose]

Drizzle tables and relations describe auth and application state. The package owns connection lifetimes, migrations, audit/outbox writes, Organization provisioning and scheduled-job leases. Enum subpaths are client-safe leaves.

## Public exports [#public-exports]

| Subpath                         | Target                                 |
| ------------------------------- | -------------------------------------- |
| `.`                             | `./src/index.ts`                       |
| `./audit`                       | `./src/audit.ts`                       |
| `./relations`                   | `./src/relations.ts`                   |
| `./schema`                      | `./src/schema/index.ts`                |
| `./schema/auth`                 | `./src/schema/auth.ts`                 |
| `./schema/audit`                | `./src/schema/audit.ts`                |
| `./schema/todo`                 | `./src/schema/todo.ts`                 |
| `./schema/flags`                | `./src/schema/flags.ts`                |
| `./schema/todo.enums`           | `./src/schema/todo.enums.ts`           |
| `./schema/flags.enums`          | `./src/schema/flags.enums.ts`          |
| `./schema/proposals`            | `./src/schema/proposals.ts`            |
| `./schema/webhooks`             | `./src/schema/webhooks.ts`             |
| `./schema/webhooks.enums`       | `./src/schema/webhooks.enums.ts`       |
| `./schema/proposals.enums`      | `./src/schema/proposals.enums.ts`      |
| `./provision-organization`      | `./src/provision-organization.ts`      |
| `./seed-garage`                 | `./src/seed-garage.ts`                 |
| `./schema/jobs`                 | `./src/schema/jobs.ts`                 |
| `./job-db`                      | `./src/job-db.ts`                      |
| `./schema/uploads`              | `./src/schema/uploads.ts`              |
| `./schema/uploads.enums`        | `./src/schema/uploads.enums.ts`        |
| `./schema/billing`              | `./src/schema/billing.ts`              |
| `./schema/notifications`        | `./src/schema/notifications.ts`        |
| `./schema/notifications.enums`  | `./src/schema/notifications.enums.ts`  |
| `./schema/imports`              | `./src/schema/imports.ts`              |
| `./schema/imports.enums`        | `./src/schema/imports.enums.ts`        |
| `./schema/assistant`            | `./src/schema/assistant.ts`            |
| `./schema/documents`            | `./src/schema/documents.ts`            |
| `./schema/documents.enums`      | `./src/schema/documents.enums.ts`      |
| `./schema/preferences`          | `./src/schema/preferences.ts`          |
| `./schema/security`             | `./src/schema/security.ts`             |
| `./schema/preferences.enums`    | `./src/schema/preferences.enums.ts`    |
| `./schema/catalog`              | `./src/schema/catalog.ts`              |
| `./schema/garage`               | `./src/schema/garage.ts`               |
| `./schema/garage.enums`         | `./src/schema/garage.enums.ts`         |
| `./schema/reminder`             | `./src/schema/reminder.ts`             |
| `./schema/ledger`               | `./src/schema/ledger.ts`               |
| `./schema/ledger.enums`         | `./src/schema/ledger.enums.ts`         |
| `./schema/passport`             | `./src/schema/passport.ts`             |
| `./schema/showcase`             | `./src/schema/showcase.ts`             |
| `./schema/showcase.enums`       | `./src/schema/showcase.enums.ts`       |
| `./schema/studio`               | `./src/schema/studio.ts`               |
| `./schema/studio.enums`         | `./src/schema/studio.enums.ts`         |
| `./schema/invite-link`          | `./src/schema/invite-link.ts`          |
| `./schema/data-export`          | `./src/schema/data-export.ts`          |
| `./schema/data-export.enums`    | `./src/schema/data-export.enums.ts`    |
| `./schema/erasure`              | `./src/schema/erasure.ts`              |
| `./schema/vehicle-member`       | `./src/schema/vehicle-member.ts`       |
| `./schema/vehicle-member.enums` | `./src/schema/vehicle-member.enums.ts` |
| `./schema/partner`              | `./src/schema/partner.ts`              |
| `./schema/partner.enums`        | `./src/schema/partner.enums.ts`        |
| `./schema/history-transfer`     | `./src/schema/history-transfer.ts`     |
| `./schema/moment`               | `./src/schema/moment.ts`               |
| `./schema/moment.enums`         | `./src/schema/moment.enums.ts`         |
| `./schema/insight`              | `./src/schema/insight.ts`              |
| `./schema/insight.enums`        | `./src/schema/insight.enums.ts`        |
| `./schema/ai-usage`             | `./src/schema/ai-usage.ts`             |
| `./schema/ai-usage.enums`       | `./src/schema/ai-usage.enums.ts`       |
| `./erase-user`                  | `./src/erase-user.ts`                  |
| `./tenancy`                     | `./src/tenancy.ts`                     |
| `./testing/audit-log`           | `./src/testing/audit-log.ts`           |

These paths come from `packages/db/package.json`. A `.` entry is the package root. Conditional targets distinguish platform or type resolution; consumers should import the subpath, not its source file.

## How to extend [#how-to-extend]

AutoFolio's tables (ADR-0015) live in `preferences`, `catalog`, `garage`, `ledger` and `passport`. ★ tables are append-only: `app_tenant` may only select and insert, and the `append_only` trigger refuses UPDATE, DELETE and TRUNCATE for every role, except the cascade that erases a whole Organization (or User). `db:seed:autofolio <email> [pt|en|de]` loads `handoff/data/seed.json` into that User's personal Organization, idempotently and on local databases only. The rows come from `./seed-garage`, which opens no connection and reads no file, so the dev-only [seed sign-in](/docs/development/environments#dev-seed-sign-in) reuses it.

Generate and review a journaled migration. Register needed relations in the schema aggregate. Keep enum values in import-free leaves and scope domain rows by Organization. Use transactions for domain changes and their audit/outbox records.

Read the [postgres schema and durable state guide](/docs/features/database) for the full flow.

## Key files [#key-files]

- [`packages/db/package.json`](https://github.com/CarlosZiegler/autofolio/blob/main/packages/db/package.json)