# Database (https://v1.s3.dimah.dev/docs/db)

[`@dimah-s3/db`](https://www.npmjs.com/package/@dimah-s3/db) is an optional
plugin for [`dimahS3`](https://v1.s3.dimah.dev/docs/server/setup). It keeps object ownership, upload
state, and deletion history aligned with S3 without custom SQL on every
endpoint.

dimah-s3 works without a database. Add this plugin when you need ownership
checks, usage totals, file listings, or server-side multipart lifecycle
tracking.

## What the plugin does [#what-the-plugin-does]

- **Tracks objects** — writes and updates a row on presign, confirm, and delete
- **Enforces ownership** — each file belongs to a scope you define (for example
  `user:123`); download requires a confirmed (`active`) object owned by
  that scope; delete rejects access from another scope. This is per-caller
  tenancy, not the route `keyPrefix` check — prefix isolation always runs in
  [`@dimah-s3/server`](https://v1.s3.dimah.dev/docs/server/security#route-namespace-vs-ownership).
- **Lists files** — query by scope on the server and in the browser
- **Tracks multipart** — records in-progress uploads for ownership and stale
  cleanup; pair it with a client `UploadStore` to resume after the same local
  file is reselected

Authentication, quota values, and business rules stay application-owned. The
plugin manages object metadata and scope isolation, and can compare usage with
limits supplied by your application.

## Lifecycle [#lifecycle]

Each object moves through three statuses:

| Status    | Meaning                                |
| --------- | -------------------------------------- |
| `pending` | Upload started, not confirmed          |
| `active`  | Confirmed in S3 — verified size stored |
| `deleted` | Removed from S3                        |

Typical flow: pending → active → deleted. Aborted multipart uploads and
[purge](https://v1.s3.dimah.dev/docs/db/purge) clean up rows that never reached `active`.

## Next steps [#next-steps]

<Cards>
  <Card
    title="Database Setup"
    href="/docs/db/setup"
    description="Install, add the schema, and register the plugin."
  />
  <Card
    title="Database Lifecycle Hooks"
    href="/docs/db/lifecycle-hooks"
    description="Lifecycle hooks the plugin attaches automatically."
  />
  <Card
    title="API"
    href="/docs/db/api"
    description="List and query objects from server or browser."
  />
  <Card
    title="Purge Stale Uploads"
    href="/docs/db/purge"
    description="Remove stale pending uploads."
  />
  <Card
    title="Full example"
    href="https://github.com/dimah-kz/dimah-s3/tree/main/examples/with-db"
    description="Minimal Next.js + Drizzle setup with upload and listing."
  />
</Cards>