PG Cloud Storage

CloudBase JS SDK v3 PG mode provides PostgreSQL-native bucket-based cloud storage capabilities. Use app.storage.from(bucketId) to get the object client for a specific bucket. All path parameters are object names inside the bucket; do not pass cloud:// fileIDs.

Quick Start

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

const app = cloudbase.init({ env: "your-env-id" });
const bucket = app.storage.from("avatars");

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

const { data: blob } = await bucket.download("user-123/avatar.png");
const { data: signed } = await bucket.createSignedUrl("user-123/avatar.png", 3600);
await bucket.remove(["user-123/avatar.png"]);

API Methods

Bucket Client

• from() - Select a bucket and return its object client
• throwOnError() - Throw on error

File Operations

• upload() - Upload files
• update() - Update files
• download() - Download files
• remove() - Delete files
• move() - Move files
• copy() - Copy files
• list() - List objects in a bucket

URL Management

• createSignedUrl() - Create a signed URL
• createSignedUrls() - Create signed URLs in batch
• getPublicUrl() - Get a public URL
• createSignedUploadUrl() - Create a signed upload URL

File Information

• info() - Get file information
• exists() - Check whether a file exists

Bucket Management

• Bucket management - Create, query, update, and delete buckets

---

from

from(bucketId: string): PostgresNativeStorageFileApi

type PostgresNativeStorageFileApi = StorageFileApi;

参数

bucketId

string

PG Bucket ID, corresponding to `storage.buckets.id`.

返回

PostgresNativeStorageFileApi

Object

Native PG bucket object operation client.

示例

---

throwOnError

throwOnError(): this

参数

无参数

返回

this

PostgresNativeStorageFileApi

Current client instance for chaining.

示例

---

upload

Upload a file to storage.

upload(path: string, fileBody: FileBody, fileOptions?: UploadOptions): Promise<Result<UploadResult>>

type FileBody = File | Blob | ArrayBuffer | ArrayBufferView | FormData | ReadableStream<Uint8Array> | string;

type Result<T> = { data: T; error: null } | { data: null; error: StorageError };

interface UploadOptions {
  cacheControl?: string;
  contentType?: string;
  metadata?: Record<string, any>;
  upsert?: boolean; // default false
}

interface UploadResult {
  id: string;
  path: string;
  fullPath: string; // bucketId/objectName
}

参数

path

string

Object name inside the bucket, for example `user-123/avatar.png`. Do not pass `cloud://` fileIDs.

fileBody

FileBody

File content.

fileOptions

UploadOptions

Upload options. Pass `upsert: true` to overwrite existing objects.

cacheControl可选string

Cache control.

contentType可选string

File MIME type.

metadata可选object

Custom metadata.

upsert可选boolean

Whether to overwrite an existing object. Default is `false`.

返回

data.id

string

Object ID.

data.path

string

Object name inside the bucket.

data.fullPath

string

Full path in `bucketId/objectName` format.

error

StorageError | null

Error.

示例

---

update

Update an existing file.

update(path: string, fileBody: FileBody, fileOptions?: UploadOptions): Promise<Result<UploadResult>>

interface UploadOptions {
  cacheControl?: string;
  contentType?: string;
  metadata?: Record<string, any>;
}

参数

path

string

Object name inside the bucket.

fileBody

FileBody

New file content.

fileOptions

UploadOptions

Upload options.

返回

data

UploadResult | null

Update result.

error

StorageError | null

Error.

示例

---

download

Download a file.

download(path: string, options?: DownloadOptions, parameters?: FetchParameters): DownloadBuilder

interface DownloadOptions {
  download?: string | boolean;
  cacheNonce?: string;
}

interface FetchParameters {
  signal?: AbortSignal;
  cache?: RequestCache;
}

参数

path

string

Object name inside the bucket.

options

DownloadOptions

Download options.

parameters

FetchParameters

Request control parameters.

返回

data

Blob | ReadableStream | null

Await returns Blob by default. `.asStream()` returns ReadableStream.

error

StorageError | null

Error.

示例

---

remove

Delete one or more files.

remove(paths: string[]): Promise<Result<FullObject[]>>

interface FullObject {
  name: string;
  bucket_id: string;
  owner_id?: string | null;
  metadata?: Record<string, any>;
}

参数

paths

string[]

Object names inside the bucket.

返回

data

FullObject[] | null

Deleted object information.

error

StorageError | null

Error.

示例

---

move

Move a file to a new path.

move(fromPath: string, toPath: string, options?: DestinationOptions): Promise<Result<{ message: string }>>

interface DestinationOptions {
  destinationBucket?: string;
  upsert?: boolean;
}

参数

fromPath

string

Source object name.

toPath

string

Destination object name.

options

DestinationOptions

Destination bucket options.

返回

data.message

string

Operation result message.

error

StorageError | null

Error.

示例

---

copy

Copy a file to a new path.

copy(fromPath: string, toPath: string, options?: DestinationOptions): Promise<Result<{ path: string }>>

interface DestinationOptions {
  destinationBucket?: string;
  upsert?: boolean;
  copyMetadata?: boolean;
  metadata?: Record<string, any>;
}

参数

fromPath

string

Source object name.

toPath

string

Destination object name.

options

DestinationOptions

Cross-bucket and metadata options.

返回

data.path

string

Destination object full path.

error

StorageError | null

Error.

示例

---

createSignedUrl

Create a temporary access URL.

createSignedUrl(path: string, expiresIn: number, options?: SignedUrlOptions): Promise<Result<SignedUrlResult>>

interface SignedUrlOptions {
  download?: string | boolean;
  cacheNonce?: string;
}

interface SignedUrlResult {
  fullSignedURL: string;
}

参数

path

string

Object name inside the bucket.

expiresIn

number

Expiration in seconds.

options

SignedUrlOptions

Signed URL options.

返回

data.fullSignedURL

string

Complete signed URL.

error

StorageError | null

Error.

示例

---

createSignedUrls

Create temporary access URLs in batch.

createSignedUrls(paths: string[], expiresIn: number, options?: SignedUrlOptions): Promise<Result<SignedUrlsResultItem[]>>

interface SignedUrlsResultItem {
  path: string;
  fullSignedURL: string | null;
  error: string | null;
}

参数

paths

string[]

Object names inside the bucket.

expiresIn

number

Expiration in seconds.

options

SignedUrlOptions

Signed URL options.

返回

data

SignedUrlsResultItem[] | null

Batch signing results.

error

StorageError | null

Error.

示例

---

getPublicUrl

Get a public access URL.

getPublicUrl(path: string, options?: PublicUrlOptions): { data: { publicUrl: string } }

interface PublicUrlOptions {
  download?: string | boolean;
  cacheNonce?: string;
}

参数

path

string

Object name inside the bucket.

options

PublicUrlOptions

Public URL options.

返回

data.publicUrl

string

Public access URL.

示例

---

info

Get file information.

info(path: string): Promise<Result<ObjectInfo>>

interface ObjectInfo {
  id: string;
  name: string;
  bucketId: string;
  size?: number | null;
  contentType?: string | null;
  metadata?: Record<string, any>;
  createdAt?: string | null;
}

参数

path

string

Object name inside the bucket.

返回

data

ObjectInfo | null

Object metadata.

error

StorageError | null

Error.

示例

---

exists

Check whether a file exists.

exists(path: string): Promise<Result<boolean>>

参数

path

string

Object name inside the bucket.

返回

data

boolean | null

Whether it exists.

error

StorageError | null

Error.

示例

---

createSignedUploadUrl

Create a signed upload URL.

createSignedUploadUrl(path: string, options?: { upsert?: boolean }): Promise<Result<CreateSignedUploadUrlResult>>

interface CreateSignedUploadUrlResult {
  fullSignedURL: string;
  token: string;
  path: string;
}

参数

path

string

Object name inside the bucket.

options

{ upsert?: boolean }

Whether to allow overwrite.

返回

data

CreateSignedUploadUrlResult | null

Signed upload URL and token.

error

StorageError | null

Error.

示例

---

list

List objects in a bucket.

list(path?: string, options?: ListOptions, parameters?: FetchParameters): Promise<Result<ListObjectsResponse>>

interface ListOptions {
  limit?: number;
  cursor?: string;
  withDelimiter?: boolean;
  sortBy?: { column?: "name" | "created_at" | "updated_at"; order?: "asc" | "desc" };
}

参数

path

string

Prefix. Omit it to list the bucket root.

options

ListOptions

List options.

返回

data

ListObjectsResponse | null

Contains folders, objects, hasNext, and nextCursor.

error

StorageError | null

Error.

示例

---

Bucket management

The following APIs are mounted directly on app.storage and are only available in PG mode:

listBuckets(options?: ListBucketOptions): Promise<Result<Bucket[]>>
getBucket(bucketId: string): Promise<Result<Bucket>>
createBucket(bucketId: string, options?: CreateBucketOptions): Promise<Result<{ name: string }>>
updateBucket(bucketId: string, options: UpdateBucketOptions): Promise<Result<{ message: string }>>
deleteBucket(bucketId: string): Promise<Result<{ message: string }>>

interface CreateBucketOptions {
  public?: boolean;
  type?: "STANDARD";
  fileSizeLimit?: number | string | null;
  allowedMimeTypes?: string[] | null;
}

参数

bucketId

string

Bucket ID.

options

Object

Bucket configuration.

返回

data

Bucket | Bucket[] | Object | null

Bucket operation result.

示例

---

---

Best Practices

1. Error handling

const { data, error } = await app.storage.from("avatars").upload("user-123/avatar.png", file);

if (error) {
  console.error("Operation failed:", error.message);
  return;
}

2. Path rules

• Select a bucket with from(bucketId) first. All subsequent paths are object names inside that bucket.
• Do not pass cloud:// fileIDs.
• Do not start paths with / or include consecutive /.

FAQ

1. Why should I not pass cloud:// fileIDs in PG mode?

The native PG API already selects the bucket through from(bucketId). Method path arguments are object names inside that bucket.

2. Where are file permissions configured?

PG mode is controlled by RLS policies on storage.objects / storage.buckets.

Related Resources

• PG Cloud Storage
• PG Cloud Storage SDK Guide
• PG Cloud Storage Permission Management
• PG Cloud Storage HTTP API