Tigris Bucket Management

Tigris Bucket Management

Prerequisites

Before doing anything else, install the Tigris CLI if it's not already available:

tigris help || npm install -g @tigrisdata/cli

If you need to install it, tell the user: "I'm installing the Tigris CLI (@tigrisdata/cli) so we can work with Tigris object storage."

Overview

Buckets are containers for objects. This skill covers bucket lifecycle: create, list, inspect, and delete.

Quick Reference

| Operation | Function | Key Parameters | | --------- | ----------------------------- | ------------------------------------ | | Create | createBucket(name, options) | name, access, region, enableSnapshot | | List | listBuckets(options) | limit, paginationToken | | Inspect | getBucketInfo(name) | bucketName | | Delete | removeBucket(name, options) | bucketName, force |

Create Bucket

import { createBucket } from "@tigrisdata/storage";

// Simple private bucket
const result = await createBucket("my-new-bucket");
if (result.error) {
  console.error("Error:", result.error);
} else {
  console.log("Created:", result.data);
}

// Public bucket (objects readable by anyone)
const result = await createBucket("public-assets", {
  access: "public",
});

// Snapshot-enabled bucket (for version control)
const result = await createBucket("my-snapshot-bucket", {
  enableSnapshot: true,
});

// Regional bucket
const result = await createBucket("eu-data", {
  region: "eu",
});

// Fork from existing bucket snapshot
const result = await createBucket("my-forked-bucket", {
  sourceBucketName: "parent-bucket",
  sourceBucketSnapshot: "1751631910169675092",
});

Create Bucket Options

| Option | Values | Default | Purpose | | -------------------- | --------------------------------------- | -------- | ------------------------ | | access | public/private | private | Object readability | | consistency | default/strict | default | Read consistency level | | defaultTier | STANDARD/STANDARDIA/GLACIER/GLACIERIR | STANDARD | Default storage tier | | enableSnapshot | boolean | false | Enable snapshots/forking | | region | string | global | Bucket region | | sourceBucketName | string | - | Fork from this bucket | | sourceBucketSnapshot | string | - | Fork from this snapshot |

Note: Snapshot-enabled buckets must use STANDARD tier.

List Buckets

import { listBuckets } from "@tigrisdata/storage";

// List all buckets
const result = await listBuckets();
if (result.error) {
  console.error("Error:", result.error);
} else {
  console.log("Buckets:", result.data?.buckets);
  console.log("Owner:", result.data?.owner);
}

// Paginated list
const allBuckets = [];
let currentPage = await listBuckets({ limit: 10 });
allBuckets.push(...currentPage.data?.buckets);

while (currentPage.data?.paginationToken) {
  currentPage = await listBuckets({
    limit: 10,
    paginationToken: currentPage.data?.paginationToken,
  });
  allBuckets.push(...currentPage.data?.buckets);
}

Get Bucket Info

import { getBucketInfo } from "@tigrisdata/storage";

const result = await getBucketInfo("my-bucket");
if (result.error) {
  console.error("Error:", result.error);
} else {
  console.log("Info:", result.data);
  // {
  //   isSnapshotEnabled: true,
  //   hasForks: false,
  //   sourceBucketName: undefined,
  //   sourceBucketSnapshot: undefined
  // }
}

Delete Bucket

import { removeBucket } from "@tigrisdata/storage";

// Delete empty bucket
const result = await removeBucket("my-bucket");
if (result.error) {
  console.error("Error:", result.error);
} else {
  console.log("Deleted successfully");
}

// Force delete (even if not empty)
const result = await removeBucket("my-bucket", {
  force: true,
});

Warning: Force delete is irreversible. All objects will be lost.

Bucket Access Levels

| Level | Behavior | Use Case | | ------- | ------------------------- | ----------------------------- | | private | Objects require auth | Default, sensitive data | | public | Objects publicly readable | Static assets, public content |

Consistency Levels

| Level | Behavior | Trade-off | | ------- | ---------------------------------- | -------------- | | default | Low latency, eventual consistency | Most workloads | | strict | Strong consistency, higher latency | Critical data |

Storage Tiers

| Tier | Use Case | Cost | | ----------- | --------------------------- | ------------------------------ | | STANDARD | General purpose | Standard | | STANDARDIA | Infrequently accessed | Lower cost | | GLACIER | Long-term archive | Lowest cost | | GLACIERIR | Rare access, fast retrieval | Archive with occasional access |

Regions

Specify region for data locality or compliance:

await createBucket("data-eu", { region: "eu" });
await createBucket("data-asia", { region: "asia-south-1" });

Leave empty for global bucket (recommended for most use cases).

Common Mistakes

| Mistake | Fix | | ----------------------------------------------- | -------------------------------------- | | Enable snapshot with non-STANDARD tier | Snapshot requires STANDARD tier | | Not checking bucket exists before delete | Use getBucketInfo first | | Trying to delete non-empty bucket without force | Use force: true or empty bucket first | | Name conflicts | Bucket names must be globally unique |

Forking and Snapshots

For version control (snapshots/forking), see the tigris-snapshots-forking skill.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tigrisdata
• Source: tigrisdata/skills
• License: MIT

Install and usage instructions live in the source repository linked above.