Files and records

Storage holds the bytes; your database holds the meaning. The pattern: store the file’s key on a record and build the URL when you need it.

Store the key, not the URL

A URL can change (a signed link expires, a domain moves). A key doesn’t. Keep the key in a column such as avatar_key and build the link on read. First add the column in Studio: Data → profiles → Columns → Add column avatar_key, type Text (short), and apply the migration (Columns and types).

const key = `${user.id}/avatar-${crypto.randomUUID()}.png`;
await pawabase.storage.from("avatars").upload(key, file);
await pawabase.from("profiles").update(profile.id, { avatar_key: key });

// Later, to display it
const src = pawabase.storage.from("avatars").getPublicUrl(profile.avatar_key);

key = f"{user_id}/avatar-{uuid.uuid4()}.png"
pb.storage.from_("avatars").upload(key, open("avatar.png", "rb"), content_type="image/png")
pb.from_("profiles").update(profile["id"], avatar_key=key)

src = pb.storage.from_("avatars").public_url(profile["avatar_key"])

Upload first, then save the key, so a record never points at a file that doesn’t exist.

Replace a file

Give the new file a new key, update the record, then delete the old key. A fresh key avoids stale caches.

const old = profile.avatar_key;
await bucket.upload(newKey, file);
await pawabase.from("profiles").update(profile.id, { avatar_key: newKey });
if (old) await bucket.remove(old);

old = profile.get("avatar_key")
bucket.upload(new_key, data)
pb.from_("profiles").update(profile["id"], avatar_key=new_key)
if old:
    bucket.remove(old)

Several files per record

Create an attachments table in Studio (Data → Create table): record_id, key, name, size, content_type. Save the name the person chose in name; the key itself should be generated. Give the table the owner quick set (Access tab) and an owner column.

const key = `${user.id}/${crypto.randomUUID()}`;
await bucket.upload(key, file);
await pawabase.from("attachments").create({ record_id: task.id, key, name: file.name, size: file.size, content_type: file.type });

Clean up

Deleting a record doesn’t delete its files. Remove them with the record:

async function deleteTask(task: Task) {
  const { data: files } = await pawabase.from("attachments").eq("record_id", task.id);
  for (const f of files) await bucket.remove(f.key);
  await pawabase.from("attachments").delete(/* each id */);
  await pawabase.from("tasks").delete(task.id);
}

Or set up a flow in Studio that listens for the delete event and removes the files (Automation), so cleanup happens even when the delete came from elsewhere.

Quotas

Largest file caps one file. Your plan caps total storage; uploads beyond it fail (in Python as QuotaExceededError, a kind of ForbiddenError). See usage under Project → Usage & plan in Studio.

Keeping data and files consistent

Risk	Defence
Record saved, upload failed	Upload first
Upload succeeded, record failed	A periodic job lists a prefix and removes keys no record references
Same key reused	Generate keys
Someone swaps `avatar_key` for another person’s file	Rule on the table limits who may update; the bucket rule limits who may read

Upload

Upload and handle errors.

Patterns

Complete designs.

Getting started

Set up in Studio

Use it from your app

Protect and build

Files and records

Store the key, not the URL

Replace a file

Several files per record

Clean up

Quotas

Keeping data and files consistent

Upload

Patterns

​Store the key, not the URL

​Replace a file

​Several files per record

​Clean up

​Quotas

​Keeping data and files consistent

Upload

Patterns

Store the key, not the URL

Replace a file

Several files per record

Clean up

Quotas

Keeping data and files consistent