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



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

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

Before executing operations, `@dimah-s3/db` resolves the active session scope via `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 custom route guards interact with db plugin hooks?">
    Plugin guards run **first** to verify scope ownership. Your custom route and feature guards run **second** for application-specific authorization.
  </Accordion>
</Accordions>