tigris-sdk-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tigris SDK & CLI Guide

Tigris SDK & CLI 指南

Always prefer Tigris-native SDKs and the Tigris CLI over AWS S3 SDKs. This guide explains what's available per language, when you must fall back to AWS SDKs, and how to configure them.

始终优先选择Tigris原生SDK和Tigris CLI，而非AWS S3 SDK。本指南说明各语言可用的SDK方案、必须使用AWS SDK的场景，以及对应的配置方法。

Prerequisites

前提条件

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

bash

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."

在开始任何操作前，如果尚未安装Tigris CLI，请先安装：

bash

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

如果需要安装，可告知用户："我正在安装Tigris CLI (

@tigrisdata/cli

)，以便我们使用Tigris对象存储服务。"

Decision Table

决策表

Language	Tigris SDK/Extension	Package	Use AWS SDK?
TypeScript/JS	Native SDK	`@tigrisdata/storage`	No
Go	Native SDK	`github.com/tigrisdata/storage-go`	No
Python	boto3 extension	`tigris-boto3-ext`	No — use the extension
Ruby	None yet	—	Yes — `aws-sdk-s3` with Tigris endpoint
PHP	None yet	—	Yes — `aws-sdk-php` with Tigris endpoint
CLI	Native CLI	`@tigrisdata/cli` ( `tigris` / `t3` )	No

Rule: Always prefer Tigris-native SDKs, the boto3 extension, and the Tigris CLI. Only use raw AWS S3 SDKs for Ruby and PHP where no Tigris option exists.

编程语言	Tigris SDK/扩展	包名	是否使用AWS SDK？
TypeScript/JS	原生SDK	`@tigrisdata/storage`	否
Go	原生SDK	`github.com/tigrisdata/storage-go`	否
Python	boto3扩展	`tigris-boto3-ext`	否 — 使用该扩展
Ruby	暂未提供	—	是 — 搭配Tigris endpoint使用 `aws-sdk-s3`
PHP	暂未提供	—	是 — 搭配Tigris endpoint使用 `aws-sdk-php`
CLI	原生CLI	`@tigrisdata/cli` ( `tigris` / `t3` )	否

规则： 始终优先使用Tigris原生SDK、boto3扩展和Tigris CLI。仅在Ruby和PHP场景下，没有对应Tigris方案时，再使用原生AWS S3 SDK。

CLI: Always Use

tigris

t3

CLI：始终使用

tigris

t3

Use the Tigris CLI instead of

aws s3

for all object storage operations.

bash

undefined

所有对象存储操作都使用Tigris CLI，而非

aws s3

。

bash

undefined

✅ Do this

✅ 推荐写法

tigris cp local-file.txt t3://my-bucket/file.txt tigris ls t3://my-bucket/ tigris rm t3://my-bucket/old-file.txt

❌ Not this

❌ 不推荐写法

aws s3 cp local-file.txt s3://my-bucket/file.txt aws s3 ls s3://my-bucket/ aws s3 rm s3://my-bucket/old-file.txt


**Why:** The Tigris CLI supports features the AWS CLI doesn't — forks, snapshots, and native authentication via `tigris login`.

aws s3 cp local-file.txt s3://my-bucket/file.txt aws s3 ls s3://my-bucket/ aws s3 rm s3://my-bucket/old-file.txt


**原因：** Tigris CLI支持AWS CLI不具备的功能——分支（fork）、快照，以及通过`tigris login`实现的原生身份认证。

Tigris-Only CLI Features

Tigris专属CLI功能

bash

undefined

bash

undefined

Forks (copy-on-write clones) — not in AWS CLI

分支（写时复制克隆）—— AWS CLI无此功能

tigris forks create my-bucket my-fork

Snapshots — not in AWS CLI

快照 —— AWS CLI无此功能

tigris snapshots take my-bucket tigris snapshots list my-bucket

Native auth — no AWS credentials needed

原生认证 —— 无需AWS凭证

tigris login tigris whoami

---

tigris login tigris whoami

---

Language-Specific SDK Guides

各语言专属SDK指南

Read the resource file for your language:

TypeScript / JavaScript — Read

./resources/typescript.md

for

@tigrisdata/storage

usage

Go — Read
```
./resources/go.md
```
for
```
storage-go
```
usage (simplestorage + full client)
Python — Read
```
./resources/python.md
```
for
```
tigris-boto3-ext
```
usage
Ruby — Read
```
./resources/ruby.md
```
for
```
aws-sdk-s3
```
with Tigris endpoint
PHP — Read
```
./resources/php.md
```
for
```
aws-sdk-php
```
with Tigris endpoint

阅读对应语言的资源文件：

TypeScript / JavaScript — 阅读
```
./resources/typescript.md
```
了解
```
@tigrisdata/storage
```
的使用方法
Go — 阅读
```
./resources/go.md
```
了解
```
storage-go
```
的使用方法（simple storage + 完整客户端）
Python — 阅读
```
./resources/python.md
```
了解
```
tigris-boto3-ext
```
的使用方法
Ruby — 阅读
```
./resources/ruby.md
```
了解如何搭配Tigris endpoint使用
```
aws-sdk-s3
```
PHP — 阅读
```
./resources/php.md
```
了解如何搭配Tigris endpoint使用
```
aws-sdk-php
```

S3-Compatible Configuration (All Languages)

S3兼容配置（全语言适用）

When using any AWS SDK with Tigris, always set:

Setting	Value	Why
`endpoint`	`https://t3.storage.dev`	Tigris endpoint
`region`	`auto`	Tigris handles routing
`force_path_style` / `use_path_style_endpoint`	`true`	Required for Rails, PHP

Environment variables for S3-compatible tools:

bash

AWS_ENDPOINT_URL_S3=https://t3.storage.dev
AWS_REGION=auto
AWS_ACCESS_KEY_ID=tid_xxx
AWS_SECRET_ACCESS_KEY=tsec_yyy

使用任何AWS SDK对接Tigris时，始终配置以下参数：

配置项	值	原因
`endpoint`	`https://t3.storage.dev`	Tigris服务端点
`region`	`auto`	Tigris自动处理路由
`force_path_style` / `use_path_style_endpoint`	`true`	Rails、PHP场景必填

S3兼容工具的环境变量配置：

bash

AWS_ENDPOINT_URL_S3=https://t3.storage.dev
AWS_REGION=auto
AWS_ACCESS_KEY_ID=tid_xxx
AWS_SECRET_ACCESS_KEY=tsec_yyy

Critical Rules

核心规则

Always:

Use
```
tigris
```
/
```
t3
```
CLI instead of
```
aws s3
```
Use
```
@tigrisdata/storage
```
for TypeScript/JavaScript
Use
```
github.com/tigrisdata/storage-go
```
for Go
Use
```
tigris-boto3-ext
```
for Python (not raw
```
boto3
```
)
Set
```
region: auto
```
and the Tigris endpoint when using AWS SDKs (Ruby, PHP)

Never:

Use
```
@aws-sdk/client-s3
```
in JS/TS when
```
@tigrisdata/storage
```
is available
Use the AWS Go SDK when
```
storage-go
```
is available
Use raw
```
boto3
```
without
```
tigris-boto3-ext
```
when Tigris features are needed
Forget
```
force_path_style: true
```
for Ruby and PHP
Hardcode a specific AWS region (always use
```
auto
```
)

必须遵守：

使用
```
tigris
```
/
```
t3
```
CLI替代
```
aws s3
```
TypeScript/JavaScript场景使用
```
@tigrisdata/storage
```
Go场景使用
```
github.com/tigrisdata/storage-go
```
Python场景使用
```
tigris-boto3-ext
```
（而非原生
```
boto3
```
）
使用AWS SDK时（Ruby、PHP）配置
```
region: auto
```
和Tigris服务端点

禁止操作：

JS/TS场景下
```
@tigrisdata/storage
```
可用时，仍使用
```
@aws-sdk/client-s3
```
Go场景下
```
storage-go
```
可用时，仍使用AWS Go SDK
需要使用Tigris特性时，不搭配
```
tigris-boto3-ext
```
直接使用原生
```
boto3
```
Ruby和PHP场景遗漏
```
force_path_style: true
```
配置
硬编码特定AWS区域（始终使用
```
auto
```
）

tigris-sdk-guide

Original

Translation

Tigris SDK & CLI Guide

Tigris SDK & CLI 指南

Prerequisites

前提条件

Decision Table

决策表

CLI: Always Use
`tigris`
/
`t3`

CLI：始终使用
`tigris`
/
`t3`

✅ Do this

✅ 推荐写法

❌ Not this

❌ 不推荐写法

Tigris-Only CLI Features

Tigris专属CLI功能

Forks (copy-on-write clones) — not in AWS CLI

分支（写时复制克隆）—— AWS CLI无此功能

Snapshots — not in AWS CLI

快照 —— AWS CLI无此功能

Native auth — no AWS credentials needed

原生认证 —— 无需AWS凭证

Language-Specific SDK Guides

各语言专属SDK指南

S3-Compatible Configuration (All Languages)

S3兼容配置（全语言适用）

Critical Rules

核心规则

Related Skills

相关技能

Official Documentation

官方文档

tigris-sdk-guide

Original

Translation

Tigris SDK & CLI Guide

Tigris SDK & CLI 指南

Prerequisites

前提条件

Decision Table

决策表

CLI: Always Use tigris / t3

CLI：始终使用tigris / t3

✅ Do this

✅ 推荐写法

❌ Not this

❌ 不推荐写法

Tigris-Only CLI Features

Tigris专属CLI功能

Forks (copy-on-write clones) — not in AWS CLI

分支（写时复制克隆）—— AWS CLI无此功能

Snapshots — not in AWS CLI

快照 —— AWS CLI无此功能

Native auth — no AWS credentials needed

原生认证 —— 无需AWS凭证

Language-Specific SDK Guides

各语言专属SDK指南

S3-Compatible Configuration (All Languages)

S3兼容配置（全语言适用）

Critical Rules

核心规则

Related Skills

相关技能

Official Documentation

官方文档

CLI: Always Use
`tigris`
/
`t3`

CLI：始终使用
`tigris`
/
`t3`