FILE Columns & Uploads

@kalamdb/client supports file upload and retrieval patterns for KalamDB FILE columns.

Upload through Drizzle (`@kalamdb/orm`)

When you use Drizzle, pass upload bytes in .values() or .set(). You do not need a separate queryWithFiles() wrapper for ORM builders:

1import { Auth, createClient } from '@kalamdb/client';2import { kalamDriver, kalamFile } from '@kalamdb/orm';3import { drizzle } from 'drizzle-orm/pg-proxy';4import { users } from './schema';5 6const client = createClient({7  url: 'http://localhost:2900',8  namespace: 'app',9  authProvider: async () => Auth.basic('admin', 'AdminPass123!'),10});11 12const db = drizzle(kalamDriver(client));13 14await db.insert(users).values({15  id: 'user_123',16  avatar: kalamFile('avatar', avatarFile),17});

kalamFile(name, blob) marks an upload for the driver. You can also pass a File or Blob directly to a generated file() column. kalamDriver() compiles the query, rewrites upload params to FILE("name"), and calls client.queryWithFiles() automatically.

Upserts work the same way — include kalamFile(...) in both .values() and .onConflictDoUpdate().set() when the FILE column changes. See Drizzle ORM & Generator.

Upload with raw SQL (`@kalamdb/client`)

Use queryWithFiles(sql, files, params?, onProgress?) when you are not going through Drizzle:

1const avatarFile = fileInput.files?.[0];2if (!avatarFile) throw new Error('No file selected');3 4await client.queryWithFiles(5  'INSERT INTO app.users (id, avatar) VALUES ($1, FILE("avatar"))',6  { avatar: avatarFile },7  ['user_123']8);

Insert + read FileRefs (end-to-end)

1// 1) Insert a FILE via multipart upload2await client.queryWithFiles(3  'INSERT INTO app.users (id, avatar) VALUES ($1, FILE("avatar"))',4  { avatar: avatarFile },5  ['user_123'],6);7 8// 2) Read rows with FILE-aware wrappers9const rows = await client.queryRows<{ id: string; avatar: unknown }>(10  'SELECT id, avatar FROM app.users WHERE id = $1',11  'app.users',12  ['user_123'],13);14 15const avatar = rows[0]?.file('avatar');16if (avatar) {17  console.log(avatar.name, avatar.formatSize());18  console.log(avatar.downloadUrl());19}

downloadUrl() returns the authenticated file-download endpoint for the stored file path:

TEXT

1/v1/files/{namespace}/{table}/{sub}/{stored_name}

Fetch it with the same bearer token you use for SQL calls:

1const response = await fetch(avatar.downloadUrl(), {2  headers: {3    Authorization: `Bearer ${token}`,4  },5});6 7const bytes = await response.arrayBuffer();

For user tables, SDK helpers intentionally generate an owner-scoped URL without user_id. A normal user can download only files in their own user-table scope. Service-role clients may upload or write through authorized EXECUTE AS USER flows, but raw cross-user FILE downloads are reserved for dba and system tokens that explicitly add an authorized user_id query parameter.

Progress callback

In browser environments (XMLHttpRequest available), pass onProgress:

1await client.queryWithFiles(sql, files, params, (progress) => {2  console.log(progress.file_name, progress.percent);3});

Auth behavior

From source:

SDK builds auth header via buildAuthHeader(auth)
sends multipart request to POST /v1/api/sql
falls back to fetch when XHR progress is unavailable

FileRef model

file_ref.ts exposes FileRef and helpers:

1import { FileRef, parseFileRef, parseFileRefs } from '@kalamdb/client';

Parse and use file metadata

1const ref = parseFileRef(row.attachment);2if (ref) {3  console.log(ref.name, ref.size, ref.mime);4  console.log(ref.formatSize());5  console.log(ref.relativePath());6}

When rows come from queryOne/queryAll, FILE values are KalamCellValue:

1const row = await client.queryOne('SELECT avatar FROM app.users WHERE id = $1', ['user_123']);2const ref = row?.avatar.asFile();3if (ref) {4  console.log(ref.getDownloadUrl('http://localhost:2900', 'app', 'users'));5}

Build download URL

1const url = ref.getDownloadUrl('http://localhost:2900', 'app', 'users');

That URL points at /v1/files/.../{stored_name} and uses the sanitized stored filename, not the raw file id alone.

Type helpers

1ref.isImage();2ref.isVideo();3ref.isAudio();4ref.isPdf();5ref.getTypeDescription();

Storage-path internals documented by source

FileRef includes:

id, sub, name, size, mime, sha256, optional shard
filename sanitization and extension normalization
shared-table shard-aware relativePath() generation

This is useful for building file galleries, attachment viewers, and audit tooling.