Files

The generated app includes one public file path. It stores an opaque file ID in SQLite and keeps the R2 bucket, key, checksum, and upload state out of application rows.

Declare the column

Declare one nullable file() column and include it in the table policy.

src/schema.ts

import { file } from "@chardb/core/files";

export const messages = cdbTable(
  "messages",
  {
    attachment: file("attachment", {
      maxSize: 5 * 1_024 * 1_024,
      contentTypes: ["image/jpeg", "image/png"],
    }),
  },
  {
    selfBy: "authorId",
    roles: {
      member: { read: "*", create: ["id", "body", "attachment", "createdAt"] },
      self: { update: ["body", "attachment"] },
    },
  },
);

This release accepts files up to the column limit, capped by the current proxied-upload maximum. The generated example accepts JPEG and PNG files up to 5 MiB.

Bind the browser client

The browser uses a schema locator because schema.ts imports server-only Better Auth definitions.

import { fileRef } from "@chardb/core/files";

const messageAttachment = fileRef("messages", "attachment");

function Attachment({ rowId }: Props) {
  const attachment = db.useFile(messageAttachment);

  return (
    <a href={attachment.downloadUrl({ rowId })}>
      Download attachment
    </a>
  );
}

Upload before the message mutation, then store the returned opaque ID.

const post = db.useMutation(postMessage);
const uploaded = await attachment.upload({
  file: selectedFile,
  idempotencyKey: crypto.randomUUID(),
});

await post({
  id: uuidv7(),
  body,
  attachment: uploaded.fileId,
  clientCreatedAt: Date.now(),
});

The configured client adds the active organization to writes, uploads, and downloads. File routes use the Worker URL configured on createChardbReactClient, and the browser sends the Better Auth session cookie automatically. CharDB checks the active organization, current membership, table policy, row ID, and opaque file ID before returning bytes.

Do not store an R2 URL or object key. Store only the FileId returned by the upload.

Use Vectors when the row also needs semantic search.

Core

Clients

Features

Operate

Plan ahead

Cookbook

Declare the column

Bind the browser client

​Declare the column

​Bind the browser client

Declare the column

Bind the browser client