# Database Lifecycle Hooks (https://s3.dimah.dev/docs/db/lifecycle-hooks)



The [`db()`](https://s3.dimah.dev/docs/db/setup) plugin automatically attaches guards and
synchronization actions across upload, download, and delete flows.

## Access and scope validation [#access-and-scope-validation]

Before an operation runs, `@dimah-s3/db` resolves the active session scope
through `resolveScope(request)`:

| Situation                                   | Response Status      | Error Code         |
| ------------------------------------------- | -------------------- | ------------------ |
| `resolveScope` returns `null`               | **401 Unauthorized** | `UNAUTHORIZED`     |
| Target key belongs to another scope         | **403 Forbidden**    | `FORBIDDEN`        |
| Target object row not found or soft-deleted | **404 Not Found**    | `OBJECT_NOT_FOUND` |

***

## Lifecycle behavior by operation [#lifecycle-behavior-by-operation]

* **Upload** — Inserts a new row with `status: "pending"`.
* **Upload confirmation** — Verifies `pending` state, records verified `contentLength` from `HeadObject`, and transitions status to `"active"`.
* **Download** — Enforces that the object has `status: "active"` and matches the caller's scope.
* **Delete** — Runs S3 `DeleteObjectCommand`, then updates row status to `"deleted"` (soft delete) or removes it (hard delete).

## Frequently asked questions [#frequently-asked-questions]

<Accordions>
  <Accordion title="How do my route guards interact with the database plugin?">
    Your route-level `guard` runs first during route resolution. After that, the
    database plugin's operation guard verifies scope and ownership before your
    operation-specific `upload.guard`, `download.guard`, or `delete.guard`. See the
    standard [plugin hook order](https://s3.dimah.dev/docs/server/plugins#hook-execution-order).
  </Accordion>
</Accordions>