Buckets

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

Access levels

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

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.

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