postgrest-go 的使用

47 min read

主要类型及方法

1. Client

Client 类型是与 PostgREST 实例交互的核心。

  • NewClient(rawURL string, schema string, headers map[string]string) *Client

    • 创建一个新的 Client 实例，连接到指定的 PostgREST URL。

  • ChangeSchema(schema string) *Client

    • 修改客户端的 schema，用于后续的请求。

  • From(table string) *QueryBuilder

    • 设置要查询的表，返回一个 QueryBuilder 实例以构建查询。

  • Ping() bool

    • 检查客户端是否能够成功连接到 PostgREST 实例。

  • Rpc(name string, count string, rpcBody interface{}) string

    • 执行一个 Postgres 函数（RPC），返回结果作为字符串。

  • SetApiKey(apiKey string) *Client

    • 设置 API 密钥，用于后续的请求头。

  • SetAuthToken(authToken string) *Client

    • 设置授权令牌，用于后续的请求头。

2. QueryBuilder

QueryBuilder 用于构建和执行数据库查询。

  • Select(columns string, count string, head bool) *FilterBuilder

    • 执行选择操作，返回一个 FilterBuilder 以添加过滤条件。

  • Insert(value interface{}, upsert bool, onConflict string, returning string, count string) *FilterBuilder

    • 执行插入操作，可以选择是否执行 upsert。

  • Update(value interface{}, returning string, count string) *FilterBuilder

    • 执行更新操作。

  • Delete(returning string, count string) *FilterBuilder

    • 执行删除操作。

  • Upsert(value interface{}, onConflict string, returning string, count string) *FilterBuilder

    • 执行 upsert 操作（插入或更新）。

  • Execute() ([]byte, int64, error)

    • 执行构建的查询，返回结果的字节切片。

  • ExecuteString() (string, int64, error)

    • 执行查询，返回结果的 JSON 字符串。

  • ExecuteTo(to interface{}) (int64, error)

    • 执行查询，并将结果编码到提供的接口中（通常是切片的引用）。

3. FilterBuilder

FilterBuilder 用于在查询中添加过滤条件。

  • 过滤条件方法

    • Filter(column string, operator string, value string) *FilterBuilder
      • 添加一个自定义过滤条件。
    • Eq(column string, value string) *FilterBuilder
      • 添加等于过滤条件。
    • Neq(column string, value string) *FilterBuilder
      • 添加不等于过滤条件。
    • Gt(column string, value string) *FilterBuilder
      • 添加大于过滤条件。
    • Gte(column string, value string) *FilterBuilder
      • 添加大于等于过滤条件。
    • Lt(column string, value string) *FilterBuilder
      • 添加小于过滤条件。
    • Lte(column string, value string) *FilterBuilder
      • 添加小于等于过滤条件。
    • Like(column string, value string) *FilterBuilder
      • 添加 LIKE 过滤条件。
    • Ilike(column string, value string) *FilterBuilder
      • 添加不区分大小写的 LIKE 过滤条件。
    • In(column string, values []string) *FilterBuilder
      • 添加 IN 过滤条件。
    • Contains(column string, value []string) *FilterBuilder
      • 添加包含过滤条件。
    • ContainedBy(column string, value []string) *FilterBuilder
      • 添加被包含过滤条件。
    • Overlaps(column string, value []string) *FilterBuilder
      • 添加重叠过滤条件。
    • Is(column string, value string) *FilterBuilder
      • 添加 IS 过滤条件（如 IS NULL）。
    • Match(userQuery map[string]string) *FilterBuilder
      • 添加多个匹配条件。

  • 逻辑组合方法

    • And(filters string, foreignTable string) *FilterBuilder
      • 使用 AND 组合多个过滤条件。
    • Or(filters string, foreignTable string) *FilterBuilder
      • 使用 OR 组合多个过滤条件。
    • Not(column string, operator string, value string) *FilterBuilder
      • 添加 NOT 过滤条件。

  • 其他方法

    • Limit(count int, foreignTable string) *FilterBuilder
      • 限制结果数量。
    • Range(from int, to int, foreignTable string) *FilterBuilder
      • 限定结果范围。
    • RangeGt(column string, value string) *FilterBuilder
      • 添加范围大于条件。
    • RangeGte(column string, value string) *FilterBuilder
      • 添加范围大于等于条件。
    • RangeLt(column string, value string) *FilterBuilder
      • 添加范围小于条件。
    • RangeLte(column string, value string) *FilterBuilder
      • 添加范围小于等于条件。
    • RangeAdjacent(column string, value string) *FilterBuilder
      • 添加相邻范围条件。
    • Order(column string, opts *OrderOpts) *FilterBuilder
      • 添加排序条件。
    • Single() *FilterBuilder
      • 限定结果为单一记录。
    • TextSearch(column string, userQuery string, config string, tsType string) *FilterBuilder
      • 添加全文搜索条件。

  • 执行方法

    • Execute() ([]byte, int64, error)
      • 执行过滤后的查询，返回结果的字节切片。
    • ExecuteString() (string, int64, error)
      • 执行查询，返回结果的 JSON 字符串。
    • ExecuteTo(to interface{}) (countType, error)
      • 执行查询，并将结果编码到提供的接口中。

4. 其他类型

  • ExecuteError

    • 结构体，表示 PostgREST 的错误响应格式，包含 Hint、Details、Code 和 Message 字段。

  • OrderOpts

    • 结构体，描述排序选项，包括 Ascending（升序）、NullsFirst（空值优先）和 ForeignTable（外表）字段。
    • DefaultOrderOpts
      • 默认的排序选项实例。

使用示例

以下是一个简单的使用示例，展示如何使用 postgrest-go 执行一个 RPC 调用：

package main

import (
	"fmt"
	"github.com/supabase-community/postgrest-go"
)

func main() {
	client := postgrest.NewClient("http://localhost:3000/rest/v1", "", nil)
	if client.ClientError != nil {
		panic(client.ClientError)
	}

	result := client.Rpc("add_them", "", map[string]int{"a": 12, "b": 3})
	if client.ClientError != nil {
		panic(client.ClientError)
	}

	fmt.Println(result)
}