Autoscaling Report: Production databases on Neon use 2.4x less compute and 50% less cost than if they were running on a provisioned platform.

Buckets

Create and manage storage buckets

Private Preview

This feature is in private preview: it's not ready for production use, and it may be briefly unavailable as we deploy updates. To get access, sign up here.

A bucket is a named container for objects in Neon Storage. Buckets are scoped to a branch and inherit from parent branches when a new branch is created. No data is copied on fork.

Create a bucket

You can create a bucket from the Neon Console, the Neon CLI, the Neon API, or directly via the S3 API.

Neon Console

In the Neon Console, navigate to your project, select a branch, and open the Storage tab. Click New bucket, enter a name, choose an access level, and click Create.

neon buckets create my-bucket

To create a public_read bucket with neon:

neon buckets create my-public-bucket --access-level public_read

note

AWS_ENDPOINT_URL_S3 is your branch's storage endpoint. See Get started for how to obtain it.

Access levels

Every bucket has an access level that controls who can read objects in it.

Access levelReadsWrites
privateRequire a valid credentialRequire a valid credential
public_readOpen to anyone (no credential needed)Require a valid credential

The default is private. Set the access level when creating a bucket via the Neon API, or change it from the Storage tab in the Console.

note

Access level is set through the Neon Console or API, not through the S3 API. S3 ACL and bucket policy mutation requests (PutBucketAcl, PutBucketPolicy) return 501 Not Implemented. If you need to change access level on an existing bucket, use the Console or Neon API.

public_read example

Objects in a public_read bucket are accessible at:

https://<branch-id>.storage.c-<N>.us-east-2.aws.neon.tech/my-public-bucket/<object-key>

List buckets

neon buckets list

Delete a bucket

Buckets must be empty before deletion. Delete all objects first, then delete the bucket.

neon buckets delete my-bucket

Bucket branching

When you create a new branch, it inherits all buckets from its parent at the point of forking. No data is copied. From that point on:

  • Creating or deleting a bucket on a child branch does not affect the parent.
  • Objects uploaded to a child branch are only visible on that branch and its descendants.
  • The parent branch continues to see its own state unchanged.

This makes it safe to test bucket changes in a preview branch without affecting production.

Next steps

  • Objects: upload, download, list, and delete objects
  • Authentication: credential scopes and branch binding

Need help?

Join our Discord Server to ask questions or see what others are doing with Neon. For paid plan support options, see Support.

Was this page helpful?
Edit on GitHub