Postgrest Go

https://github.com/supabase-community/postgrest-go
Admin
Postgrest Go is a Golang client for PostgREST, aiming to provide an ORM-like restful interface for...
Tokens:42,215
Snippets:301
Trust Score:9.7
License:Apache-2.0
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install PostgREST Go Client

Source: https://github.com/supabase-community/postgrest-go/blob/main/docs/book/print.html

Use 'go get' to install the PostgREST Go client library.

```bash
go get github.com/supabase-community/postgrest-go
```

--------------------------------

### Start Query Builder

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Initializes a query builder for a specified table or view. Used to construct and execute queries.

```go
// From sets the table or view to query from
func (c *Client) From(relation string) *QueryBuilder[map[string]interface{}] {
        return NewQueryBuilder[map[string]interface{}](c, relation)
}
```

--------------------------------

### Generate EXPLAIN Plan with Options

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Use the Explain method with ExplainOptions to get the EXPLAIN plan for a query. It constructs the 'Accept' header with the specified format and options.

```go
// Explain returns data as the EXPLAIN plan for the query
func (t *TransformBuilder[T]) Explain(opts *ExplainOptions) *Builder[interface{}] {
        if opts == nil {
                opts = &ExplainOptions{Format: "text"}
        }

        var options []string
        if opts.Analyze {
                options = append(options, "analyze")
        }
        if opts.Verbose {
                options = append(options, "verbose")
        }
        if opts.Settings {
                options = append(options, "settings")
        }
        if opts.Buffers {
                options = append(options, "buffers")
        }
        if opts.WAL {
                options = append(options, "wal")
        }

        optionsStr := strings.Join(options, "|")

        forMediatype := t.headers.Get("Accept")
        if forMediatype == "" {
                forMediatype = "application/json"
        }

        acceptValue := fmt.Sprintf("application/vnd.pgrst.plan+%s; for=\"%s\"; options=%s;", opts.Format, forMediatype, optionsStr)
        t.headers.Set("Accept", acceptValue)

        return &Builder[interface{} ]{
                method:             t.method,
                url:                t.url,
                headers:            t.headers,
                schema:             t.schema,
                body:               t.body,
                shouldThrowOnError: t.shouldThrowOnError,
                signal:             t.signal,
                client:             t.client,
                isMaybeSingle:      t.isMaybeSingle,
        }
}
```

--------------------------------

### Start Table Query

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Returns a QueryBuilder for the given table or view, which exposes Select, Insert, Update, Upsert, and Delete methods.

```go
qb := client.From("users") // *QueryBuilder[map[string]interface{}]
```

--------------------------------

### Initialize PostgREST Go Client Builder

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Creates a new `Builder` instance for PostgREST queries. It initializes the builder with client-specific headers and any additional headers provided in options. Use this to start constructing a query.

```go
package postgrest

import (
        "bytes"
        "context"
        "encoding/json"
        "fmt"
        "io"
        "net/http"
        "net/url"
        "reflect"
        "strconv"
        "strings"
)

// Builder is the base builder for PostgREST queries
// Similar to PostgrestBuilder in postgrest-js
type Builder[T any] struct {
        method             string
        url                *url.URL
        headers            http.Header
        schema             string
        body               interface{}
        shouldThrowOnError bool
        signal             context.Context
        client             *Client
        isMaybeSingle      bool
}

// NewBuilder creates a new Builder instance
func NewBuilder[T any](client *Client, method string, url *url.URL, opts *BuilderOptions) *Builder[T] {
        if opts == nil {
                opts = &BuilderOptions{}
        }

        b := &Builder[T]{
                method:             method,
                url:                url,
                headers:            make(http.Header),
                schema:             opts.Schema,
                body:               opts.Body,
                shouldThrowOnError: opts.ShouldThrowOnError,
                signal:             opts.Signal,
                client:             client,
                isMaybeSingle:      opts.IsMaybeSingle,
        }

        // Copy headers from client
        if client != nil && client.Transport != nil {
                client.Transport.mu.RLock()
                for key, values := range client.Transport.header {
                        for _, val := range values {
                                b.headers.Add(key, val)
                        }
                }
                client.Transport.mu.RUnlock()
        }

        // Copy additional headers
        if opts.Headers != nil {
                for key, values := range opts.Headers {
                        for _, val := range values {
                                b.headers.Add(key, val)
                        }
                }
        }

        return b
}

// BuilderOptions contains options for creating a Builder
type BuilderOptions struct {
        Headers            http.Header
        Schema             string
        Body               interface{}
        ShouldThrowOnError bool
        Signal             context.Context
        IsMaybeSingle      bool
}
```

--------------------------------

### Execute Query and Get Response

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Executes the constructed query and returns the raw Postgrest response, including data and potential errors.

```go
// Execute executes the query and returns the response
func (f *FilterBuilder[T]) Execute(ctx context.Context) (*PostgrestResponse[T], error) {
        return f.Builder.Execute(ctx)
}
```

--------------------------------

### Select Data with Filters and Options

Source: https://github.com/supabase-community/postgrest-go/blob/main/README.md

Example of selecting specific columns from a table with filtering, limiting, and ordering. The 'Count: "exact"' option requests the exact number of matching rows.

```go
// Select with filters
opts := &postgrest.SelectOptions{Count: "exact"}
response, err := client.
	From("users").
	Select("id, name, email", opts).
	Eq("status", "active").
	Limit(10, nil).
	Order("name", &postgrest.OrderOptions{Ascending: true}).
	Execute(context.Background())
```

--------------------------------

### Range Method for Pagination

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Paginate results by specifying a start and end index (inclusive). This translates to `offset` and `limit` query parameters.

```go
ctx := context.Background()

// Page 2 of 10 items per page (items 10–19)
resp, err := client.From("products").
	Select("id, name, price", &postgrest.SelectOptions{Count: "exact"}).
	Range(10, 19, nil).
	Execute(ctx)
if err != nil {
	panic(err)
}
if resp.Count != nil {
	fmt.Printf("Showing items 10-19 of %d total\n", *resp.Count)
}
```

--------------------------------

### MaybeSingle()

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Configures the request to return data as a single object or null. The 'Accept' header is set to 'application/json' for GET requests and 'application/vnd.pgrst.object+json' for other methods.

```APIDOC
## MaybeSingle()

### Description
Returns data as a single object or null.

### Method
Sets the 'Accept' header based on the request method: 'application/json' for GET, 'application/vnd.pgrst.object+json' otherwise.

### Endpoint
N/A (Method modifies request headers)

### Parameters
None

### Request Example
```go
// Assuming 'builder' is an instance of TransformBuilder
builder.MaybeSingle()
```

### Response
Modifies the 'Accept' header for the request.
```

--------------------------------

### Retrieve query execution plan with Explain()

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Use `Explain()` to get the PostgreSQL EXPLAIN output for a query, aiding performance debugging. It accepts `ExplainOptions` for `Analyze`, `Verbose`, `Buffers`, `WAL`, `Settings`, and `Format`.

```go
ctx := context.Background()

resp, err := client.From("orders").
	Select("*", nil).
	Eq("status", "pending").
	Explain(&postgrest.ExplainOptions{
		Analyze: true,
		Verbose: true,
		Format:  "text",
	}).
	Execute(ctx)
if err != nil {
	panic(err)
}
fmt.Println(resp.Data)
```

--------------------------------

### Run Go Integration Tests with Docker Compose

Source: https://github.com/supabase-community/postgrest-go/blob/main/README.md

Instructions for running integration tests using Docker Compose to manage PostgreSQL and PostgREST services. This involves starting services, setting environment variables, running tests, and then stopping services.

```bash
docker-compose up -d
export POSTGREST_URL=http://localhost:3000
export USE_TESTCONTAINERS=false
go test -v -run TestIntegration
docker-compose down
```

--------------------------------

### Get Default PostgREST Headers

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Returns a map containing the default headers required for PostgREST requests, including the client version.

```go
package postgrest

import "fmt"

// DefaultHeaders returns the default headers for PostgREST requests
func DefaultHeaders() map[string]string {
        return map[string]string{
                "X-Client-Info": fmt.Sprintf("postgrest-go/%s", version),
        }
}
```

--------------------------------

### Range Pagination

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Details how to paginate results using the `Range` method, which specifies a start and end index (inclusive) for rows.

```APIDOC
## Range

### Description
Fetches rows within a specified index range (inclusive), translating to `offset` and `limit` query parameters.

### Method
Chained method on `*FilterBuilder[T]`.

### Parameters
- **from** (int) - The starting index of the range (0-based).
- **to** (int) - The ending index of the range (inclusive).
- **options** (*postgrest.RangeOptions) - Optional parameters for the range.

### Example
```go
ctx := context.Background()

// Page 2 of 10 items per page (items 10–19)
resp, err := client.From("products").
	Select("id, name, price", &postgrest.SelectOptions{Count: "exact"}).
	Range(10, 19, nil).
	Execute(ctx)
if err != nil {
	panic(err)
}
if resp.Count != nil {
	fmt.Printf("Showing items 10-19 of %d total\n", *resp.Count)
}
```
```

--------------------------------

### Set Response to Maybe Single Object

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Use MaybeSingle to retrieve data as a single object or null. The 'Accept' header is set to 'application/json' for GET requests and 'application/vnd.pgrst.object+json' for others.

```go
func (t *TransformBuilder[T]) MaybeSingle() *Builder[T] {
        if t.method == "GET" {
                t.headers.Set("Accept", "application/json")
        } else {
                t.headers.Set("Accept", "application/vnd.pgrst.object+json")
        }
        t.isMaybeSingle = true
        return t.Builder
}
```

--------------------------------

### QueryBuilder.Select - SELECT query

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Performs an HTTP GET request to select columns from a table. Supports specifying columns and controlling row count mode.

```go
import (
	"context"
	"encoding/json"
	"fmt"
	postgrest "github.com/supabase-community/postgrest-go"
)

ctx := context.Background()
client := postgrest.NewClient("http://localhost:3000", "public", nil)

// Select all columns, with exact count
resp, err := client.From("users").
	Select("id, name, email", &postgrest.SelectOptions{Count: "exact"}).
	Execute(ctx)
if err != nil {
	panic(err)
}
if resp.Error != nil {
	fmt.Printf("DB error %s: %s\n", resp.Error.Code, resp.Error.Message)
	return
}

data, _ := json.MarshalIndent(resp.Data, "", "  ")
fmt.Println(string(data))
// resp.Count contains the total row count when Count is set
if resp.Count != nil {
	fmt.Printf("Total rows: %d\n", *resp.Count)
}
// Expected output:
// [{"email":"alice@example.com","id":1,"name":"Alice"}, ...]
// Total rows: 42

```

--------------------------------

### Health Check PostgREST

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Issues a GET to the base URL to check if PostgREST is reachable. Returns bool or an error.

```go
import "context"

client := postgrest.NewClient("http://localhost:3000", "public", nil)

if !client.Ping() {
	fmt.Printf("PostgREST unreachable: %v\n", client.ClientError)
} else {
	fmt.Println("PostgREST is up")
}

// Or with explicit error:
if err := client.PingWithError(); err != nil {
	panic(err)
}
```

--------------------------------

### Basic Postgrest GO Client Usage

Source: https://github.com/supabase-community/postgrest-go/blob/main/README.md

Demonstrates creating a client, selecting all data from a table, and handling potential errors. Ensure the PostgREST server is running at the specified URL.

```go
package main

import (
	"context"
	"encoding/json"
	"fmt"

	"github.com/supabase-community/postgrest-go"
)

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

	// Select data
	response, err := client.From("users").Select("*", nil).Execute(context.Background())
	if err != nil {
		panic(err)
	}

	if response.Error != nil {
		panic(response.Error)
	}

	// Print results
	data, _ := json.Marshal(response.Data)
	fmt.Println(string(data))
}
```

--------------------------------

### Explain()

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Returns the EXPLAIN plan for the query with specified options. The 'Accept' header is set to 'application/vnd.pgrst.plan+<format>; for="<mediatype>"; options=<options>;'.

```APIDOC
## Explain(opts *ExplainOptions)

### Description
Returns data as the EXPLAIN plan for the query.

### Method
Sets the 'Accept' header to 'application/vnd.pgrst.plan+<format>; for="<mediatype>"; options=<options>;'.

### Endpoint
N/A (Method modifies request headers)

### Parameters
#### Request Body
- **opts** (*ExplainOptions) - Required - Options for the EXPLAIN plan.
  - **Analyze** (bool) - Optional - If true, includes ANALYZE information.
  - **Verbose** (bool) - Optional - If true, includes verbose output.
  - **Settings** (bool) - Optional - If true, includes settings information.
  - **Buffers** (bool) - Optional - If true, includes buffer information.
  - **WAL** (bool) - Optional - If true, includes WAL information.
  - **Format** (string) - Optional - The format for the EXPLAIN plan ('text' or 'json'). Defaults to 'text'.

### Request Example
```go
// Assuming 'builder' is an instance of TransformBuilder
explainOpts := &ExplainOptions{Analyze: true, Verbose: true, Format: "json"}
builder.Explain(explainOpts)
```

### Response
Modifies the 'Accept' header for the request to include EXPLAIN plan details.
```

--------------------------------

### Initialize PostgREST Client and Make RPC Call

Source: https://github.com/supabase-community/postgrest-go/blob/main/docs/book/print.html

Demonstrates how to initialize the PostgREST client and make a Remote Procedure Call (RPC). Ensure to handle potential client errors after initialization and RPC calls.

```go
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)
}
```

--------------------------------

### Rpc

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Calls a PostgREST RPC endpoint to execute a PostgreSQL function. Supports both POST with JSON body and GET with query parameters.

```APIDOC
## Call PostgreSQL Function (RPC)

### Description
Calls a PostgREST `/rpc/<fn>` endpoint. By default uses POST with a JSON body; set `opts.Get = true` to use GET with query parameters (for read-only functions). `opts.Head = true` uses HEAD.

### Method
POST or GET

### Endpoint
`/rpc/your_function_name`

### Parameters
#### Path Parameters
- **fn** (string) - Required - The name of the PostgreSQL function to call.

#### Request Body (for POST)
- **parameters** (object) - Optional - A JSON object containing the function's arguments.

#### Query Parameters (for GET)
- **parameters** (object) - Optional - Function arguments passed as query parameters.

#### Options (RpcOptions)
- **Get** (boolean) - Optional - Use GET method instead of POST.
- **Head** (boolean) - Optional - Use HEAD method.
- **Count** (string) - Optional - Row count mode: `"exact"`, `"planned"`, `"estimated"`.

### Request Example (POST)
```go
resp, err := client.
	Rpc("calculate_distance", map[string]interface{}{
		"origin_city": "New York",
		"dest_city":   "Los Angeles",
	}, &postgrest.RpcOptions{Count: "exact"}).
	Execute(ctx)
```

### Request Example (GET)
```go
resp, err = client.
	Rpc("get_active_user_count", nil, &postgrest.RpcOptions{Get: true}).
	Execute(ctx)
```

### Response
#### Success Response (200)
- **data** (any) - The result of the function call, typically JSON.
- **count** (integer) - Total row count (if `Count` option is set).
```

--------------------------------

### Apply Range to Query

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Adds a range constraint to the query, typically used for pagination. Specify the start and end row numbers.

```go
func (f *FilterBuilder[T]) Range(from, to int, opts *RangeOptions) *TransformBuilder[T] {
        tb := &TransformBuilder[T]{Builder: f.Builder}
        return tb.Range(from, to, opts)
}
```

--------------------------------

### Select Schema for Queries

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Creates a new client instance configured for a specific schema, used for subsequent queries or RPC calls. Updates schema headers accordingly.

```go
// Schema selects a schema to query or perform an function (rpc) call
func (c *Client) Schema(schema string) *Client {
        newClient := &Client{
                session:    c.session,
                Transport:  c.Transport,
                schemaName: schema,
        }

        // Update schema headers
        newClient.Transport.SetHeaders(map[string]string{
                "Accept-Profile":  schema,
                "Content-Profile": schema,
        })

        return newClient
}
```

--------------------------------

### Client Methods

Source: https://github.com/supabase-community/postgrest-go/blob/main/README.md

Methods for initializing and configuring the PostgREST client.

```APIDOC
## Client Methods

- `NewClient(url, schema, headers)` - Create a new client
- `From(table)` - Start a query on a table
- `Rpc(function, args, opts)` - Call a PostgreSQL function
- `Schema(schema)` - Switch to a different schema
- `SetApiKey(key)` - Set API key header
- `SetAuthToken(token)` - Set authorization token
- `ChangeSchema(schema)` - Change schema for subsequent requests
```

--------------------------------

### Configure Explain Options

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

The ExplainOptions struct defines parameters for the EXPLAIN query, including analyze, verbose, settings, buffers, WAL, and format (text or json).

```go
// ExplainOptions contains options for explain
type ExplainOptions struct {
        Analyze  bool
        Verbose  bool
        Settings bool
        Buffers  bool
        WAL      bool
        Format   string // "text" or "json"
}
```

--------------------------------

### Create New PostgREST Client (Simplified)

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Constructs a new PostgREST client, returning a client with a ClientError if initialization fails. This provides a simpler interface for client creation when immediate error handling is not critical.

```go
// NewClient constructs a new client given a URL to a Postgrest instance.
func NewClient(rawURL, schema string, headers map[string]string) *Client {
        client, err := NewClientWithError(rawURL, schema, headers)
        if err != nil {
                return &Client{ClientError: err}
        }
        return client
}
```

--------------------------------

### Rpc

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Performs a function call (RPC) to the PostgREST server. Supports GET, HEAD, and POST methods, with options for query parameters and request body.

```APIDOC
## Rpc

### Description
Performs a function call (RPC) to the PostgREST server.

### Method
```go
func (c *Client) Rpc(fn string, args interface{}, opts *RpcOptions) *FilterBuilder[interface{}]
```

### Parameters
#### Path Parameters
- **fn** (string) - The name of the function to call.
- **args** (interface{}) - Arguments for the function. Can be a map for query parameters or a body for POST requests.
- **opts** (*RpcOptions) - Options for the RPC call, including `Head`, `Get`, and `Count`.

### RpcOptions
- **Head** (bool) - If true, uses the HEAD method.
- **Get** (bool) - If true, uses the GET method.
- **Count** (string) - Specifies the count type: "exact", "planned", or "estimated".
```

--------------------------------

### QueryBuilder.Select

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Performs an HTTP GET request to select columns from a table. Supports specifying columns, controlling HEAD requests, and row count modes.

```APIDOC
## SELECT Query

### Description
Performs an HTTP GET request to select columns from a table. `columns` is a comma-separated column list (or `"*"`). `SelectOptions` controls HEAD requests and row count mode (`"exact"`, `"planned"`, `"estimated"`).

### Method
GET

### Endpoint
`/your-table-name`

### Parameters
#### Query Parameters
- **columns** (string) - Required - Comma-separated list of columns to select, or `"*"` for all.
- **options** (SelectOptions) - Optional - Controls HEAD requests and row count mode.
  - **Count** (string) - Optional - Row count mode: `"exact"`, `"planned"`, `"estimated"`.

### Request Example
```go
resp, err := client.From("users").
	Select("id, name, email", &postgrest.SelectOptions{Count: "exact"}).
	Execute(ctx)
```

### Response
#### Success Response (200)
- **data** (array) - Array of selected rows.
- **count** (integer) - Total row count (if `Count` option is set).

#### Response Example
```json
[
  {"id": 1, "name": "Alice", "email": "alice@example.com"}
]
```
```json
{
  "example": "Total rows: 42"
}
```
```

--------------------------------

### Create PostgREST Client

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Creates a new Client connected to a PostgREST instance. Sets default headers. Returns a *Client with ClientError set on URL parse failure.

```go
package main

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

func main() {
	client := postgrest.NewClient(
		"http://localhost:3000",
		"public",
		map[string]string{
			"apikey": "your-api-key",
		},
	)
	if client.ClientError != nil {
		panic(client.ClientError)
	}
	fmt.Println("Client created successfully")
}
```

--------------------------------

### Run All Tests

Source: https://github.com/supabase-community/postgrest-go/blob/main/docs/book/print.html

Execute all tests for the PostgREST Go client using the 'go test' command. Tests can optionally run against a live PostgREST instance by setting environment variables.

```bash
go test ./...
```

--------------------------------

### Get a Single Row

Source: https://github.com/supabase-community/postgrest-go/blob/main/README.md

Retrieves a single row from the 'users' table where 'id' is 1. 'Limit(1, nil)' ensures only one row is fetched.

```go
// Get a single row
response, err := client.
	From("users").
	Select("*", nil).
	Eq("id", 1).
	Limit(1, nil).
	Single().
	Execute(context.Background())
```

--------------------------------

### Create a New QueryBuilder Instance

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Initializes a QueryBuilder for a specific relation. It sets up the base URL, headers, and schema for subsequent query operations.

```go
func NewQueryBuilder[T any](client *Client, relation string) *QueryBuilder[T] {
        baseURL := client.Transport.baseURL
        queryURL := baseURL.JoinPath(relation)

        headers := make(http.Header)
        if client.Transport != nil {
                client.Transport.mu.RLock()
                for key, values := range client.Transport.header {
                        for _, val := range values {
                                headers.Add(key, val)
                        }
                }
                client.Transport.mu.RUnlock()
        }

        return &QueryBuilder[T]{
                url:     queryURL,
                headers: headers,
                schema:  client.schemaName,
                client:  client,
        }
}
```

--------------------------------

### Switching Schemas

Source: https://github.com/supabase-community/postgrest-go/blob/main/README.md

Demonstrates how to switch the client's active schema to 'private' before executing a query against a table in that schema.

```go
// Switch to a different schema
client = client.Schema("private")
response, err := client.From("sensitive_data").Select("*", nil).Execute(context.Background())
```

--------------------------------

### Run Go Integration Tests with Existing Services

Source: https://github.com/supabase-community/postgrest-go/blob/main/README.md

Command to run integration tests against a manually configured PostgREST instance. Ensure the POSTGREST_URL environment variable is set correctly.

```bash
export POSTGREST_URL=http://localhost:3000
export USE_TESTCONTAINERS=false
go test -v -run TestIntegration
```

--------------------------------

### Get a Single Row or Null (MaybeSingle)

Source: https://github.com/supabase-community/postgrest-go/blob/main/README.md

Attempts to retrieve a single row where 'id' is 999. If no row is found, it returns nil without an error, useful for optional data retrieval.

```go
// Get a single row or null (maybeSingle)
response, err := client.
	From("users").
	Select("*", nil).
	Eq("id", 999).
	MaybeSingle().
	Execute(context.Background())
```

--------------------------------

### Rpc - Call a PostgreSQL function (RPC)

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Calls a PostgREST RPC endpoint. Supports POST with JSON body or GET with query parameters for read-only functions. HEAD requests are also supported.

```go
ctx := context.Background()

// POST-based RPC
resp, err := client.
	Rpc("calculate_distance", map[string]interface{}{
		"origin_city": "New York",
		"dest_city":   "Los Angeles",
	}, &postgrest.RpcOptions{Count: "exact"}).
	Execute(ctx)
if err != nil {
	panic(err)
}
data, _ := json.MarshalIndent(resp.Data, "", "  ")
fmt.Println(string(data))
// Expected: 2451.0 (miles)

// GET-based RPC (idempotent/read-only function)
resp, err = client.
	Rpc("get_active_user_count", nil, &postgrest.RpcOptions{Get: true}).
	Execute(ctx)

```

--------------------------------

### Return results as CSV with CSV()

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Use `CSV()` to set the `Accept` header to `text/csv`. The response `Data` will be a raw CSV string. This is useful for exporting data.

```go
ctx := context.Background()

resp, err := client.From("sales").
	Select("date, product, revenue", nil).
	Eq("year", 2024).
	Order("date", &postgrest.OrderOptions{Ascending: true}).
	CSV().
	Execute(ctx)
if err != nil {
	panic(err)
}
fmt.Println(resp.Data)
```

--------------------------------

### Perform a SELECT Query

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Constructs and prepares a SELECT query. Supports specifying columns and options like HEAD requests or count retrieval. Handles column name cleaning to avoid issues with quoted identifiers.

```go
func (q *QueryBuilder[T]) Select(columns string, opts *SelectOptions) *FilterBuilder[[]T] {
        if opts == nil {
                opts = &SelectOptions{}
        }

        method := "GET"
        if opts.Head {
                method = "HEAD"
        }

        // Remove whitespaces except when quoted
        quoted := false
        var cleanedColumns strings.Builder
        if columns == "" {
                cleanedColumns.WriteString("*")
        } else {
                for _, char := range columns {
                        if char == '"' {
                                quoted = !quoted
                        }
                        if char == ' ' && !quoted {
                                continue
                        }
                        cleanedColumns.WriteRune(char)
                }
        }

        query := q.url.Query()
        query.Set("select", cleanedColumns.String())
        q.url.RawQuery = query.Encode()

        if opts.Count != "" && (opts.Count == "exact" || opts.Count == "planned" || opts.Count == "estimated") {
                q.headers.Add("Prefer", fmt.Sprintf("count=%s", opts.Count))
        }

        builder := NewBuilder[[]T](q.client, method, q.url, &BuilderOptions{
                Headers: q.headers,
                Schema:  q.schema,
        })

        return &FilterBuilder[[]T]{Builder: builder}
}
```

--------------------------------

### Explain

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Retrieve the query execution plan. Returns the PostgreSQL EXPLAIN output for the query. `ExplainOptions` supports `Analyze`, `Verbose`, `Buffers`, `WAL`, `Settings`, and `Format`.

```APIDOC
## Explain — Retrieve the query execution plan

### Description
Returns the PostgreSQL EXPLAIN output for the query. Useful for performance debugging. `ExplainOptions` supports `Analyze`, `Verbose`, `Buffers`, `WAL`, `Settings`, and `Format` (`"text"` or `"json"`).

### Method
```go
ctx := context.Background()

resp, err := client.From("orders").
	Select("*", nil).
	Eq("status", "pending").
	Explain(&postgrest.ExplainOptions{
		Analyze: true,
		Verbose: true,
		Format:  "text",
	}).
	Execute(ctx)
if err != nil {
	panic(err)
}
fmt.Println(resp.Data)
// Expected: PostgreSQL EXPLAIN ANALYZE VERBOSE output as plain text
```
```

--------------------------------

### Match Multiple Columns

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Demonstrates how to match multiple columns simultaneously with specific values.

```APIDOC
## Match

### Description
Matches rows where multiple columns have specific values.

### Method
Chained filter method on `*FilterBuilder[T]`.

### Parameters
- **values** (map[string]interface{}) - A map where keys are column names and values are the desired values.

### Example
```go
ctx := context.Background()
resp, _ := client.From("users").
	Select("*", nil).
	Match(map[string]interface{}{"role": "admin", "status": "active"}).
	Execute(ctx)
```
```

--------------------------------

### Perform an INSERT Operation

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Prepares an INSERT query. Allows specifying insert options such as count retrieval and handling of default values.

```go
func (q *QueryBuilder[T]) Insert(values interface{}, opts *InsertOptions) *FilterBuilder[interface{}] {
        if opts == nil {
                opts = &InsertOptions{DefaultToNull: true}
        }

        method := "POST"

        headers := make(http.Header)
        for key, values := range q.headers {
                for _, val := range values {
                        headers.Add(key, val)
                }
        }

        if opts.Count != "" && (opts.Count == "exact" || opts.Count == "planned" || opts.Count == "estimated") {
                headers.Add("Prefer", fmt.Sprintf("count=%s", opts.Count))
        }
}
```

--------------------------------

### Execute HTTP Request with Context

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Constructs and executes an HTTP request using the provided context. Handles request creation, header setting, and initial error checking, including context cancellation.

```go
bodyBytes, err := json.Marshal(b.body)
if err != nil {
	return nil, fmt.Errorf("error marshaling body: %w", err)
}
bod yReader = bytes.NewBuffer(bodyBytes)
}

// Check if context is already canceled
if ctx.Err() != nil {
	return nil, ctx.Err()
}

// Create request
req, err := http.NewRequestWithContext(ctx, b.method, b.url.String(), bodyReader)
if err != nil {
	return nil, fmt.Errorf("error creating request: %w", err)
}

// Set headers
for key, values := range b.headers {
	for _, val := range values {
		req.Header.Add(key, val)
	}
}

// Execute request
resp, err := b.client.session.Do(req)
if err != nil {
	// Check if error is due to context cancellation
	if ctx.Err() != nil {
		return nil, ctx.Err()
	}
	if b.shouldThrowOnError {
		return nil, err
	}
	return &PostgrestResponse[T]{
		Error: NewPostgrestError(
			fmt.Sprintf("FetchError: %s", err.Error()),
			fmt.Sprintf("%v", err),
			"",
			"",
		),
		Data:       *new(T),
		Count:      nil,
		Status:     0,
		StatusText: "",
	}, nil
}
defer resp.Body.Close()
```

--------------------------------

### Switch Database Schema

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Query the specified schema using a new client or mutate the existing client to use a different schema for future requests.

```go
client := postgrest.NewClient("http://localhost:3000", "public", nil)

// Query the "private" schema (returns a new client, original unaffected)
privateClient := client.Schema("private")
resp, err := privateClient.From("secrets").Select("*", nil).Execute(ctx)

// Mutate the existing client to use a different schema for all future requests
client.ChangeSchema("analytics")
```

--------------------------------

### NewClient

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Creates a new PostgREST client instance connected to a PostgREST API server. It sets default headers and returns a *Client. The error, if any, is embedded in the returned client.

```APIDOC
## NewClient

### Description
Creates a new `Client` connected to a PostgREST instance. Sets default headers (`Accept`, `Content-Type`, schema profile headers, `X-Client-Info`). Returns a `*Client` with `ClientError` set on URL parse failure.

### Method
`postgrest.NewClient(baseURL string, schema string, headers map[string]string) *Client`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
package main

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

func main() {
	client := postgrest.NewClient(
		"http://localhost:3000",
		"public",
		map[string]string{
			"apikey": "your-api-key",
		},
	)
	if client.ClientError != nil {
		panic(client.ClientError)
	}
	fmt.Println("Client created successfully")
}
```

### Response
#### Success Response (200)
Returns a `*Client` object. Errors are stored in the `ClientError` field of the returned client.

#### Response Example
(No explicit response example, but the client object is returned)

### Error Handling
Errors during client creation (e.g., invalid URL) are stored in the `ClientError` field of the returned `*Client`.
```

--------------------------------

### Basic Filter Methods: Equality, Inequality, Numeric Comparisons

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Use these methods for standard filtering based on equality, inequality, and numeric ranges. They are chainable for complex queries.

```go
ctx := context.Background()

// Equality, inequality, numeric comparisons
resp, _ := client.From("products").
	Select("*", nil).
	Eq("category", "electronics").
	Neq("status", "discontinued").
	Gte("price", 10).
	Lte("price", 500).
	Execute(ctx)
```

--------------------------------

### Create Client with Explicit Error Return

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Identical to NewClient but returns (*Client, error) instead of embedding the error.

```go
client, err := postgrest.NewClientWithError(
	"http://localhost:3000",
	"public",
	map[string]string{"Authorization": "Bearer my-jwt-token"},
)
if err != nil {
	panic(err)
}
```

--------------------------------

### Run Go Integration Tests with Testcontainers

Source: https://github.com/supabase-community/postgrest-go/blob/main/README.md

Command to run integration tests using Dockerized PostgreSQL and PostgREST instances managed by testcontainers. This provides a realistic testing environment.

```bash
go test -v -run TestIntegration
```

--------------------------------

### Create New PostgREST Client with Error Handling

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Constructs a new PostgREST client with explicit error handling. It parses the base URL and sets up default headers, including schema and client information.

```go
// NewClientWithError constructs a new client given a URL to a Postgrest instance.
func NewClientWithError(rawURL, schema string, headers map[string]string) (*Client, error) {
        // Create URL from rawURL
        baseURL, err := url.Parse(rawURL)
        if err != nil {
                return nil, err
        }

        t := transport{
                header:  http.Header{},
                baseURL: *baseURL,
                Parent:  nil,
        }

        c := Client{
                session:    &http.Client{Transport: &t},
                Transport:  &t,
                schemaName: schema,
        }

        if schema == "" {
                schema = "public"
                c.schemaName = schema
        }

        // Set required headers
        c.Transport.SetHeaders(map[string]string{
                "Accept":          "application/json",
                "Content-Type":    "application/json",
                "Accept-Profile":  schema,
                "Content-Profile": schema,
                "X-Client-Info":   "postgrest-go/" + version,
        })
        // Set optional headers if they exist
        c.Transport.SetHeaders(headers)

        return &c, nil
}
```

--------------------------------

### Set API Key or Auth Token

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Set the apikey header or Authorization: Bearer <token> header. Both return *Client for chaining.

```go
client := postgrest.NewClient("http://localhost:3000", "public", nil)

// API key auth (e.g., Supabase anon key)
client.SetApiKey("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...")

// JWT bearer token auth (e.g., logged-in user)
client.SetAuthToken("user-jwt-token-here")
```

--------------------------------

### Handle PostgREST Errors in Go

Source: https://github.com/supabase-community/postgrest-go/blob/main/README.md

Demonstrates how to check for both network/parsing errors and PostgREST-specific errors after executing a query. Use this when you need to manually inspect and handle different types of errors.

```go
response, err := client.From("users").Select("*", nil).Execute(context.Background())
if err != nil {
	// Network or parsing error
	panic(err)
}

if response.Error != nil {
	// PostgREST error
	fmt.Printf("Error: %s (Code: %s)\n", response.Error.Message, response.Error.Code)
	fmt.Printf("Details: %s\n", response.Error.Details)
	fmt.Printf("Hint: %s\n", response.Error.Hint)
}
```

--------------------------------

### From

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Specifies the table or view to query from. Returns a QueryBuilder instance.

```APIDOC
## From

### Description
Sets the table or view to query from.

### Method
```go
func (c *Client) From(relation string) *QueryBuilder[map[string]interface{}]
```

### Parameters
#### Path Parameters
- **relation** (string) - The name of the table or view.
```

--------------------------------

### Schema

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Selects a schema to perform queries or RPC calls against. Returns a new client instance configured for the specified schema.

```APIDOC
## Schema

### Description
Selects a schema to query or perform an function (rpc) call.

### Method
```go
func (c *Client) Schema(schema string) *Client
```

### Parameters
#### Path Parameters
- **schema** (string) - The name of the schema to select.
```

--------------------------------

### Return results as GeoJSON with GeoJSON()

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Set the `Accept` header to `application/geo+json` using `GeoJSON()`. The response `Data` will be a `map[string]interface{}` representing GeoJSON. This is suitable for geospatial data.

```go
ctx := context.Background()

resp, err := client.From("locations").
	Select("name, geom", nil).
	Eq("city", "San Francisco").
	GeoJSON().
	Execute(ctx)
if err != nil {
	panic(err)
}
data, _ := json.MarshalIndent(resp.Data, "", "  ")
fmt.Println(string(data))
```

--------------------------------

### LIKE and ILIKE Pattern Matching

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Explains how to use LIKE and ILIKE operators for case-sensitive and case-insensitive pattern matching in string columns.

```APIDOC
## Like / Ilike

### Description
Filters results based on pattern matching using LIKE (case-sensitive) or ILIKE (case-insensitive) operators.

### Method
Chained filter methods on `*FilterBuilder[T]`.

### Parameters
- **column** (string) - The column to filter on.
- **pattern** (string) - The pattern to match (e.g., `%widget%`).

### Example
```go
ctx := context.Background()
resp, _ := client.From("products").
	Select("name, sku", nil).
	Ilike("name", "%widget%").
	Execute(ctx)
```
```

--------------------------------

### Advanced Filtering with Multiple Conditions

Source: https://github.com/supabase-community/postgrest-go/blob/main/README.md

Demonstrates applying multiple filters (equality, greater/less than or equal, IN, LIKE) to a query. This allows for complex data retrieval based on various criteria.

```go
// Multiple filters
response, err := client.
	From("users").
	Select("*", nil).
	Eq("status", "active").
	Gte("age", 18).
	Lte("age", 65).
	In("role", []interface{}{"admin", "user"}).
	Like("name", "%John%").
	Execute(context.Background())
```

--------------------------------

### Select Columns for Query

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Use Select to specify which columns to retrieve in a SELECT query. Handles quoted column names and removes unnecessary whitespace. Defaults to selecting all columns if an empty string is provided.

```go
func (t *TransformBuilder[T]) Select(columns string) *FilterBuilder[T] {
        // Remove whitespaces except when quoted
        quoted := false
        var cleanedColumns strings.Builder
        for _, char := range columns {
                if char == '"' {
                        quoted = !quoted
                }
                if char == ' ' && !quoted {
                        continue
                }
                cleanedColumns.WriteRune(char)
        }

        cleaned := cleanedColumns.String()
        if cleaned == "" {
                cleaned = "*"
        }

        query := t.url.Query()
        query.Set("select", cleaned)
        t.url.RawQuery = query.Encode()
        t.headers.Add("Prefer", "return=representation")

        return &FilterBuilder[T]{Builder: t.Builder}
}
```

--------------------------------

### LIKE / ILIKE Pattern Matching Filter

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Perform case-sensitive (LIKE) or case-insensitive (ILIKE) pattern matching on text columns. Use SQL wildcards like '%' and '_'.

```go
ctx := context.Background()

// LIKE / ILIKE pattern matching
resp, _ = client.From("products").
	Select("name, sku", nil).
	Ilike("name", "%widget%").
	Execute(ctx)
```

--------------------------------

### Apply Order to Query

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Adds an ORDER BY clause to the query. Specify the column and sorting options.

```go
func (f *FilterBuilder[T]) Order(column string, opts *OrderOptions) *TransformBuilder[T] {
        tb := &TransformBuilder[T]{Builder: f.Builder}
        return tb.Order(column, opts)
}
```

--------------------------------

### Equality, Inequality, and Numeric Comparisons

Source: https://context7.com/supabase-community/postgrest-go/llms.txt

Demonstrates how to filter results based on equality (Eq), inequality (Neq), greater than or equal to (Gte), and less than or equal to (Lte) operators.

```APIDOC
## Eq, Neq, Gt, Gte, Lt, Lte

### Description
Filters results based on equality, inequality, and numeric comparisons.

### Method
Chained filter methods on `*FilterBuilder[T]`.

### Parameters
- **column** (string) - The column to filter on.
- **value** (interface{}) - The value to compare against.

### Example
```go
ctx := context.Background()
resp, _ := client.From("products").
	Select("*", nil).
	Eq("category", "electronics").
	Neq("status", "discontinued").
	Gte("price", 10).
	Lte("price", 500).
	Execute(ctx)
```
```

--------------------------------

### Single()

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Configures the request to return data as a single object instead of an array. This is achieved by setting the 'Accept' header to 'application/vnd.pgrst.object+json'.

```APIDOC
## Single()

### Description
Returns data as a single object instead of an array.

### Method
Sets the 'Accept' header to 'application/vnd.pgrst.object+json'.

### Endpoint
N/A (Method modifies request headers)

### Parameters
None

### Request Example
```go
// Assuming 'builder' is an instance of TransformBuilder
builder.Single()
```

### Response
Modifies the 'Accept' header for the request.
```

--------------------------------

### Order Query Results

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Use Order to sort the query results by a specified column. Supports ascending/descending order and nulls first/last options. Can specify a referenced table for ordering.

```go
func (t *TransformBuilder[T]) Order(column string, opts *OrderOptions) *TransformBuilder[T] {
        if opts == nil {
                opts = &OrderOptions{Ascending: true}
        }

        key := "order"
        if opts.ReferencedTable != "" {
                key = opts.ReferencedTable + ".order"
        }

        ascendingStr := "desc"
        if opts.Ascending {
                ascendingStr = "asc"
        }

        nullsStr := ""
        if opts.NullsFirst != nil {
                if *opts.NullsFirst {
                        nullsStr = ".nullsfirst"
                } else {
                        nullsStr = ".nullslast"
                }
        }

        query := t.url.Query()
        existingOrder := query.Get(key)
        orderValue := fmt.Sprintf("%s.%s%s", column, ascendingStr, nullsStr)
        if existingOrder != "" {
                orderValue = existingOrder + "," + orderValue
        }

        query.Set(key, orderValue)
        t.url.RawQuery = query.Encode()
        return t
}
```

--------------------------------

### Set Response to CSV Format

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Use the CSV method to request data in CSV format. This sets the 'Accept' header to 'text/csv'.

```go
func (t *TransformBuilder[T]) CSV() *Builder[string] {
        t.headers.Set("Accept", "text/csv")
        return &Builder[string]{
                method:             t.method,
                url:                t.url,
                headers:            t.headers,
                schema:             t.schema,
                body:               t.body,
                shouldThrowOnError: t.shouldThrowOnError,
                signal:             t.signal,
                client:             t.client,
                isMaybeSingle:      t.isMaybeSingle,
        }
}
```

--------------------------------

### Select Method

Source: https://github.com/supabase-community/postgrest-go/wiki/coverage.html

Method to specify which columns to include in the response.

```APIDOC
## Select

### Description
Specifies which columns to include in the response.

### Method
`Select(columns string) *FilterBuilder[T]`

### Parameters
- **columns** (string) - A comma-separated string of column names to select.

### Endpoint
(Implicitly applied to the PostgREST query)

### Request Example
(Not applicable, this is a client-side method)

### Response
(Returns a modified FilterBuilder instance, enabling chaining with TransformBuilder methods)
```
Tokens:
Raw