kotlin客户端库

@supabase-community/supabase-kt

本参考文档记录了 Supabase 的 Kotlin 多平台库 supabase-kt 中可用的每个对象和方法。您可以使用 supabase-kt 与您的 Postgres 数据库交互、监听数据库变更、调用 Deno Edge 函数、构建登录和用户管理功能以及管理大型文件。

要查看支持的 Kotlin 目标，请查看 GitHub 上的相应模块 README。

要从版本 2.X 迁移到 3.0.0，请参阅迁移指南

Kotlin 客户端库由 Supabase 社区创建和维护，并非官方库。请对库仍在开发中的领域保持宽容，并且——与所有库一样——欢迎您在发现问题时随时贡献。

非常感谢官方维护者，jan-tennert。

安装

将一个或多个模块添加到您的项目#

使用 BOM 将依赖项添加到您的构建文件

可用的模块是

查看不同的 README 以获取有关支持的 Kotlin 目标的信息。

请注意，最低 Android SDK 版本为 26。对于较低版本，您需要启用核心库去糖化。

1
implementation(platform("io.github.jan-tennert.supabase:bom:VERSION"))
2
implementation("io.github.jan-tennert.supabase:postgrest-kt")
3
implementation("io.github.jan-tennert.supabase:auth-kt")
4
implementation("io.github.jan-tennert.supabase:realtime-kt")

将 Ktor 客户端引擎添加到您的每个 Kotlin 目标（必需）#

您可以在此处找到引擎列表

请注意，并非所有 Ktor 引擎都支持 WebSockets。因此，如果您计划使用 Realtime 模块，请确保使用支持 WebSockets 的引擎。有关更多信息，请查看引擎限制。
如果使用 supabase-kt 3.0.0 及更高版本，您需要使用 Ktor 版本 3.0.0-rc-1 或更高版本。

1
implementation("io.ktor:ktor-client-[engine]:KTOR_VERSION")

多平台示例

1
commonMain {
2
    dependencies {
3
        //Supabase modules
4
    }
5
}
6
jvmMain {
7
    dependencies {
8
        implementation("io.ktor:ktor-client-cio:KTOR_VERSION")
9
    }
10
}
11
androidMain {
12
    dependsOn(jvmMain.get())
13
}
14
jsMain {
15
    dependencies {
16
        implementation("io.ktor:ktor-client-js:KTOR_VERSION")
17
    }
18
}
19
iosMain {
20
    dependencies {
21
        implementation("io.ktor:ktor-client-darwin:KTOR_VERSION")
22
    }
23
}

序列化#

supabase-kt 提供了几种不同的编码和解码自定义对象的方法。默认情况下，使用 KotlinX 序列化。

使用 KotlinX 序列化。

1
plugins {
2
    kotlin("plugin.serialization") version "KOTLIN_VERSION"
3
}

1
val supabase = createSupabaseClient(supabaseUrl, supabaseKey) {
2
    //Already the default serializer, but you can provide a custom Json instance (optional):
3
    defaultSerializer = KotlinXSerializer(Json {
4
        //apply your custom config
5
    })
6
}

使用 Moshi。

1
implementation("io.github.jan-tennert.supabase:serializer-moshi:VERSION")

1
val supabase = createSupabaseClient(supabaseUrl, supabaseKey) {
2
    defaultSerializer = MoshiSerializer()
3
}

使用 Jackson。

1
implementation("io.github.jan-tennert.supabase:serializer-jackson:VERSION")

1
val supabase = createSupabaseClient(supabaseUrl, supabaseKey) {
2
    defaultSerializer = JacksonSerializer()
3
}

使用自定义序列化器。

1
class CustomSerializer: SupabaseSerializer {
2
3
    override fun <T : Any> encode(type: KType, value: T): String {
4
        //encode value to string
5
    }
6
7
    override fun <T : Any> decode(type: KType, value: String): T {
8
        //decode value
9
    }
10
11
}

1
val supabase = createSupabaseClient(supabaseUrl, supabaseKey) {
2
    defaultSerializer = CustomSerializer()
3
}

初始化

创建 Supabase 客户端#

无论您使用哪个 Supabase 模块，都需要先初始化主客户端并安装模块。

要创建一个新客户端，可以使用 createSupabaseClient 函数。

在安装模块时，您可以传递一个块来配置它。

OAuth 和 OTP 链接验证#

supabase-kt 提供了 OAuth 和 OTP 链接验证的几种平台实现。

在桌面平台（JVM、MacOS*、Linux、Windows）上，它使用 HTTP 回调服务器来接收成功的 OAuth 登录会话数据。可以通过 AuthConfig#httpCallbackConfig 自定义成功页面
* 如果未使用深层链接。

注意：OTP 链接验证，例如注册，在 JVM 上不受支持。您可能需要发送验证令牌而不是 URL 到您的电子邮件中。要发送令牌而不是重定向 URL，请将注册电子邮件中的 {{ .ConfirmationURL }} 更改为 {{ .Token }}

在 Android、iOS 和 MacOS 上，OAuth 和 OTP 验证使用深层链接。请参阅下面的指南以了解如何设置深层链接。或者，您可以使用原生 Google Auth。
在 JS 上，它使用网站来源作为回调 URL。会话导入会自动处理。
tvOS 和 watchOS 目前没有默认实现。欢迎创建 PR。

您始终可以创建自己的实现并使用 auth.parseSessionFromFragment(fragment) 或 auth.parseSessionFromUrl(url) 让 supabase-kt 在接收到回调后处理解析。然后，您只需使用 auth.importSession(session)。

配置身份验证的深层链接回调#

深层链接在 Android、iOS 和 MacOS 上受支持。

设置深层链接
在 Android 上，在您的 Android 清单文件中设置深层链接。
在 iOS 和 MacOS 上，设置 URL 方案。
将您的深层链接添加到重定向 URL
模式：scheme://host

配置 Auth 插件 在 Auth 配置中设置 host 和 scheme

1
install(Auth) {
2
   host = "deeplink host" // this can be anything, eg. your package name or app/company url (not your Supabase url)
3
   scheme = "deeplink scheme"
4
5
   // On Android only, you can set OAuth and SSO logins to open in a custom tab, rather than an external browser:
6
   defaultExternalAuthAction = ExternalAuthAction.CustomTabs() //defaults to ExternalAuthAction.ExternalBrowser
7
}

在启动时调用特定平台的函数
在 Android 上：supabase.handleDeeplinks(intent)
如果您不想单独的 Activity，只需在您的 MainActivity 的 onCreate 函数的顶部调用此函数即可。
在 iOS/MacOS 上：supabase.handleDeeplinks(url)

然后您就可以使用 OAuth 登录

1
supabase.auth.signInWith(Google)

或直接在您的应用程序中打开 OTP 链接。

PKCE 身份验证流程#

supabase-kt 支持 PKCE 身份验证流程。要使用它，请在 Auth 配置中更改 flowType

1
install(Auth) {
2
  flowType = FlowType.PKCE
3
}

就是这样！如果您已经实现了深层链接来处理 OTP 和 OAuth，则无需更改任何内容！

参数

supabaseUrl
必需
字符串
您在项目仪表板中创建新项目时提供的唯一 Supabase URL。
supabaseKey
必需
字符串
您在项目仪表板中创建新项目时提供的唯一 Supabase Key。
builder
可选
SupabaseClientBuilder.() -> Unit
应用额外的配置并安装插件。

1
val supabase = createSupabaseClient(
2
    supabaseUrl = "https://xyzcompany.supabase.co",
3
    supabaseKey = "publishable-or-anon-key"
4
) {
5
    install(Auth)
6
    install(Postgrest)
7
    //install other modules
8
}

获取数据

对表或视图执行 SELECT 查询。

在调用 decode 方法时，您必须提供一个可序列化的类作为类型参数。
您可以提供一个 Columns 对象来选择特定的列。
您可以提供一个过滤器块来过滤结果

参数

列
可选
Columns
要检索的列，默认为 Columns.ALL。您还可以使用 Columns.list、Columns.type 或 Columns.raw 来指定列。
head
可选
Boolean
如果为 true，则 select 将删除选定的数据。
request
可选
PostgrestRequestBuilder.() -> Unit
请求的额外配置和过滤。

1
val city = supabase.from("cities").select().decodeSingle<City>()

插入数据

执行插入到表或视图的操作。

在调用 insert 方法时，您必须提供一个可序列化的值。
默认情况下，insert 不会返回插入的数据。如果您想返回插入的数据，可以在请求中使用 select() 方法。

参数

value
必需
T 或 List<T>
您想要插入的值。T 可以是任何可序列化的类型。
request
可选
PostgrestRequestBuilder.() -> Unit
请求的额外配置和过滤。

1
val city = City(name = "The Shire", countryId = 554)
2
supabase.from("cities").insert(city)

更新数据

执行 UPDATE 到表或视图。

update() 应该始终与过滤器块结合使用，以避免更新所有记录。
在调用 insert 或 update 时，您必须提供一个可序列化的值作为函数参数。
默认情况下，update 不会返回插入的数据。如果您想返回插入的数据，可以在请求中使用 select() 方法。

参数

value
必需
T 或 PostgrestUpdate.() -> Unit = {}
新值，可以是可序列化的值或 PostgrestUpdate DSL，您可以在其中设置每个列的新值。
request
可选
PostgrestRequestBuilder.() -> Unit
请求的额外配置和过滤。

1
supabase.from("characters").update(
2
    {
3
       Country::name setTo "Han Solo"
4
       //or
5
       set("name", "Han Solo")
6
    }
7
) {
8
    filter {
9
        Character::id eq 1
10
        //or
11
        eq("id", 1)
12
    }
13
}

更新或插入数据

执行表或视图上的 UPSERT。根据传递到 onConflict 的列，.upsert() 允许您执行与 .insert() 相同的功能，如果具有相应的 onConflict 列的行不存在，或者如果存在，则根据 ignoreDuplicates 执行替代操作。

主键应包含在数据负载中，以便更新正常工作。
主键必须是自然的，而不是代理的。但是，有一些解决方法用于代理主键。
如果您需要同时插入新数据和更新现有数据，请使用 Postgres 触发器。
在调用 insert 或 update 时，您必须提供一个可序列化的值作为函数参数。
默认情况下，upsert 不会返回插入的数据。如果您想返回插入的数据，可以在请求中使用 select() 方法。

参数

value
必需
T 或 List<T>
您想要插入的值。T 可以是任何可序列化的类型。
request
可选
PostgrestRequestBuilder.() -> Unit
请求的额外配置和过滤。

1
val toUpsert = Message(id = 3, message = "foo", username = "supabot")
2
supabase.from("messages").upsert(toUpsert)

删除数据

执行 DELETE 到表或视图。

delete() 应该始终与过滤器块结合使用，以定位您想要删除的项目。
如果您使用带有过滤器的 delete() 并且启用了 RLS，则只会删除通过 SELECT 策略可见的行。请注意，默认情况下没有行可见，因此您至少需要一个使行可见的 SELECT/ALL 策略。
默认情况下，delete 不会返回删除的数据。如果您想返回删除的数据，可以在请求中使用 select() 方法。

参数

request
可选
PostgrestRequestBuilder.() -> Unit
请求的额外配置和过滤。

1
supabase.from("cities").delete {
2
    filter {
3
        City::id eq 666
4
        //or
5
        eq("id", 666)
6
    }
7
}

调用 Postgres 函数

您可以将存储过程作为“远程过程调用”来调用。

这是一种花哨的说法，您可以将一些逻辑放入您的数据库，然后从任何地方调用它。当逻辑很少更改时，它特别有用——例如密码重置和更新。

在调用带有参数的 rpc 时，您必须提供一个可序列化的值作为函数参数。

参数

function
必需
字符串
函数名称
parameters
可选
T
传递给函数的参数。T 可以是任何可序列化的类型。
request
可选
PostgrestRequestBuilder.() -> Unit
请求的额外配置和过滤。

1
supabase.postgrest.rpc("hello_world")

使用过滤器

过滤器允许你仅返回匹配特定条件的行。

过滤器可用于 select()、update() 和 delete() 查询。

您可以使用两种不同的类型来应用过滤器

1
eq("country_id", 1)

并使用类属性

1
City::countryId eq 1

如您在属性语法中看到的那样：countryId 的名称转换为 country_id。

默认情况下，这是通过将驼峰式转换为蛇形式来完成的，但您可以更改 Postgrest 配置中的 propertyConversionMethod 来自定义它

如果数据库函数返回表响应，您也可以应用过滤器。

1
supabase.from("cities").select(columns = Columns.list("name", "country_id")) {
2
    filter {
3
        City::name eq "The Shire"
4
        //or
5
        eq("name", "The Shire")
6
    }
7
}

列等于一个值

查找指定 column 上的值与指定的 value 完全匹配的所有行。

参数

column
必需
字符串
要过滤的列。
value
必需
Any
要过滤的值。

1
supabase.from("cities").select(columns = Columns.list("name", "country_id")) {
2
    filter {
3
        City::name eq "The Shire"
4
        //or
5
        eq("name", "The Shire")
6
    }
7
}

列不等于一个值

查找所有 column 的值与指定的 value 不匹配的行。

参数

column
必需
字符串
要过滤的列。
value
必需
Any
要过滤的值。

1
supabase.from("cities").select(columns = Columns.list("name", "country_id")) {
2
    filter {
3
        City::name neq "The Shire"
4
        //or
5
        neq("name", "The Shire")
6
    }
7
}

列大于一个值

查找所有 column 的值大于指定的 value 的行。

参数

column
必需
字符串
要过滤的列。
value
必需
Any
要过滤的值。

1
supabase.from("cities").select(columns = Columns.list("name")) {
2
    filter {
3
       City::countryId gt 300
4
       //or
5
       gt("country_id", 300)
6
    }
7
}

列大于或等于一个值

查找所有 column 的值大于或等于指定的 value 的行。

参数

column
必需
字符串
要过滤的列。
value
必需
Any
要过滤的值。

1
supabase.from("cities").select(columns = Columns.list("name")) {
2
    filter {
3
       City::countryId gte 300
4
       //or
5
       gte("country_id", 300)
6
    }
7
}

列小于一个值

查找所有 column 的值小于指定的 value 的行。

参数

column
必需
字符串
要过滤的列。
value
必需
Any
要过滤的值。

1
supabase.from("cities").select(columns = Columns.list("name")) {
2
    filter {
3
       City::countryId lt 300
4
       //or
5
       lt("country_id", 300)
6
    }
7
}

列小于或等于一个值

查找所有 column 的值小于或等于指定的 value 的行。

参数

column
必需
字符串
要过滤的列。
value
必需
Any
要过滤的值。

1
supabase.from("cities").select(columns = Columns.list("name")) {
2
    filter {
3
       City::countryId lte 300
4
       //or
5
       lte("country_id", 300)
6
    }
7
}

列匹配一个模式

查找所有 column 的值与提供的 pattern 匹配的行（区分大小写）。

参数

column
必需
字符串
要过滤的列。
pattern
必需
字符串
要匹配的模式。

1
supabase.from("cities").select(columns = Columns.list("name")) {
2
    filter {
3
       City::name like "%la%"
4
       //or
5
       like("name", "%la%")
6
    }
7
}

列匹配一个不区分大小写的模式

查找所有 column 的值与提供的 pattern 匹配的行（不区分大小写）。

参数

column
必需
字符串
要过滤的列。
pattern
必需
字符串
要匹配的模式。

1
supabase.from("cities").select(columns = Columns.list("name")) {
2
    filter {
3
       City::name ilike "%la%"
4
       //or
5
       ilike("name", "%la%")
6
    }
7
}

列是一个值

用于精确相等性（null、true、false）的检查，查找所有 column 的值与指定的 value 完全匹配的行。

is_ 和 in_ 过滤器方法以 _ 为后缀，以避免与保留关键字冲突。

参数

column
必需
字符串
要过滤的列。
value
必需
布尔值？
要过滤的值。

1
supabase.from("cities").select(columns = Columns.list("name")) {
2
    filter {
3
       City::name isExact null
4
       //or
5
       exact("name", null)
6
    }
7
}

列在一个数组中

查找所有 column 的值在指定的 values 中找到的行。

参数

column
必需
字符串
要过滤的列。
值
必需
Any类型的列表
用于过滤的值。

1
supabase.from("cities").select(columns = Columns.list("name")) {
2
    filter {
3
       City::name isIn listOf("Hobbiton", "Edoras")
4
       //or
5
       isIn("name", listOf("Hobbiton", "Edoras"))
6
    }
7
}

列包含数组中的每个元素

仅适用于 jsonb、数组和范围列。仅匹配 column 包含 value 中出现的每个元素的行。

参数

column
必需
字符串
要过滤的jsonb、数组或范围列
value
必需
Any类型的列表
用于过滤的jsonb、数组或范围值

1
supabase.from("cities").select(columns = Columns.list("name")) {
2
    filter {
3
       City::mainExports contains listOf("oil")
4
       //or
5
       contains("main_exports", listOf("oil"))
6
    }
7
}

大于一个范围

仅适用于范围列。仅匹配列中的每个元素都大于范围中任何元素的行。

参数

column
必需
字符串
要过滤的列。
值
必需
Any类型的键值对
用于过滤的值。

1
supabase.from("reservations").select {
2
      filter {
3
         Reservation::during rangeGt ("2000-01-02 08:30" to "2000-01-02 09:30")
4
         //or
5
         rangeGt("during", "2000-01-02 08:30" to "2000-01-02 09:30")
6
      }
7
  }

大于或等于一个范围

仅适用于范围列。仅匹配列中的每个元素都包含在范围内或大于范围中任何元素的行。

参数

column
必需
字符串
要过滤的列。
值
必需
Any类型的键值对
用于过滤的值。

1
supabase.from("reservations").select {
2
      filter {
3
         Reservation::during rangeGte ("2000-01-02 08:30" to "2000-01-02 09:30")
4
         //or
5
         rangeGte("during", "2000-01-02 08:30" to "2000-01-02 09:30")
6
      }
7
  }

小于一个范围

仅适用于范围列。仅匹配列中的每个元素都小于范围中任何元素的行。

参数

column
必需
字符串
要过滤的列。
值
必需
Any类型的键值对
用于过滤的值。

1
supabase.from("reservations").select {
2
      filter {
3
         Reservation::during rangeLt ("2000-01-02 08:30" to "2000-01-02 09:30")
4
         //or
5
         rangeLt("during", "2000-01-02 08:30" to "2000-01-02 09:30")
6
      }
7
  }

小于或等于一个范围

仅适用于范围列。仅匹配列中的每个元素都包含在范围内或小于范围中任何元素的行。

参数

column
必需
字符串
要过滤的列。
值
必需
Any类型的键值对
用于过滤的值。

1
supabase.from("reservations").select {
2
      filter {
3
         Reservation::during rangeLte ("2000-01-02 08:30" to "2000-01-02 09:30")
4
         //or
5
         rangeLte("during", "2000-01-02 08:30" to "2000-01-02 09:30")
6
      }
7
  }

与范围互斥

仅适用于范围列。仅匹配列与范围互斥，并且两个范围之间没有元素。

参数

column
必需
字符串
要过滤的列。
值
必需
Any类型的键值对
用于过滤的值。

1
supabase.from("reservations").select {
2
      filter {
3
         Reservation::during adjacent ("2000-01-02 08:30" to "2000-01-02 09:30")
4
         //or
5
         adjacent("during", "2000-01-02 08:30" to "2000-01-02 09:30")
6
      }
7
  }

具有共同元素

仅适用于数组和范围列。仅匹配列和值具有共同元素。

参数

column
必需
字符串
要过滤的列。
值
必需
Any类型的列表
用于过滤的值。

1
supabase.from("issues").select(columns = Columns.list("title")) {
2
    filter {
3
       Issue::tags overlaps listOf("is:closed", "severity:high")
4
       //or
5
       overlaps("tags", listOf("is:closed", "severity:high"))
6
    }
7
}

匹配一个字符串

仅适用于文本和tsvector列。仅匹配 column 与 query 中的查询字符串匹配的行。

有关更多信息，请参阅 Postgres 全文搜索。

参数

column
必需
字符串
要过滤的文本或tsvector列
query
必需
字符串
要匹配的查询文本
textSearchType
可选
TextSearchType
要使用的文本搜索类型。默认为 TextSearchType.NONE。
config
可选
字符串
要使用的文本搜索配置。

1
supabase.from("quotes").select(columns = Columns.list("catchphrase")) {
2
    filter {
3
       textSearch(column = "catchphrase", query = "'fat' & 'cat'", config = "english", type = TextSearchType.YOUR_TYPE)
4
    }
5
}

不匹配过滤器

查找所有不满足过滤条件的行。

.filterNot() 要求您使用原始 PostgREST 语法来指定过滤器的名称和值。

参数

column
必需
字符串
要过滤的列。
operator
必需
FilterOperator
用于过滤器的运算符。
value
必需
Any
要过滤的值。

1
supabase.from("countries").select {
2
    filter {
3
        filterNot("name", FilterOperator.IS, "")
4
    }
5
}

匹配至少一个过滤器

查找满足至少一个过滤器的所有行。

参数

negate
可选
Boolean
如果为 true，则否定整个块。
block
必需
PostgrestFilterBuilder.() -> Unit
将应用 or 过滤器到的块。

1
supabase.from("countries").select(columns = Columns.list("name")) {
2
    filter {
3
        or {
4
            Country::id eq 2
5
            Country::name eq "Mordor"
6
            //or
7
            eq("id", 2)
8
            eq("name", "Mordor")
9
        }
10
    }
11
}

匹配过滤器

filter() 期望您使用原始 PostgREST 语法来获取过滤器的值。

参数

column
必需
字符串
要过滤的列。
operator
必需
FilterOperator
用于过滤器的运算符。
value
必需
Any
要过滤的值。

1
supabase.from("characters").select {
2
    filter {
3
       filter(column = "name", operator = FilterOperator.IN, value = "('Han', 'Katniss')")
4
    }
5
}

使用修饰符

过滤器在行级别上工作——它们允许您仅返回匹配特定条件的行，而不会更改行的形状。修饰符是所有不符合该定义的内容——允许您更改响应的格式（例如，返回 CSV 字符串）。

修饰符在过滤器块旁边指定。某些修饰符仅适用于返回行的查询（例如，select() 或返回表格响应的函数上的 rpc()）。

插入后返回数据

参数

列
可选
Columns
要选择的列。

1
val toUpsert = Country(id = 2, name = "Mordor")
2
val count = supabase.from("countries").upsert(toUpsert) {
3
    select()
4
}.decodeSingle<Country>()

对结果进行排序

按列对查询结果进行排序。

参数

column
必需
字符串
要排序的列。
order
必需
Order
要使用的排序方式。
nullsFirst
可选
Boolean
是否先排序 null 值。
referencedTable
可选
字符串
要排序的外部表。

1
supabase.from("characters").select(columns = Columns.list("id", "name")) {
2
   order(column = "id", order = Order.DESCENDING)
3
}

限制返回的行数

按计数限制查询结果。

参数

count
必需
Long
将结果限制为的行数。
referencedTable
可选
字符串
要限制的外部表。

1
supabase.from("characters").select {
2
    limit(count = 1)
3
}

将查询限制在一个范围内

按 from 和 to 包含性地限制查询结果。

参数

from
必需
Long
范围的开始。
to
必需
Long
范围的结束。
referencedTable
可选
字符串
要限制的外部表。

1
supabase.from("characters").select {
2
    range(1L..5L)
3
}

检索一行数据

1
val result = supabase.from("characters").select(Columns.list("name")) {
2
    limit(1)
3
    single()
4
}

检索为 CSV

1
val (csvData, _) = supabase.from("characters").select {
2
    csv()
3
}

使用 explain

为了调试慢查询，你可以使用 explain() 方法获取查询的 Postgres EXPLAIN 执行计划。这适用于任何查询，甚至适用于 rpc() 或写入。

Explain 默认情况下未启用，因为它可能会泄露数据库中的敏感信息。最好仅在测试环境中使用，但如果您希望在生产环境中使用，可以通过使用 `pre-request` 函数提供额外的保护。

请遵循性能调试指南以在您的项目上启用该功能。

参数

analyze
可选
Boolean
如果 true，则将执行查询并返回实际运行时间
verbose
可选
Boolean
如果 true，将返回查询标识符，并且 data 将包含查询的输出列
settings
可选
Boolean
如果 true，则包含影响查询计划的配置参数信息
buffers
可选
Boolean
如果 true，则包含有关缓冲区使用情况的信息
wal
可选
Boolean
如果 true，则包含有关 WAL 记录生成的信息
format
可选
字符串
输出的格式，可以是 "text"（默认）或 "json"

1
val result = supabase.from("characters").select {
2
    explain()
3
}

概述

可以通过 Supabase Auth 客户端访问身份验证方法。

1
val supabase = createSupabaseClient(supabaseUrl = "https://xyzcompany.supabase.co'", supabaseKey = "publishable-or-anon-key") { ... }
2
val auth = supabase.auth

创建新用户

创建一个新用户。

默认情况下，用户需要在登录前验证其电子邮件地址。要关闭此功能，请在您的项目中禁用 **确认电子邮件**。
**确认电子邮件** 确定用户在注册后是否需要确认其电子邮件地址。
- 如果启用了 确认电子邮件，则返回值是用户，您不会自动登录。
- 如果禁用了 确认电子邮件，则返回值为空，您将登录。
当用户确认其电子邮件地址时，默认情况下他们将被重定向到 SITE_URL。您可以在您的项目中修改 SITE_URL 或添加其他重定向 URL。
要了解如何处理 OTP 链接和 OAuth，请参阅初始化
如果为已确认的用户调用 signUpWith()
- 当在您的项目中同时启用 **确认电子邮件** 和 **确认电话**（即使电话提供程序已禁用）时，将返回一个混淆/虚假的用户对象。
- 当 **确认电子邮件** 或 **确认电话**（即使电话提供程序已禁用）中的任何一个被禁用时，将返回错误消息 `User already registered`。

参数

provider
必需
电子邮件或电话
用于用户身份验证的提供程序。在本例中为 Email 或 Phone。
redirectUrl
可选
String?
要使用的重定向 URL。如果您没有指定此 URL，将使用特定于平台的 URL，例如 Android 上的深层链接。
config
可选
Email.Config.() -> Unit 或 Phone.Config.() -> Unit
使用 Email 或 Phone 进行注册的配置。

监听认证事件

监听会话更改。

sessionStatus 是一个 Flow<SessionStatus>，它会发出当前的会话状态。与会话相关的所有内容都由此流处理。
events 是一个 Flow<AuthEvent>，它会发出身份验证事件。此流用于监听与当前会话无关的身份验证事件，例如 OTP 错误、刷新失败等。实验性。

1
supabase.auth.sessionStatus.collect {
2
    when(it) {
3
        is SessionStatus.Authenticated -> {
4
            println("Received new authenticated session.")
5
            when(it.source) { //Check the source of the session
6
                SessionSource.External -> TODO()
7
                is SessionSource.Refresh -> TODO()
8
                is SessionSource.SignIn -> TODO()
9
                is SessionSource.SignUp -> TODO()
10
                SessionSource.Storage -> TODO()
11
                SessionSource.Unknown -> TODO()
12
                is SessionSource.UserChanged -> TODO()
13
                is SessionSource.UserIdentitiesChanged -> TODO()
14
            }
15
        }
16
        SessionStatus.Initializing -> println("Initializing")
17
        is SessionStatus.RefreshFailure -> {
18
            println("Session expired and could not be refreshed")
19
        }
20
        is SessionStatus.NotAuthenticated -> {
21
            if(it.isSignOut) {
22
                println("User signed out")
23
            } else {
24
                println("User not signed in")
25
            }
26
        }
27
    }
28
}

创建匿名用户

创建一个匿名用户。
可以通过调用 supabase.auth.currentUserOrNull() 来检索用户。
建议为匿名注册设置验证码以防止滥用。您可以在 `options` 参数中传递验证码令牌。

参数

captchaToken
可选
String?
启用 captcha 时的 captcha 令牌。
data
可选
JsonObject? 或 T
要传递的额外用户数据。

登录用户

登录现有用户。

需要电子邮件和密码或电话号码和密码。

参数

provider
必需
电子邮件或电话
用于用户身份验证的提供程序，在本例中为 Email 或 Phone。
redirectUrl
可选
String?
要使用的重定向 URL。如果您没有指定此 URL，将使用特定于平台的 URL，例如 Android 上的深层链接。
config
可选
Email.Config.() -> Unit 或 Phone.Config.() -> Unit
使用 Email 或 Phone 进行注册的配置。

使用 ID Token 登录 (原生登录)

参数

provider
必需
IDToken
用于用户身份验证的提供程序。对于此方法，它将是 IDToken。
redirectUrl
可选
String?
要使用的重定向 URL。如果您没有指定此 URL，将使用特定于平台的 URL，例如 Android 上的深层链接。
config
可选
IDToken.Config.() -> Unit
使用 ID 令牌进行注册的配置。

1
supabase.auth.signInWith(IDToken) {
2
    idToken = "token"
3
    provider = Google //Also supported: Apple, Azure and Facebook
4
    //optional:
5
    nonce = "nonce"
6
    data = buildJsonObject {
7
        //...
8
    }
9
}

通过 OTP 登录用户

向用户的电子邮件或电话号码发送 OTP。

需要电子邮件或电话号码。
此方法用于无密码登录，其中 OTP 会发送到用户的电子邮件或电话号码。
如果用户不存在，signInWith(OTP) 将注册用户。要限制此行为，您可以将 createUser 设置为 false。
signUpWith(OTP) 执行与 signInWith(OTP) 相同的功能，因此使用哪个无关紧要。
如果您使用的是电子邮件，您可以配置是否希望用户接收 magiclink 或 OTP。
如果您使用的是电话，您可以配置是否希望用户接收 OTP。
magic link 的目标 URL 由 SITE_URL 确定。
请参阅重定向 URL 和通配符以将其他重定向 URL 添加到您的项目。
要了解如何处理 OTP 链接和 OAuth，请参阅初始化
魔术链接和 OTP 共享相同的实现。要向用户发送一次性代码而不是魔术链接，请修改魔术链接电子邮件模板以包含 {{ .Token }} 而不是 {{ .ConfirmationURL }}。

参数

provider
必需
OTP
用于用户身份验证的提供程序，在本例中为 OTP。
redirectUrl
可选
String?
要使用的重定向 URL。如果您没有指定此 URL，将使用特定于平台的 URL，例如 Android 上的深层链接。
config
可选
OTP.Config.() -> Unit
使用 OTP 进行注册的配置。

通过 OAuth 登录用户

此方法用于使用第三方提供程序登录。
Supabase 支持许多不同的第三方提供程序。
要了解如何处理 OTP 链接和 OAuth，请参阅初始化

参数

provider
必需
OAuthProvider
用于用户身份验证的 OAuth 提供程序，例如 Google 或 GitHub。
redirectUrl
可选
String?
要使用的重定向 URL。如果您没有指定此 URL，将使用特定于平台的 URL，例如 Android 上的深层链接。
config
可选
ExternalAuthConfig.() -> Unit
使用 OAuth 提供程序进行注册的配置。

通过 SSO 登录用户

在您可以使用此方法之前，您需要建立与身份提供程序的连接。使用 CLI 命令来执行此操作。
如果您已将电子邮件域与身份提供程序关联，则可以在 signInWith(SSO) 方法中更改 domain 属性以启动登录流程。
如果您需要使用不同的方式启动与身份提供程序的身份验证流程，您可以更改 providerId 属性。例如
- 将特定的用户电子邮件地址与身份提供程序映射。
- 使用不同的提示来识别用户要使用的身份提供程序，例如公司特定的页面、IP 地址或其他跟踪信息。
要了解如何处理 OTP 链接和 OAuth，请参阅初始化

参数

provider
必需
SSO
用于用户身份验证的 OAuth 提供程序，在本例中为 SSO。
redirectUrl
可选
String?
要使用的重定向 URL。如果您没有指定此 URL，将使用特定于平台的 URL，例如 Android 上的深层链接。
config
可选
ExternalAuthConfig.() -> Unit
使用 OAuth 提供程序进行注册的配置。

1
// You can extract the user's email domain and use it to trigger the
2
  // authentication flow with the correct identity provider.
3
4
  supabase.auth.signInWith(SSO) {
5
      domain = "company.com"
6
  }
7
8
  //the url was opened automatically, if you don't want that, provide a custom redirect url

从经过验证的 JWT 获取用户声明

首先通过验证服务器的 JSON Web Key Set (JWKS) 端点来验证 JWT，然后从访问令牌中提取 JWT 声明。

优选此方法而不是 retrieveUser()，因为 JWKS 响应已缓存，从而产生显著更快的响应。
如果项目未使用非对称 JWT 签名密钥（如 ECC 或 RSA），它将向 Auth 服务器发送请求（类似于 retrieveUser()）以验证 JWT。
返回一个 ClaimsResponse，其中包含 claims（一个带有标准 JWT 字段的类型访问器的 JwtPayload）、header 和 signature。
JwtPayload 上可用的标准声明：iss、sub、aud、exp、iat、role、aal、sessionId、email、phone、isAnonymous、amr、appMetadata、userMetadata。
使用 claims.getClaim<T>(key) 或 claims.getClaimOrNull<T>(key) 获取自定义声明。

参数

jwt
可选
String?
一个可选的特定 JWT 进行验证。如果未提供，则使用当前会话的访问令牌。
options
可选
ClaimsRequestBuilder.() -> Unit
用于自定义行为的选项，例如允许过期的令牌。

1
val response = supabase.auth.getClaims()
2
val email = response.claims.email
3
val role = response.claims.role
4
val aal = response.claims.aal

注销用户

注销当前用户。

为了使用 `signOut()` 方法，用户需要先登录。

参数

scope
可选
SignOutScope
注销的范围。

1
supabase.auth.signOut()

发送密码重置请求

向给定的电子邮件地址发送密码重置请求。

密码重置流程包含 2 个主要步骤：(i) 允许用户通过密码重置链接登录；(ii) 更新用户的密码。
resetPasswordForEmail() 仅将密码重置链接发送到用户的电子邮件。要更新用户的密码，请参阅 updateUser()。
用户会重定向回您的应用程序，假设您设置了 OTP 处理
用户成功重定向后，提示他们输入新密码并调用 updateUser()
```
1
supabase.auth.updateUser {
2
    password = "1234567"
3
}
```

参数

email
必需
字符串
要发送密码重置电子邮件的电子邮件。
redirectUrl
可选
String?
要使用的重定向 URL。如果您没有指定此 URL，将使用特定于平台的 URL，例如 Android 上的深层链接。
captchaToken
可选
String?
启用 captcha 时的 captcha 令牌。

1
supabase.auth.resetPasswordForEmail(email = "example@email.com")

通过 OTP 验证并登录

验证 OTP 是通过 verifyPhoneOtp 或 verifyEmailOtp 完成的。
应根据在调用 verifyPhoneOtp/verifyEmailOtp 注册/登录用户之前调用的相应身份验证方法来确定使用的验证类型。

参数

type
必需
OtpType.Email 或 OtpType.Phone
OTP 类型。根据类型，必须指定电子邮件或电话号码作为参数。
电子邮件/电话
必需
字符串
根据您指定的类型，电子邮件或电话号码。
token
必需
字符串
要验证的令牌。
captchaToken
可选
String?
启用 captcha 时的 captcha 令牌。

1
supabase.auth.verifyEmailOtp(type = OtpType.Email.EMAIL, email = "example@email.com", token = "token")

获取会话

返回当前会话，如果没有会话则返回 null。

1
val session = supabase.auth.currentSessionOrNull()

获取新的会话

此方法将刷新会话，无论当前会话是否过期。

这是自动完成的，但可以在 Auth 配置中禁用。

参数

refreshToken
必需
字符串
要使用的刷新令牌。

1
val session = supabase.auth.refreshCurrentSession()

获取用户

此方法从当前会话获取用户对象。
从数据库而不是本地会话获取用户对象。
仅当您需要最新的用户数据时才应使用此方法。为了获得更快的速度，建议使用 getCurrentSessionOrNull()?.user。

参数

jwt
必需
字符串
JWT 令牌。

1
val user = supabase.auth.retrieveUserForCurrentSession(updateSession = true)

更新用户

修改用户数据。

为了使用 `updateUser()` 方法，用户需要先登录。
默认情况下，电子邮件更新会将确认链接发送到用户的当前电子邮件和新电子邮件。要仅将确认链接发送到用户的新的电子邮件，请在您项目的电子邮件身份验证提供程序设置中禁用 **安全电子邮件更改**。

参数

updateCurrentUser
可选
Boolean
是否使用新的用户更新本地会话。默认为 true。
redirectUrl
可选
String?
要使用的重定向 URL。如果您没有指定此 URL，将使用特定于平台的 URL，例如 Android 上的深层链接。
config
必需
UserUpdateBuilder.() -> Unit

1
val user = supabase.auth.updateUser {
2
   email = "newEmail@email.com"
3
}

获取与用户关联的身份

用户需要登录才能调用 currentIdentitiesOrNull()。

1
//get the identities from the current user
2
val identities = supabase.auth.currentIdentitiesOrNull()
3
//Or retrieve them
4
val identities = supabase.auth.retrieveUserForCurrentSession().identities

将身份与用户关联

必须从您的项目身份验证设置中启用 **启用手动链接** 选项。
需要先登录才能调用 `linkIdentity()`。
如果候选身份已链接到现有用户或另一个用户，`linkIdentity()` 将失败。
此方法的工作方式类似于使用 OAuthProvider 的 signInWith()。要了解如何处理 OTP 链接和 OAuth，请参阅 initializing

参数

provider
必需
OAuthProvider
您要将用户关联的 OAuth 提供程序。
redirectUrl
可选
String?
要使用的重定向 URL。如果您没有指定此 URL，将使用特定于平台的 URL，例如 Android 上的深层链接。
config
可选
ExternalAuthConfigDefaults.() -> Unit
额外的配置。

1
supabase.auth.linkIdentity(OAuthProvider)
2
3
//Example:
4
supabase.auth.linkIdentity(Google)

将身份从用户取消关联

必须从您的项目身份验证设置中启用 **启用手动链接** 选项。
用户需要已登录才能调用 unlinkIdentity()。
用户必须至少拥有 2 个身份才能取消关联一个身份。
要取消关联的身份必须属于该用户。

参数

identityId
必需
字符串
OAuth 身份的 ID
updateLocalUser
可选
Boolean
是否从本地用户中删除身份。默认为 true。

1
//get all identities linked to a user
2
val identities = supabase.auth.currentIdentitiesOrNull() ?: emptyList()
3
4
//find the google identity linked to the user
5
val googleIdentity = identities.first { it.provider == "google" }
6
7
//unlink the google identity from the user
8
supabase.auth.unlinkIdentity(googleIdentity.identityId!!)

发送密码重新认证 nonce

当需要更新用户的密码时，此方法与 updateUser() 结合使用。
此方法会将 nonce 发送到用户的电子邮件。如果用户没有确认的电子邮件地址，该方法会将 nonce 发送到用户的确认的电话号码。

1
supabase.auth.reauthenticate()

重新发送 OTP

通过再次调用 reset_password_for_email() 方法，可以重新发送密码重置电子邮件。
可以通过再次调用 signInWith(OTP) 方法来重新发送无密码登录。
可以通过再次调用 resetPasswordForEmail() 方法重新发送密码恢复电子邮件。
只有在进行初始注册、电子邮件更改或电话号码更改请求时，此方法才会重新向用户发送电子邮件或电话 OTP。

参数

type
必需
OtpType.Email 或 OtpType.Phone
OTP 类型。根据类型，必须指定电子邮件或电话号码作为参数。
电子邮件/电话
必需
字符串
根据您指定的类型，电子邮件或电话号码。
captchaToken
可选
String?
启用 captcha 时的 captcha 令牌。

设置会话数据

更改本地会话。

importSession() 接收一个 UserSession。
刷新令牌轮换默认在所有项目上启用，以防止重放攻击。
您可以配置 REFRESH_TOKEN_REUSE_INTERVAL，它提供了一个简短的时间窗口，在并发或离线问题的情况下，可以在该窗口内多次使用相同的刷新令牌。

参数

session
必需
UserSession
要设置的会话。

1
supabase.auth.importSession(UserSession(accessToken = "token", refreshToken = "refresh", expiresIn = 2000, tokenType = "Bearer", user = null))

将授权码交换为会话

当 Auth 配置中 flowType 设置为 FlowType.PKCE 时使用。

参数

code
必需
字符串
要交换的代码。
saveSession
可选
Boolean
是否保存会话。默认为 true。

1
supabase.auth.exchangeCodeForSession("34e770dd-9ff9-416c-87fa-43b31d7ef225")

认证 MFA

本节包含通常用于多因素身份验证 (MFA) 的方法，并在 supabase.auth.mfa 命名空间下调用。

目前，我们仅支持基于时间的 One-Time Password (TOTP) 作为第二个因素。我们不支持恢复代码，但允许用户注册超过 1 个 TOTP 因素，上限为 10 个。

拥有第二个 TOTP 因素用于恢复，可以减轻用户存储恢复代码的负担。它还可以减少攻击面，因为通常会生成多个恢复代码，而不仅仅是 1 个备份 TOTP 因素。

注册因素

注册新的因素。

使用 FactorType.TOTP 或 FactorType.Phone 作为 factorType，并使用返回的 id 创建一个挑战。
要创建挑战，请参阅 mfa.createChallenge()。
要验证挑战，请参阅 mfa.verifyChallenge()。
要一步创建和验证挑战，请参阅 mfa.createChallengeAndVerify()。

参数

factorType
必需
FactorType<C, R>
要注册的多因素身份验证类型。目前支持 FactorType.TOTP 和 FactorType.Phone。
issuer
可选
String?
用户注册的域名。
config
可选
Config.() -> Unit
特定于因素类型的配置。

1
val factor = supabase.auth.mfa.enroll(factorType = FactorType.TOTP, friendlyName = "Your friendly Name") {
2
      // Optional
3
      issuer = "example.com"
4
}
5
6
// Use the id to create a challenge.
7
// The challenge can be verified by entering the code generated from the authenticator app.
8
// The code will be generated upon scanning the qr_code or entering the secret into the authenticator app.
9
val (id, type, qrCode) = factor.data //qrCode is a svg as a string
10
val (factorId, factorType, _) = factor
11
val challenge = supabase.auth.mfa.createChallenge(factor.id)

创建挑战

为因素创建挑战。

在创建挑战之前需要一个注册的因素。
要验证挑战，请参阅 mfa.verifyChallenge()。
电话因素会在挑战时向用户发送代码。通道默认为 Phone.Channel.SMS，除非另有说明。

参数

factorId
必需
字符串
您要为其创建挑战的多因素身份验证因素的 ID。
channel
可选
Phone.Channel?
将挑战发送到的通道。默认为 Phone.Channel.SMS。

1
val challenge = supabase.auth.mfa.createChallenge(factorId = "34e770dd-9ff9-416c-87fa-43b31d7ef225")

验证挑战

验证因素的挑战。

要验证挑战，请先创建挑战。

参数

factorId
必需
字符串
要验证的多因素身份验证因素的 ID。
challengeId
必需
字符串
要验证的挑战的 ID。
code
必需
字符串
用于验证的代码。
saveSession
可选
Boolean
是否保存会话。默认为 true。

1
supabase.auth.mfa.verifyChallenge(
2
    factorId = "34e770dd-9ff9-416c-87fa-43b31d7ef225",
3
    challengeId = "4034ae6f-a8ce-4fb5-8ee5-69a5863a7c15",
4
    code = "123456",
5
    saveSession = true // this is set to true by default, but you can set it to false if you want to handle the session yourself
6
)

创建并验证挑战

为因素创建并验证挑战。

Phone 因素类型不支持一步创建和验证挑战。
在调用 createChallengeAndVerify() 之前需要一个注册的因素。
一步执行 mfa.createChallenge() 和 mfa.verifyChallenge()。

参数

factorId
必需
字符串
要验证的多因素身份验证因素的 ID。
code
必需
字符串
用于验证的代码。
saveSession
可选
Boolean
是否保存会话。默认为 true。

1
supabase.auth.mfa.createChallengeAndVerify(
2
    factorId = "34e770dd-9ff9-416c-87fa-43b31d7ef225",
3
    code = "123456",
4
    saveSession = true // this is set to true by default, but you can set it to false if you want to handle the session yourself
5
)

取消注册因素

取消注册会删除一个 MFA 因素。用户必须具有 AAL2 身份验证级别才能取消注册已验证的因素。

参数

factorId
必需
字符串
您要取消注册的因素的 ID。

1
supabase.auth.mfa.unenroll(factorId = "34e770dd-9ff9-416c-87fa-43b31d7ef225")

获取身份验证器保证级别

身份验证器保证级别 (AAL) 是身份验证机制强度的度量。
在 Supabase 中，具有 aal1 的 AAL 指的是第一因素身份验证，例如电子邮件和密码或 OAuth 登录，而 aal2 指的是第二因素身份验证，例如基于时间的一次性密码 (TOTP)。
如果用户具有已验证的因素，则 next 字段将返回 AuthenticatorAssuranceLevel.AAL2，否则，它将返回 AuthenticatorAssuranceLevel.AAL1。

1
val (current, next) = supabase.auth.mfa.getAuthenticatorAssuranceLevel()

认证 Admin

supabase.auth.admin 命名空间下的任何方法都需要一个 service_role 密钥。
这些方法被认为是管理方法，应在受信任的服务器上调用。切勿在浏览器中公开你的 service_role 密钥。

1
val supabase = createSupabaseClient(
2
    supabaseUrl = "https://id.supabase.co",
3
    supabaseKey = "supabaseKey"
4
) {
5
    install(Auth) {
6
        minimalConfig() //disables session saving and auto-refreshing
7
    }
8
    // install other plugins (these will use the service role key)
9
}
10
supabase.auth.importAuthToken("service_role")
11
12
// Access auth admin api
13
val adminAuthClient = supabase.auth.admin

获取用户

根据用户的 ID 从数据库中获取用户对象。

retrieveUserById() 方法需要用户的 ID，该 ID 映射到 auth.users.id 列。

参数

uid
必需
字符串
您要检索的用户的 ID。

1
val user = supabase.auth.admin.retrieveUserById(uid = "f2a0b0a0-6b1a-4b7a-8f1a-4b7a6b1a8f1a")

列出所有用户

检索用户列表。

默认情况下，每页返回 50 个用户。

参数

page
可选
Int
要检索的页码。
perPage
可选
Int
每页要检索的用户数。

1
val users = supabase.auth.admin.retrieveUsers()

创建用户

创建一个新用户。

要确认用户的电子邮件地址或电话号码，请将 autoConfirm 设置为 true。两个参数都默认为 false。

参数

builder
必需
AdminUserBuilder.Email.() -> Unit 或 AdminUserBuilder.Phone.() -> Unit
创建新用户的构建器。

1
val userWithEmail = supabase.auth.admin.createUserWithEmail {
2
    email = "example@email.com"
3
    password = "secretpassword"
4
    userMetadata {
5
        put("name", "John")
6
    }
7
}

删除用户

从数据库中删除用户。

deleteUser() 方法需要用户的 ID，它映射到 auth.users.id 列。

参数

uid
必需
字符串
您要删除的用户的 ID。

1
supabase.auth.admin.deleteUser(uid = "uid")

发送电子邮件邀请链接

向用户的电子邮件地址发送邀请链接。

参数

email
必需
字符串
要发送邀请的电子邮件。
redirectTo
可选
字符串
要使用的重定向 URL。如果您没有指定此 URL，将使用特定于平台的 URL，例如 Android 上的深层链接。
data
可选
JsonObject
使用自定义数据创建用户。

1
supabase.auth.admin.inviteUserByEmail(
2
    email = "example@email.com",
3
    //optional:
4
    redirectTo = "https://example.com/redirect",
5
    data = buildJsonObject {
6
        put("custom", "value")
7
    }
8
)

生成电子邮件链接

生成电子邮件链接和 OTP。这不会向最终用户发送链接或 OTP。此函数用于自定义管理员功能。

参数

type
必需
LinkType<C>
要生成的链接类型，例如 LinkType.Signup。
redirectTo
可选
字符串
要使用的重定向 URL。如果您没有指定此 URL，将使用特定于平台的 URL，例如 Android 上的深层链接。
config
可选
C.() -> Unit
创建新链接的构建器。

更新用户

更新用户数据。

参数

uid
必需
字符串
您要更新的用户的 ID。
builder
必需
AdminUserUpdateBuilder.() -> Unit
更新用户的构建器。

1
supabase.auth.admin.updateUserById(uid = "id") {
2
    email = "example@email.com"
3
}

删除用户的因素

删除用户的一个因素。如果删除的因素已验证，这将使用户退出所有活动会话。

参数

uid
必需
字符串
您要删除因素的用户的 ID。
factorId
必需
字符串
您要删除的因素的 ID。

1
supabase.auth.admin.deleteFactor(uid = "id", factorId = "factor_id")

调用 Supabase 边缘函数。

调用 Supabase 函数。请参阅指南以了解有关编写函数的详细信息。

在具有参数的函数中调用函数时，您必须在函数参数中提供一个可序列化的值。
需要 Authorization 标头。

参数

function
必需
字符串
要调用的函数的名称。
body
可选
T
与请求一起发送的正文。T 可以是任何可序列化的类型。
region
可选
FunctionRegion
调用函数的区域。默认为 Functions.Config#defaultRegion。
headers
可选
标头
与请求一起发送的标头。

1
val response = supabase.functions.invoke("function_name")
2
3
// Decode the response body to a serializable class
4
val data = response.body<FunctionResponse>()

监听数据库变更

将来自您表格的实时数据作为 Flow 返回。

默认情况下，新表格的实时功能已禁用。您可以通过管理复制来启用它。
selectAsFlow 和 selectSingleValueAsFlow 将发出初始数据，然后监听更改。
接收一个 filter 参数来过滤数据，以及一个 primaryKey 参数来通过主键缓存数据。
此方法需要安装 Realtime 和 Postgrest 插件。
类型参数 T 必须是一个可序列化的类。
如果您想更多地控制实时更新，可以使用 Realtime 插件直接使用。

参数

primaryKey
必需
KProperty1<Data, Value> 或 PrimaryKey<Data>
用于缓存数据的键。可以是属性引用或自定义主键。
channelName
可选
字符串
用于实时更新的通道名称。如果为 null，将使用格式为 "schema:table:id" 的通道名称
filter
可选
PostgrestFilterBuilder.() -> Unit 或 FilterOperation
应用于数据的过滤器。

1
val flow: Flow<List<Country>> = supabase.from("countries").selectAsFlow(Country::id)
2
flow.collect {
3
    for (country in it) {
4
        println(country.name)
5
    }
6
}

订阅频道

订阅数据库中的实时更改。

默认情况下，新项目的实时功能已禁用，以提高数据库性能和安全性。您可以通过管理复制来启用它。
如果您想接收更新和删除的“先前”数据，则需要将 REPLICA IDENTITY 设置为 FULL，如下所示：ALTER TABLE your_table REPLICA IDENTITY FULL;
在使用具有泛型类型的方法（如 track、broadcast 或 broadcastFlow）时，您必须提供一个可序列化的类作为类型参数。
Presence、Broadcast 和 Database 更新通过 Flow 发送

1
@Serializable
2
data class Message(val content: String, val sender: String)
3
4
val channel = supabase.channel("channelId") {
5
    // optional config
6
}
7
8
val broadcastFlow = channel.broadcastFlow<Message>(event = "message")
9
10
// Collect the flow
11
broadcastFlow.onEach { // it: Message
12
    println(it)
13
}.launchIn(coroutineScope) // launch a new coroutine to collect the flow
14
15
channel.subscribe(blockUntilSubscribed = true)

取消订阅频道

取消订阅并从实时客户端中删除实时通道。

删除通道是维护项目实时服务性能以及数据库性能的好方法，尤其是在监听 Postgres 更改时。
Supabase 会在客户端断开连接 30 秒后自动处理清理，但未使用的通道可能会导致更多客户端同时订阅时性能下降。
如果您删除了所有通道，客户端将自动断开与实时 websocket 的连接。这可以在实时配置中通过将 disconnectOnNoSubscriptions 设置为 false 来禁用。

1
val channel = supabase.channel("channelId") {
2
    //optional config
3
}
4
//...
5
supabase.realtime.removeChannel(channel)

取消订阅所有频道

取消订阅并从实时客户端删除所有实时通道。

删除频道是维护项目实时服务性能以及数据库性能的好方法（如果你正在侦听 Postgres 更改）。Supabase 会在客户端断开连接 30 秒后自动处理清理，但未使用的频道可能会导致更多客户端同时订阅而导致性能下降。
如果您删除了所有通道，客户端将自动断开与实时 websocket 的连接。这可以在实时配置中通过将 disconnectOnNoSubscriptions 设置为 false 来禁用。

1
supabase.realtime.removeAllChannels()

获取所有频道

返回所有实时通道。

1
val channels = supabase.realtime.subscriptions.entries

广播消息

向连接到通道的所有客户端广播消息。

使用 REST 时，您无需订阅通道

1
val channel = supabase.channel("room1")
2
channel.subscribe(blockUntilSubscribed = true)
3
channel.broadcast("cursor-pos", message = buildJsonObject {
4
  put("x", 10)
5
  put("y", 20)
6
})

文件存储

本节包含处理文件存储桶的方法。

列出所有存储桶

所需的 RLS 策略权限
- buckets 表权限：select
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

1
val buckets = supabase.storage.retrieveBuckets()

检索存储桶

所需的 RLS 策略权限
- buckets 表权限：select
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

1
val bucket = supabase.storage.retrieveBucketById(bucketId = "avatars")

创建存储桶

所需的 RLS 策略权限
- buckets 表权限：insert
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

参数

id
必需
字符串
您要创建的存储桶的 ID。
builder
可选
BucketBuilder.() -> Unit
创建新存储桶的构建器。

1
supabase.storage.createBucket(id = "icons") {
2
    public = true
3
    fileSizeLimit = 5.megabytes
4
}

清空存储桶

所需的 RLS 策略权限
- buckets 表权限：select
- objects 表权限：select 和 delete
请参阅存储指南，了解访问控制的工作方式

参数

bucketId
必需
字符串
您要清空的存储桶的 ID。

1
supabase.storage.emptyBucket(bucketId = "icons")

更新存储桶

所需的 RLS 策略权限
- buckets 表权限：select 和 update
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

参数

id
必需
字符串
您要创建的存储桶的 ID。
builder
可选
BucketBuilder.() -> Unit
创建新存储桶的构建器。

1
supabase.storage.updateBucket("cards") {
2
    public = false
3
    fileSizeLimit = 20.megabytes
4
    allowedMimeTypes(ContentType.Image.PNG, ContentType.Image.JPEG)
5
}

删除存储桶

所需的 RLS 策略权限
- buckets 表权限：select 和 delete
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

参数

bucketId
必需
字符串
您要删除的存储桶的 ID。

1
supabase.storage.deleteBucket(bucketId = "icons")

上传文件

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：insert
请参阅存储指南，了解访问控制的工作方式
可恢复上传默认使用 Disk 缓存来存储上传 URL。您可以通过更改 Auth 配置中的 resumable.cache 属性来自定义它。

参数

path
必需
字符串
您要上传的文件的路径。
data
必需
ByteArray
您要上传的文件的数据。
options
可选
UploadOptionBuilder.() -> Unit
上传的附加选项。

1
val bucket = supabase.storage.from("avatars")
2
bucket.upload("myIcon.png", byteArray) {
3
    upsert = false
4
}
5
//on JVM you can use java.io.File
6
bucket.upload("myIcon.png", file) {
7
    upsert = false
8
}

替换现有文件

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：update 和 select
请参阅存储指南，了解访问控制的工作方式

参数

path
必需
字符串
您要上传的文件的路径。
data
必需
ByteArray
您要上传的文件的数据。
options
可选
UploadOptionBuilder.() -> Unit
上传的附加选项。

1
val bucket = supabase.storage.from("avatars")
2
bucket.update("myIcon.png", byteArray) {
3
    upsert = false
4
}
5
//on JVM you can use java.io.File
6
bucket.update("myIcon.png", file) {
7
    upsert = false
8
}

移动现有文件

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：update 和 select
请参阅存储指南，了解访问控制的工作方式

参数

from
必需
字符串
您要移动的文件的路径。
to
必需
字符串
文件的新的路径。
destinationBucket
可选
字符串
文件的目标存储桶。

1
val bucket = supabase.storage.from("avatars")
2
bucket.move("icon1.png", "icon2.png")

复制现有文件

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：insert 和 select
请参阅存储指南，了解访问控制的工作方式

参数

from
必需
字符串
您要复制的文件的路径。
to
必需
字符串
文件的新的路径。
destinationBucket
可选
字符串
文件的目标存储桶。

1
supabase.storage.from("test").copy(from = "avatar.png", to = "avatar2.png")

创建签名 URL

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：select
请参阅存储指南，了解访问控制的工作方式

参数

path
必需
字符串
您要为其创建签名 URL 的文件的路径。
expiresIn
必需
Duration
签名 URL 有效的持续时间。
builder
可选
ImageTransformation.() -> Unit
应用于图像的转换。

1
val bucket = supabase.storage.from("avatars")
2
val url = bucket.createSignedUrl(path = "icon.png", expiresIn = 3.minutes)

创建签名 URL

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：select
请参阅存储指南，了解访问控制的工作方式

参数

expiresIn
必需
Duration
签名 URL 有效的持续时间。
paths
必需
vararg String
您要为其创建签名 URL 的文件的路径。

1
val urls = supabase.storage.from("avatars").createSignedUrls(20.minutes, "avata1.jpg", "avatar2.jpg")

创建签名上传 URL

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：insert
请参阅存储指南，了解访问控制的工作方式

参数

path
必需
字符串
您要上传的文件的路径。
upsert
可选
Boolean
如果文件已存在，是否覆盖该文件。

1
val url = supabase.storage.from("avatars").createSignedUploadUrl("avatar.png")

上传到签名 URL

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

参数

path
必需
字符串
您要上传的文件的路径。
token
必需
字符串
您从 createSignedUploadUrl 接收到的令牌。
data
可选
ByteArray
您要上传的文件的数据。
options
可选
UploadOptionBuilder.() -> Unit
上传的附加选项。

1
supabase.storage.from("avatars").uploadToSignedUrl(path = "avatar.jpg", token = "token-from-createSignedUploadUrl", data = bytes)
2
//or on JVM:
3
supabase.storage.from("avatars").uploadToSignedUrl(path = "avatar.jpg", token = "token-from-createSignedUploadUrl", file = File("avatar.jpg"))

检索公共 URL

存储桶需要设置为公共，可以通过 updateBucket() 或通过转到 Storage 在 supabase.com/dashboard，单击存储桶上的溢出菜单并选择“设为公共”来完成。
所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

参数

path
必需
字符串
您要获取公共 URL 的文件的路径。

1
val url = supabase.storage.from("public-bucket").publicUrl("folder/avatar1.png")

下载文件

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：select
请参阅存储指南，了解访问控制的工作方式

参数

path
必需
字符串
您要下载的文件的路径。
options
可选
DownloadOptionBuilder.() -> Unit
下载的附加选项。

1
val bucket = supabase.storage.from("avatars")
2
val bytes = bucket.downloadAuthenticated("test.png")
3
//or on JVM:
4
bucket.downloadAuthenticatedTo("test.png", File("test.png"))

删除存储桶中的文件

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：delete 和 select
请参阅存储指南，了解访问控制的工作方式

参数

paths
必需
vararg String
您要删除的文件的路径。

1
val bucket = supabase.storage.from("avatars")
2
bucket.delete("test.png", "test2.png")

列出存储桶中的所有文件

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：select
请参阅存储指南，了解访问控制的工作方式

1
val bucket = supabase.storage.from("avatars")
2
val files = bucket.list()