ALTER BUCKET

Available since: v3.0.5

The ALTER BUCKET statement can be used to modify an existing defined bucket.

Statement syntax

ALTER BUCKET [ IF EXISTS ] @name
  [ ON [ ROOT | NAMESPACE | DATABASE ] ]
  [ READONLY | DROP READONLY ]
  [ BACKEND @string ]
  [ PERMISSIONS @expression ]
  [ COMMENT @string | DROP COMMENT ]
  [ REVOKE SIGNATURES ]

Example usage

DEFINE BUCKET my_bucket BACKEND "memory";

ALTER BUCKET my_bucket COMMENT "Should we make this read-only too??";

Changing the backend

Available since: v4.0.0

BACKEND moves the bucket to another backend. The files in the old backend stay where they are, and the bucket serves the files of the new one. A global:// backend needs a root user, as on DEFINE BUCKET. From SurrealDB 4.0, a bucket always has a backend, so DROP BACKEND no longer parses.

Changing BACKEND or READONLY makes SurrealDB open a new connection to the backend once the statement commits. For a memory backend, a new connection starts empty, so a memory bucket loses its files when either clause changes.

Root and namespace buckets

Available since: v4.0.0

Without ON, ALTER BUCKET changes a bucket of the database in use. To change a root or namespace bucket, name its level:

ALTER BUCKET shared ON NAMESPACE COMMENT "Files for every database in this namespace";

Revoking presigned URLs

Available since: v4.0.0

REVOKE SIGNATURES stops every presigned URL already issued for the bucket from working. A request with one of those URLs then answers 403. URLs created after the statement work as usual.

ALTER BUCKET my_bucket REVOKE SIGNATURES;

Each bucket holds a random value that is part of the key that signs its URLs, and REVOKE SIGNATURES replaces it. DEFINE BUCKET ... OVERWRITE keeps the value, so redefining a bucket does not make revoked URLs work again. Removing a bucket and defining it again gives it a new value, which also revokes its URLs. To revoke the URLs of every bucket on a server at once, change SURREAL_BUCKET_PRESIGN_SECRET.