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



[`@dimah-s3/db`](https://www.npmjs.com/package/@dimah-s3/db) is an optional
plugin for [`dimahS3`](https://s3.dimah.dev/docs/server/setup). It keeps your database aligned
with S3 — who owns each file, whether it is still uploading, and when it was
removed — 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 resumable multipart uploads backed
by metadata.

## 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
* Lists files — query by scope on the server and in the browser
* Handles multipart — records in-progress uploads so you can resume or purge
  stale ones

Auth, quotas, and business rules stay in your hooks. The plugin only manages
object metadata and scope isolation.

## 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://s3.dimah.dev/docs/db/purge) clean up rows that never reached `active`.

## Next steps [#next-steps]

<Cards>
  <Card title="Setup" href="/docs/db/setup" description="Install, add the schema, and register the plugin." />

  <Card title="Hooks" href="/docs/db/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" 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>