supabase.storage — io.github.supabase-community/storage 0.6.0

Object storage against Supabase Storage.

Provides bucket CRUD plus per-bucket file operations (list, remove, move, copy, info, exists?, public/signed URLs, upload, download), bucket lifecycle policies (get-bucket-lifecycle / update-bucket-lifecycle / delete-bucket-lifecycle), and object versioning (:versioning-status on bucket create/update, :version-id on download/URL/info ops, version-targeted remove/move/copy, version listing options on list-files/list-files-v2). Per-bucket ops take a storage instance returned by from. Analytics bucket operations live in supabase.storage.analytics. Vector bucket, index, and vector data operations live in supabase.storage.vector.

Example

(require '[supabase.core.client :as client]
         '[supabase.storage :as storage])

(def c (client/make-client "https://abc.supabase.co" "anon-key"))

(storage/list-buckets c)
(storage/create-bucket c "avatars" {:public true})

(def s (storage/from c "avatars"))
(storage/upload s "profile.png" my-bytes
                {:content-type "image/png" :upsert true})
(storage/download s "profile.png")
(storage/get-public-url s "profile.png")

Each function returns {:status :body :headers} on success or an anomaly map on failure. See https://supabase.com/docs/reference/javascript/storage-api

copy clj

(copy s opts)

Copies an object within or across buckets. Options match move.

create-bucket clj

(create-bucket client id)

(create-bucket client id attrs)

Creates a new bucket with id and the given attrs.

Attributes (all optional)

• :public — boolean visibility flag (default false)
• :file-size-limit — max file size in bytes
• :allowed-mime-types — vector of allowed MIME types or wildcards
• :type — "STANDARD" (default) or "ANALYTICS"
• :versioning-status — initial object versioning status, "DISABLED" (default) or "ENABLED"

create-signed-upload-url clj

(create-signed-upload-url s path)

(create-signed-upload-url s path opts)

Creates a signed URL that lets a client upload to path without further authentication. Valid for two hours.

Options

• :upsert — allow overwriting an existing object (default false)

On success returns {:status :body :headers} where :body is {:signed-url <url> :token <token> :path <clean-path>}. The token can be fed to upload-to-signed-url.

create-signed-url clj

(create-signed-url s path opts)

Creates a time-limited signed download URL for path.

Options

• :expires-in — TTL in seconds (required)
• :download — see get-public-url
• :transform — image transform map applied to the signed asset
• :version-id — sign a specific object version instead of the current one (requires bucket versioning)

create-signed-urls clj

(create-signed-urls s paths opts)

Creates signed URLs for multiple paths.

Options

• :expires-in — TTL in seconds (required)
• :download — applied to every returned URL

delete-bucket clj

(delete-bucket client id)

Deletes the bucket and every object inside it.

delete-bucket-lifecycle clj

(delete-bucket-lifecycle client id)

Removes the lifecycle policy from bucket id. Safe to call when no policy is stored; the response is still success.

download clj

(download s path)

(download s path opts)

Downloads the object at path from a private bucket.

Returns {:status :body :headers}. By default :body is a byte array; pass :response-as :stream to receive a java.io.InputStream (the caller is responsible for closing it).

Options

• :response-as — :byte-array (default) or :stream
• :range — [start end] inclusive byte range for a partial download
• :transform — image transform map (renders via render/image)
• :cache-nonce — value for the cacheNonce query param (cache busting)
• :version-id — download a specific object version instead of the current one (requires bucket versioning)
• :headers — extra request headers

empty-bucket clj

(empty-bucket client id)

Removes every object from the bucket without deleting it.

exists? clj

(exists? s path)

Returns true if the object exists, false otherwise. Errors other than not-found are still surfaced as false — call info if you need detail.

from clj

(from client bucket-id)

Returns a storage instance bound to bucket-id. Pass it as the first argument to file operations.

(def s (from client "avatars"))
(list-files s)

get-bucket clj

(get-bucket client id)

Retrieves a bucket by its id.

get-bucket-lifecycle clj

(get-bucket-lifecycle client id)

Returns the lifecycle policy stored on bucket id.

Fails with NoSuchLifecycleConfiguration when the bucket has no policy. The rules expire previous versions of objects, not the current one — enable versioning or there is nothing for the policy to act on. Standard buckets only; the server returns FeatureNotEnabled when lifecycle is off for the project.

(get-bucket-lifecycle client "avatars")
;; => {:rules [{:id "expire-history" :status "Enabled" :filter {}
;;              :noncurrentVersionExpiration {:noncurrentDays 30}}]}

get-public-url clj

(get-public-url s path)

(get-public-url s path opts)

Builds the public download URL for an object. Does not call the API.

Options

• :download — true triggers browser download with the object's name; a string sets a custom download filename.
• :transform — image transform map; routes through the image render endpoint and appends the transform query.
• :version-id — URL for a specific object version instead of the current one (requires bucket versioning).

info clj

(info s path)

(info s path opts)

Retrieves metadata for the object at path.

Options

• :version-id — metadata for a specific object version instead of the current one (requires bucket versioning)

list-buckets clj

(list-buckets client)

(list-buckets client opts)

Lists all buckets in the project.

Options

• :limit — max buckets returned
• :offset — number of buckets to skip
• :sort-by — {:column "name" :order "asc"}; column is one of "id", "name", "created_at", "updated_at" (kebab-case keywords accepted)
• :search — substring filter on bucket names

list-files clj

(list-files s)

(list-files s prefix)

(list-files s prefix opts)

Lists files in the bucket, optionally filtered by prefix.

Options

• :limit — max results (default server-side: 100)
• :offset — pagination offset
• :sort-by — {:column "name" :order "asc"}
• :search — substring filter
• :noncurrent-versions — :exclude (default), :include or :only; controls whether noncurrent object versions appear in the results (requires bucket versioning)
• :delete-markers — :exclude (default), :include or :only
• :exact-match — only objects whose key exactly matches prefix

list-files-v2 clj

(list-files-v2 s)

(list-files-v2 s prefix)

(list-files-v2 s prefix opts)

Lists files using cursor-based pagination (the list-v2 endpoint).

Cursor pagination is O(1) regardless of position, unlike the offset-based list-files.

Options

• :limit — page size (default server-side 100)
• :cursor — pagination cursor from a previous response
• :with-delimiter — group results by folder hierarchy when true
• :noncurrent-versions — :exclude (default), :include or :only; controls whether noncurrent object versions appear in the results (requires bucket versioning)
• :delete-markers — :exclude (default), :include or :only
• :exact-match — only objects whose key exactly matches prefix

move clj

(move s opts)

Moves an object within or across buckets.

Options

• :from — source path (required)
• :to — destination path (required)
• :destination-bucket — target bucket id (optional, same bucket if omitted)
• :source-version-id — move a specific version of the source object instead of the current one (requires bucket versioning)

purge-bucket-cache clj

(purge-bucket-cache client id)

(purge-bucket-cache client id opts)

Purges the CDN cache for an entire bucket (DELETE /cdn/{bucket}). The server issues a CDN invalidation and returns {:message "success"}.

Requires the service-role key — the endpoint rejects anon and user JWTs. On self-hosted Storage the purgeCache tenant feature must be enabled.

Options

• :transformations — when true, purges only transformed variants (resized/formatted), leaving original cached files intact

purge-cache clj

(purge-cache s path)

(purge-cache s path opts)

Purges the CDN cache for a single object (DELETE /cdn/{bucket}/{path}). No wildcard or recursion: path must be the exact object key. Requires the service-role key (see purge-bucket-cache).

Options

• :transformations — when true, purges only transformed variants (resized/formatted), leaving the original cached file intact

remove clj

(remove s paths)

Deletes one or more objects from the bucket.

paths may be a single path string or a vector. Each entry is either a plain path or a {:path ... :version-id ...} map targeting an exact object version (requires bucket versioning).

storage-error-parser clj

(storage-error-parser status body _headers _service)

Maps a Storage error response to an anomaly, preferring the API's message field for the human-readable text. Wired via http/with-error-parser.

update clj

(update s path body)

(update s path body opts)

Replaces the object at path with body via PUT. Unlike upload, this targets an existing object. Same options as upload.

update-bucket clj

(update-bucket client id attrs)

Updates the bucket identified by id with attrs.

Same attributes as create-bucket (without :id). Note :versioning-status here accepts "ENABLED" or "SUSPENDED" only — there is no transition back to "DISABLED" once versioning has been touched.

update-bucket-lifecycle clj

(update-bucket-lifecycle client id configuration)

Replaces the lifecycle policy on bucket id. The :rules vector sent is the whole policy: anything previously stored is overwritten. Call delete-bucket-lifecycle to remove the policy.

Each rule supports only :noncurrent-version-expiration today; :filter is required and must be {}. :id is optional — the server generates one when omitted. Rule ids must be unique when set.

(update-bucket-lifecycle client "avatars"
  {:rules [{:id "expire-history"
            :status :enabled
            :filter {}
            :noncurrent-version-expiration {:noncurrent-days 30
                                            :newer-noncurrent-versions 2}}]})

upload clj

(upload s path body)

(upload s path body opts)

Uploads body (bytes / InputStream / File / string) to path in the bucket via POST. Fails if the object already exists unless :upsert.

Options

• :content-type — defaults to "text/plain;charset=UTF-8"
• :cache-control — number of seconds (default "3600")
• :upsert — overwrite if the object exists (default false)
• :metadata — map of string→string stored as object metadata
• :headers — extra HTTP headers

upload-to-signed-url clj

(upload-to-signed-url s path token body)

(upload-to-signed-url s path token body opts)

Uploads body to a previously created signed upload URL using its token (see create-signed-upload-url). Same options as upload.

with-storage-errors clj

(with-storage-errors req)

Installs the Storage error parser on a request.