生成 Python 类型

How to generate Python types for your API and Supabase libraries.

Supabase 的 API 是从你的数据库生成的，这意味着我们可以使用数据库自省来生成类型安全的 API 定义。

🌐 Supabase APIs are generated from your database, which means that we can use database introspection to generate type-safe API definitions.

使用 Supabase CLI 生成类型 #

🌐 Generating types using Supabase CLI

Supabase CLI 是一个单一的 Go 二进制应用，它提供了设置本地开发环境所需的一切。

🌐 The Supabase CLI is a single binary Go application that provides everything you need to setup a local development environment.

你可以通过 npm 或其他支持的包管理器安装 CLI。CLI 的最低要求版本是 v2.66.0。

🌐 You can install the CLI via npm or other supported package managers. The minimum required version of the CLI is v2.66.0.

1
npm i supabase --save-dev

使用你的个人访问令牌登录：

🌐 Login with your Personal Access Token:

1
npx supabase login

在生成类型之前，确保你已经初始化了你的 Supabase 项目：

🌐 Before generating types, ensure you initialize your Supabase project:

1
npx supabase init

为你的项目生成类型以生成 database_types.py 文件：

🌐 Generate types for your project to produce the database_types.py file:

1
npx supabase gen types --lang=python --project-id "$PROJECT_REF" --schema public > database.types.py

或者在本地开发时：

🌐 or in case of local development:

1
npx supabase gen types --lang=python --local > database_types.py

这些类型是从你的数据库模式生成的。给定一个表 public.movies，生成的类型看起来会像这样：

🌐 These types are generated from your database schema. Given a table public.movies, the generated types will look like:

1
create table public.movies (
2
  id bigint generated always as identity primary key,
3
  name text not null,
4
  data jsonb null
5
);

1
class PublicMovies(BaseModel):
2
    data: Optional[Json[Any]] = Field(alias="data")
3
    id: int = Field(alias="id")
4
    name: str = Field(alias="name")
5
6
class PublicMoviesInsert(TypedDict):
7
    data: NotRequired[Annotated[Json[Any], Field(alias="data")]]
8
    id: NotRequired[Annotated[int, Field(alias="id")]]
9
    name: Annotated[str, Field(alias="name")]
10
11
class PublicMoviesUpdate(TypedDict):
12
    data: NotRequired[Annotated[Json[Any], Field(alias="data")]]
13
    id: NotRequired[Annotated[int, Field(alias="id")]]
14
    name: NotRequired[Annotated[str, Field(alias="name")]]

用于选择、插入和更新的类型 #

🌐 Types for select, insert and update

PublicMovies 类用于解析 movies 表中的 SELECT 结果，而 PublicMoviesInsert 和 PublicMoviesUpdate 则分别用于格式化和提供 insert 与 update 的参数完成。

🌐 The PublicMovies class is used to parse SELECT results from the movies table, while PublicMoviesInsert and PublicMoviesUpdate are used to format and provide completion for arguments for insert and update respectively.

1
from .database_types import PublicMovies, PublicMoviesInsert, PublicMoviesUpdate
2
from supabase import create_client
3
4
client = create_client("YOUR_SUPABASE_URL", "YOUR_SUPABASE_KEY")
5
movies = client.table("movies")
6
7
# Select
8
selected = [PublicMovies(m) for m in movies.select("*").execute().data]
9
10
# Insert
11
inserted = [PublicMovies(m) for m in movies.insert(PublicMoviesInsert(name="foo", data="bar")) \
12
                                          .execute().data]
13
14
# Update
15
updated  = [PublicMovies(m) for m in movies.update(PublicMoviesUpdate(name="bar")) \
16
                                        .eq("id", 5) \
17
                                        .execute().data]

使用 GitHub Actions 自动更新类型 #

🌐 Update types automatically with GitHub Actions

保持你的类型定义与数据库同步的一种方法是设置一个定期运行的 GitHub 动作。

🌐 One way to keep your type definitions in sync with your database is to set up a GitHub action that runs on a schedule.

将以下脚本添加到你的 package.json 中以使用 npm run update-types 运行它

🌐 Add the following script to your package.json to run it using npm run update-types

1
"update-types": "npx supabase gen types --lang=python --project-id \"$PROJECT_REF\" > database_types.py"

创建一个名为 .github/workflows/update-types.yml 的文件，里面加入以下片段来定义动作以及环境变量。这个脚本会每晚把新的类型更改提交到你的仓库。

🌐 Create a file .github/workflows/update-types.yml with the following snippet to define the action along with the environment variables. This script will commit new type changes to your repo every night.

1
name: Update database types
2
3
on:
4
  schedule:
5
    # sets the action to run daily. You can modify this to run the action more or less frequently
6
    - cron: '0 0 * * *'
7
8
jobs:
9
  update:
10
    runs-on: ubuntu-latest
11
    permissions:
12
      contents: write
13
    env:
14
      SUPABASE_ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
15
      PROJECT_REF: <your-project-id>
16
    steps:
17
      - uses: actions/checkout@v4
18
        with:
19
          persist-credentials: false
20
          fetch-depth: 0
21
      - uses: actions/setup-node@v4
22
        with:
23
          node-version: 22
24
      - run: npm run update-types
25
      - name: check for file changes
26
        id: git_status
27
        run: |
28
          echo "status=$(git status -s)" >> $GITHUB_OUTPUT
29
      - name: Commit files
30
        if: ${{contains(steps.git_status.outputs.status, ' ')}}
31
        run: |
32
          git add database_types.py
33
          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
34
          git config --local user.name "github-actions[bot]"
35
          git commit -m "Update database types" -a
36
      - name: Push changes
37
        if: ${{contains(steps.git_status.outputs.status, ' ')}}
38
        uses: ad-m/github-push-action@master
39
        with:
40
          github_token: ${{ secrets.GITHUB_TOKEN }}
41
          branch: ${{ github.ref }}

资源 #

🌐 Resources