Database Setup

This guide assumes you already have Drizzle, Prisma, or Kysely connected to a database. A working reference is examples/with-db (Next.js + Drizzle + SQLite).

Upgrading from 1.x? The tables changed: follow Upgrade the schema first.

npm i @dimah-s3/db@beta

import { dimahS3Tables } from "@dimah-s3/db/drizzle/sqlite"; // or /pg, /mysql

export const { storageObject, storageFolder, private_dimah_s3_settings } =
  dimahS3Tables;

// Your own tables go here.

npx drizzle-kit push

import { DimahS3DB } from "@dimah-s3/db";
import { drizzleAdapter } from "@dimah-s3/db/adapters/drizzle";
import Database from "better-sqlite3";
import { defineRelations } from "drizzle-orm";
import { drizzle } from "drizzle-orm/better-sqlite3"; // or your driver
import * as schema from "../db/schema";

export const db = drizzle({
  client: new Database("local.db"),
  relations: defineRelations(schema),
});

export const dimahS3Db = DimahS3DB.client(
  drizzleAdapter({ db, provider: "sqlite" }), // or "postgresql" | "mysql"
);

import { S3Client } from "@aws-sdk/client-s3";
import { db } from "@dimah-s3/db";
import { dimahS3, route } from "@dimah-s3/server";
import { getSession } from "@/lib/auth"; // your auth
import { dimahS3Db } from "@/lib/dimah-s3-db";

const awsS3 = new S3Client({ requestChecksumCalculation: "WHEN_REQUIRED" });

export const s3 = dimahS3({
  client: awsS3,
  bucket: process.env.S3_BUCKET!,
  plugins: [
    db({
      client: dimahS3Db,
      getSession: (request) => getSession(request),
      resolveScope: ({ session }) =>
        session ? `user:${session.userId}` : null,
    }),
  ],
  routes: {
    files: route({
      upload: { maxFileSize: 20 * 1024 * 1024 },
      download: true,
      delete: true,
    }),
  },
});

await s3.db.checkSchema();
const page = await s3.db.objects.list({ scope: "user:123", folder: null });

ScopeCopy Anchor Link

Every row belongs to a scope, such as user:123 or org:acme. Upload tickets are bound to it, so a ticket from one scope cannot confirm or complete an upload in another.

resolveScope says who is calling. It receives the request, the session (the getSession result), the locals your guards set, the operation, and the route when the call has one. It never sees the target object: the scope comes from the caller, so the same caller gets the same scope when an upload ticket is bound, used, and confirmed. Checks on the target belong in authorize.

• getSession runs at most once per Request.
• resolveScope runs once per call, operation, and route. Two s3.api calls that share a Request but pass different locals resolve separately.

AuthorizeCopy Anchor Link

A row belongs to the scope that wrote it. A caller from another scope gets OBJECT_NOT_FOUND (404), the same as for a key with no row, so nobody learns which keys other scopes hold. (An upload to a key another scope holds gets FORBIDDEN: upload keys are the server's choice.) authorize runs after that check and can only narrow it: return false to reject the request with FORBIDDEN (403).

It gets the scope context plus the resolved scope, and what the call targets: the key, the target folder of an upload, a listing, a move, or a folder endpoint, and on upload the client's clientMetadata. object is the stored row when the request targets one: confirm, the multipart calls, download, delete, read, and update. It is the server view, with scope, s3Metadata, and the attributes as stored, not what attributes.toClient sends the browser.

An upload on a replace: "overwrite" route that replaces an active object runs authorize with object set to that object, and folder is that object's folder, not clientMetadata.folder.

const inArchive = (path?: string | null) =>
  path === "archive" || path?.startsWith("archive/") === true;

db({
  client: dimahS3Db,
  getSession,
  resolveScope: ({ session }) => (session ? `user:${session.userId}` : null),
  // `archive/` is read-only.
  authorize: ({ operation, folder, object }) => {
    if (["list", "read", "download"].includes(operation)) return true;
    return !inArchive(folder) && !inArchive(object?.folder);
  },
});

Plugin optionsCopy Anchor Link

import type { DbPluginOptions } from "@dimah-s3/db";

quota and attributes are covered in the API page.

Route optionsCopy Anchor Link

Set per-route options under plugins: { db: … }:

routes: {
  // One key per user: a new upload replaces the old avatar instead of
  // failing with OBJECT_EXISTS. `requireUserId` is your auth helper.
  avatar: route({
    upload: {
      fileTypes: ["image/*"],
      object: async ({ request }) => ({
        key: `${await requireUserId(request)}/avatar`,
      }),
    },
    download: true,
    plugins: { db: { replace: "overwrite" } }, 
  }),
  // Not tracked: no rows, no ownership checks.
  public: route({
    upload: true,
    download: { guard: requireAdmin },
    plugins: { db: false }, 
  }),
},

With replace: "overwrite", the row stays active and keeps the previous object's metadata until the new upload is confirmed; S3 replaces the bytes as soon as the new PUT lands. The row keeps its folder, attributes, and createdAt. Until then, quota counts the larger of the two sizes. A retried confirm of the upload before it still succeeds, even after the overwrite started.

plugins: { db: false } turns off tracking and every db hook for the route. Its upload tickets are not bound to a scope. When such a route enables download or delete with no route or feature guard, the plugin logs a warning at startup: nothing then checks who owns the object.

Delete behaviorCopy Anchor Link

App deletes always go through the normal server delete path (api.delete, the Delete component, useDelete, or your own delete hooks). s3.db.objects has no delete method: it never touches S3.

When that path runs:

1. S3: DeleteObject removes the object.
2. Database: deleteMode decides (default "soft").

A pending row whose object never landed (a closed tab, a network error) is cleaned up the same way, so it stops counting toward the quota before purge runs. A multipart upload in flight is aborted first. Deleting a soft-deleted object again succeeds, like a plain S3 delete. A key with no row is OBJECT_NOT_FOUND: its owner cannot be checked.

Listings hide soft-deleted rows by default.

db({
  client: dimahS3Db,
  resolveScope,
  deleteMode: "hard", 
});

Frequently asked questionsCopy Anchor Link

await s3.put(
  {
    route: "files",
    name: "report.csv",
    type: "text/csv",
    body: csv,
    clientMetadata: { folder: "reports" },
  },
  { request },
);

CLICopy Anchor Link

runCli runs the FumaDB CLI against your client, for example to generate an ORM schema. Prefer migrate(client) to migrate: the CLI's migrate command jumps straight to the latest schema and skips the 2.0.0 indexes. Only migrate:up, one version at a time, runs them.

import { runCli } from "@dimah-s3/db/cli";
import { dimahS3Db } from "@/lib/dimah-s3-db";

await runCli(dimahS3Db);

The shipped tables, models, and SQL files already include these indexes: