SDK Guide

In Postgres-Native Cloud Storage, use app.storage.from(bucketId) to enter the object client for a specific bucket. All path parameters are object names inside the bucket; do not pass cloud:// fileIDs.

import cloudbase from '@cloudbase/js-sdk';

const app = cloudbase.init({ env: '<env-id>' });
const bucket = app.storage.from('avatars');

Choose the right task guide

Goal	Recommended doc
Create, update, or delete buckets	Bucket Management
Upload files, handle `contentType`, `upsert`, and metadata	Upload Files
Download files, create signed URLs, or public URLs	Access and Download Files
List, copy, move, or delete files	Manage Files
Naming, size, MIME, overwrite, and path design advice	Limits and Best Practices
CDN caching and Public / Private cache differences	CDN Acceleration and Caching
API signatures and type definitions	JS SDK Storage API

Core entry

const bucket = app.storage.from('avatars');

avatars maps to storage.buckets.id. All object paths below are relative to that bucket:

await bucket.upload('user-123/avatar.png', file);
await bucket.download('user-123/avatar.png');
await bucket.remove(['user-123/avatar.png']);

API cheat sheet

Bucket management

API	Description	Doc
`app.storage.createBucket()`	Create a bucket	Bucket Management
`app.storage.updateBucket()`	Update bucket config	Bucket Management
`app.storage.deleteBucket()`	Delete a bucket	Bucket Management

Upload

const { data, error } = await bucket.upload('user-123/avatar.png', file, {
  contentType: 'image/png',
  upsert: true,
  metadata: {
    usage: 'avatar',
  },
});

if (error) {
  throw error;
}

See Upload Files.

Access and download

const { data: blob } = await bucket.download('user-123/avatar.png');

const { data: signed } = await bucket.createSignedUrl('user-123/avatar.png', 600, {
  download: 'avatar.png',
});

const { data: publicUrl } = app.storage
  .from('public-assets')
  .getPublicUrl('logos/cloudbase.png');

See Access and Download Files.

Manage files

const list = await bucket.list('user-123', {
  limit: 20,
  withDelimiter: true,
});

await bucket.copy('user-123/a.png', 'user-123/b.png', { upsert: true });
await bucket.move('user-123/b.png', 'user-123/archive/b.png');
await bucket.remove(['user-123/archive/b.png']);

See Manage Files.

Permissions and errors

All SDK operations are gated by RLS policies on storage.objects / storage.buckets:

SDK operation	Main permission required
`upload()` creating a new object	`INSERT WITH CHECK`
`upload({ upsert: true })` overwriting	`INSERT` or `UPDATE`, depending on whether the object exists
`download()` / `createSignedUrl()`	`SELECT`
`list()` / `info()` / `exists()`	`SELECT`
`copy()`	Source `SELECT` + destination `INSERT` / `UPDATE`
`move()`	Source `SELECT` / `DELETE` + destination `INSERT` / `UPDATE`
`remove()`	`DELETE`

For 403 errors, check the login state, object path, bucket_id, and RLS policy. See Permission Management and FAQ.

AI-friendly prompt

When asking AI to generate SDK code, provide both the bucket contract and the desired operation:

Bucket: private-files
Path template: <uid>/<filename>
Operation: upload a PDF and create a signed download URL valid for 10 minutes
Permission: only owner can upload, read, and delete
Limits: 20 MB; application/pdf
SDK: use @cloudbase/js-sdk and app.storage.from('private-files')

Choose the right task guide​

Core entry​

API cheat sheet​

Bucket management​

Upload​

Access and download​

Manage files​

Permissions and errors​

AI-friendly prompt​

Related resources​