tigris-bucket-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tigris Bucket Management

Tigris存储桶管理

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

操作	函数	关键参数
创建	`createBucket(name, options)`	name, access, region, enableSnapshot
列出	`listBuckets(options)`	limit, paginationToken
查看	`getBucketInfo(name)`	bucketName
删除	`removeBucket(name, options)`	bucketName, force

Create Bucket

创建存储桶

typescript

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",
});

typescript

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

// 简单私有存储桶
const result = await createBucket("my-new-bucket");
if (result.error) {
  console.error("Error:", result.error);
} else {
  console.log("Created:", result.data);
}

// 公共存储桶（任何人都可读取对象）
const result = await createBucket("public-assets", {
  access: "public",
});

// 启用快照的存储桶（用于版本控制）
const result = await createBucket("my-snapshot-bucket", {
  enableSnapshot: true,
});

// 区域存储桶
const result = await createBucket("eu-data", {
  region: "eu",
});

// 从现有存储桶快照分叉
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/STANDARD_IA/GLACIER/GLACIER_IR	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.

选项	取值	默认值	用途
access	public/private	private	对象可读性
consistency	default/strict	default	读取一致性级别
defaultTier	STANDARD/STANDARD_IA/GLACIER/GLACIER_IR	STANDARD	默认存储层级
enableSnapshot	boolean	false	启用快照/分叉功能
region	string	global	存储桶区域
sourceBucketName	string	-	从此存储桶分叉
sourceBucketSnapshot	string	-	从此快照分叉

注意： 启用快照的存储桶必须使用STANDARD层级。

List Buckets

列出存储桶

typescript

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);
}

typescript

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

// 列出所有存储桶
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);
}

// 分页列出
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

获取存储桶信息

typescript

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
  // }
}

typescript

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

删除存储桶

typescript

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.

typescript

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

// 删除空存储桶
const result = await removeBucket("my-bucket");
if (result.error) {
  console.error("Error:", result.error);
} else {
  console.log("Deleted successfully");
}

// 强制删除（即使存储桶非空）
const result = await removeBucket("my-bucket", {
  force: true,
});

警告： 强制删除操作不可撤销，所有对象将被永久删除。

Bucket Access Levels

存储桶访问级别

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

级别	行为	使用场景
private	对象需要身份验证才能访问	默认选项，适用于敏感数据
public	对象可公开读取	静态资源、公开内容

Consistency Levels

一致性级别

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

级别	行为	权衡
default	低延迟，最终一致性	大多数工作负载
strict	强一致性，延迟较高	关键数据场景

Storage Tiers

存储层级

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

层级	使用场景	成本
STANDARD	通用场景	标准成本
STANDARD_IA	不常访问的数据	成本较低
GLACIER	长期存档	成本最低
GLACIER_IR	极少访问但需要快速检索的存档	适用于偶尔访问的存档数据

Regions

区域

Specify region for data locality or compliance:

typescript

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

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

为了数据本地化或合规要求，可指定存储区域：

typescript

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

留空则创建全局存储桶（推荐大多数场景使用）。

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

错误	修复方案
为非STANDARD层级的存储桶启用快照	快照功能仅支持STANDARD层级
删除前未检查存储桶是否存在	先调用 `getBucketInfo` 进行检查
尝试删除非空存储桶但未使用强制参数	使用 `force: true` 或先清空存储桶
存储桶名称冲突	存储桶名称必须全局唯一

Forking and Snapshots

快照与分叉

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

如需了解版本控制（快照/分叉）相关内容，请查看tigris-snapshots-forking技能。

Prerequisites

前置条件

Before managing buckets, ensure @tigrisdata/storage is installed. See installing-tigris-storage.

在管理存储桶之前，请确保已安装@tigrisdata/storage。详情请查看installing-tigris-storage。