server.StorageActionWriter

An interface to read and write files to storage within Convex actions and HTTP actions.

In actions, ctx.storage has additional methods not available in mutations: get() to download a file as a Blob, and store() to upload a Blob directly.

Example

// In an action, download and re-upload a file:
const blob = await ctx.storage.get(storageId);
if (blob) {
  const newStorageId = await ctx.storage.store(blob);
}

• StorageWriter

  ↳ StorageActionWriter

getUrl​

▸ getUrl(storageId): Promise<null | string>

Get the URL for a file in storage by its Id<"_storage">.

The GET response includes a standard HTTP Digest header with a sha256 checksum.

Example

const url = await ctx.storage.getUrl(storageId);

Parameters​

Returns​

Promise<null | string>

• A URL which fetches the file via an HTTP GET, or null if the file no longer exists.

Inherited from​

StorageWriter.getUrl

Defined in​

server/storage.ts:72

▸ getUrl<T>(storageId): Promise<null | string>

Deprecated

Passing a string is deprecated, use storage.getUrl(Id<"_storage">) instead.

Get the URL for a file in storage by its StorageId.

The GET response includes a standard HTTP Digest header with a sha256 checksum.

Type parameters​

Parameters​

Returns​

Promise<null | string>

• A url which fetches the file via an HTTP GET, or null if it no longer exists.

Inherited from​

StorageWriter.getUrl

Defined in​

server/storage.ts:84

getMetadata​

▸ getMetadata(storageId): Promise<null | FileMetadata>

Deprecated

Use ctx.db.system.get("_storage", storageId) instead, which returns equivalent metadata from the _storage system table (with a slightly different shape):

const metadata = await ctx.db.system.get("_storage", storageId);
// { _id, _creationTime, sha256, size, contentType? }

Get metadata for a file.

Parameters​

Returns​

Promise<null | FileMetadata>

• A FileMetadata object if found or null if not found.

Inherited from​

StorageWriter.getMetadata

Defined in​

server/storage.ts:101

▸ getMetadata<T>(storageId): Promise<null | FileMetadata>

Deprecated

Use ctx.db.system.get("_storage", storageId) instead.

Get metadata for a file.

Type parameters​

Parameters​

Returns​

Promise<null | FileMetadata>

• A FileMetadata object if found or null if not found.

Inherited from​

StorageWriter.getMetadata

Defined in​

server/storage.ts:111

generateUploadUrl​

▸ generateUploadUrl(): Promise<string>

Generate a short-lived URL for uploading a file into storage.

The client should make a POST request to this URL with the file as the body. The response will be a JSON object containing a newly allocated Id<"_storage"> ({ storageId: "..." }).

Example

// In a mutation, generate the upload URL:
export const generateUploadUrl = mutation({
  args: {},
  returns: v.string(),
  handler: async (ctx) => {
    return await ctx.storage.generateUploadUrl();
  },
});

// On the client, upload the file:
// const uploadUrl = await generateUploadUrl();
// const result = await fetch(uploadUrl, { method: "POST", body: file });
// const { storageId } = await result.json();

Returns​

Promise<string>

• A short-lived URL for uploading a file via HTTP POST.

Inherited from​

StorageWriter.generateUploadUrl

Defined in​

server/storage.ts:151

delete​

▸ delete(storageId): Promise<void>

Delete a file from Convex storage.

Once a file is deleted, any URLs previously generated by getUrl will return 404s.

Example

await ctx.storage.delete(storageId);

Parameters​

Returns​

Promise<void>

Inherited from​

StorageWriter.delete

Defined in​

server/storage.ts:164

▸ delete<T>(storageId): Promise<void>

Deprecated

Passing a string is deprecated, use storage.delete(Id<"_storage">) instead.

Delete a file from Convex storage.

Once a file is deleted, any URLs previously generated by getUrl will return 404s.

Type parameters​

Parameters​

Returns​

Promise<void>

Inherited from​

StorageWriter.delete

Defined in​

server/storage.ts:175

get​

▸ get(storageId): Promise<null | Blob>

Download a file from storage as a Blob.

Only available in actions and HTTP actions (not in mutations or queries).

Parameters​

Returns​

Promise<null | Blob>

A Blob containing the file contents, or null if the file doesn't exist.

Defined in​

server/storage.ts:206

▸ get<T>(storageId): Promise<null | Blob>

Deprecated

Passing a string is deprecated, use storage.get(Id<"_storage">) instead.

Get a Blob containing the file associated with the provided StorageId, or null if there is no file.

Type parameters​

Parameters​

Returns​

Promise<null | Blob>

Defined in​

server/storage.ts:213

store​

▸ store(blob, options?): Promise<GenericId<"_storage">>

Upload a Blob directly to storage.

Only available in actions and HTTP actions. For client-side uploads from mutations, use generateUploadUrl() instead.

Example

const storageId = await ctx.storage.store(blob);
// Save storageId to the database via ctx.runMutation

Parameters​

Returns​

Promise<GenericId<"_storage">>

The Id<"_storage"> of the newly stored file.

Defined in​

server/storage.ts:232