Interface: StorageWriter

server.StorageWriter

An interface to write files to storage within Convex mutation functions.

Available as ctx.storage in mutations.

See

https://docs.convex.dev/file-storage

Hierarchy

• StorageReader

  ↳ StorageWriter

  ↳↳ StorageActionWriter

Methods

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

Name	Type	Description
storageId	GenericId<"_storage">	The Id<"_storage"> of the file to fetch from Convex storage.

Returns

Promise<null | string>

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

Inherited from

StorageReader.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

Name	Type
T	extends string

Parameters

Name	Type	Description
storageId	T extends { __tableName: any } ? never : T	The StorageId of the file to fetch from Convex storage.

Returns

Promise<null | string>

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

Inherited from

StorageReader.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

Name	Type	Description
storageId	GenericId<"_storage">	The Id<"_storage"> of the file.

Returns

Promise<null | FileMetadata>

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

Inherited from

StorageReader.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

Name	Type
T	extends string

Parameters

Name	Type	Description
storageId	T extends { __tableName: any } ? never : T	The StorageId of the file.

Returns

Promise<null | FileMetadata>

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

Inherited from

StorageReader.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.

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

Name	Type	Description
storageId	GenericId<"_storage">	The Id<"_storage"> of the file to delete from Convex storage.

Returns

Promise<void>

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

Name	Type
T	extends string

Parameters

Name	Type	Description
storageId	T extends { __tableName: any } ? never : T	The StorageId of the file to delete from Convex storage.

Returns

Promise<void>

Defined in

server/storage.ts:175