OpenParable
Skip to content
← Back to skills

Serverpod File Uploads

Development
serverpod-file-uploads

Serverpod File Uploads is an Agent Skill for development published in the serverpod/serverpod repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

File uploads in Serverpod — upload descriptions, verification, storage backends (database, S3, GCP). Use when implementing file uploads or cloud storage.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/serverpod/serverpod/blob/HEAD/packages/serverpod/skills/serverpod-file-uploads/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/serverpod-file-uploads, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Serverpod File Uploads

Flow: server issues upload description → client uploads → server verifies. Default storage is the database; use S3, GCP, R2, or compatible object storage for production.

Server: create upload description

Future<String?> getUploadDescription(Session session, String path) async {
  return await session.storage.createDirectFileUploadDescription(
    storageId: 'public',
    path: path,
  );
}

Always authorize the request and derive the path from trusted server-side state (user id, tenant id, object id). Do not accept arbitrary client paths.

Server: verify upload

Future<bool> verifyUpload(Session session, String path) async {
  return await session.storage.verifyDirectFileUpload(
    storageId: 'public', path: path);
}

Always verify after client upload when using object storage.

Client: upload

var desc = await client.myEndpoint.getUploadDescription('profile/$userId/avatar.png');
if (desc != null) {
  var uploader = FileUploader(desc);
  await uploader.upload(byteDataOrStream);
  await client.myEndpoint.verifyUpload('profile/$userId/avatar.png');
}

Use Stream for large files. Paths: no leading slash, object-store compatible, normalized, and scoped to the authenticated user/tenant.

Security checklist

  • Require authentication/authorization for both description and verification endpoints.
  • Validate or derive content type, size, and extension before issuing descriptions.
  • Never let clients choose cross-tenant paths or storage IDs.
  • Store metadata in your database after verifyDirectFileUpload succeeds.

Accessing stored files

  • session.storage.fileExists(storageId: 'public', path: path)
  • session.storage.getPublicUrl(storageId: 'public', path: path) (public storage only)
  • session.storage.retrieveFile(storageId: 'public', path: path)

Storage backends

  • Database (default): public and private storages. Fine for dev.
  • Google Cloud Storage: Add serverpod_cloud_storage_gcp, set HMAC keys in passwords.yaml or env. Register: pod.addCloudStorage(GoogleCloudStorage(...)).
  • AWS S3: Add serverpod_cloud_storage_s3, set AWS keys. Register: pod.addCloudStorage(S3CloudStorage(...)).
  • S3-compatible/R2: Use the matching integration package when targeting compatible providers.

Use storageId: 'public' or 'private' when replacing defaults.