gem-hunter

Postgrest GO

Important

Update, September 2026:
This codebase is not being actively maintained by Supabase or the community, but it's not the end of the road... We're busy building an official Supabase SDK for Go that will make this repository and the module it publishes obsolete. This thread has more information, as well as providing a venue for discussion in the meantime.

Documentation

Installation

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

Version compatibility

go get github.com/supabase-community/postgrest-go@main

Quick Start

Basic usage (v0.0.12) {#basic-usage-v012}

package main

import (
	"encoding/json"
	"fmt"

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

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

	data, count, err := client.From("users").Select("*", "", false).Execute()
	if err != nil {
		panic(err)
	}

	fmt.Printf("count: %d\n", count)
	fmt.Println(string(data))
}

Basic Usage (main branch)

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

Select with Filters

// 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())

Insert Data

// Insert a single row
insertOpts := &postgrest.InsertOptions{Count: "exact"}
response, err := client.
	From("users").
	Insert(map[string]interface{}{
		"name":  "John Doe",
		"email": "john@example.com",
	}, insertOpts).
	Execute(context.Background())

Update Data

// Update rows
updateOpts := &postgrest.UpdateOptions{Count: "exact"}
response, err := client.
	From("users").
	Update(map[string]interface{}{
		"status": "inactive",
	}, updateOpts).
	Eq("id", 1).
	Execute(context.Background())

Delete Data

// Delete rows
deleteOpts := &postgrest.DeleteOptions{Count: "exact"}
response, err := client.
	From("users").
	Delete(deleteOpts).
	Eq("status", "inactive").
	Execute(context.Background())

Upsert Data

// Upsert (insert or update)
upsertOpts := &postgrest.UpsertOptions{
	OnConflict:      "email",
	IgnoreDuplicates: false,
	Count:           "exact",
}
response, err := client.
	From("users").
	Upsert(map[string]interface{}{
		"email": "john@example.com",
		"name":  "John Doe",
	}, upsertOpts).
	Execute(context.Background())

RPC (Remote Procedure Call)

// Call a PostgreSQL function
rpcOpts := &postgrest.RpcOptions{Count: "exact"}
response, err := client.
	Rpc("get_user_by_email", map[string]interface{}{
		"email": "john@example.com",
	}, rpcOpts).
	Execute(context.Background())

Advanced Filtering

// 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())

// Text search
textSearchOpts := &postgrest.TextSearchOptions{
	Type:   "websearch",
	Config: "english",
}
response, err := client.
	From("posts").
	Select("*", nil).
	TextSearch("content", "golang tutorial", textSearchOpts).
	Execute(context.Background())

Single Result

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

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

ExecuteTo (Unmarshal directly)

// Unmarshal directly into a struct
type User struct {
	ID    int64  `json:"id"`
	Name  string `json:"name"`
	Email string `json:"email"`
}

var users []User
count, err := client.
	From("users").
	Select("*", nil).
	Eq("status", "active").
	ExecuteTo(context.Background(), &users)

Schema Selection

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

Error Handling

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

Throw on Error

// Throw errors instead of returning them in response
response, err := client.
	From("users").
	Select("*", nil).
	ThrowOnError().
	Execute(context.Background())
// If there's an error, it will be thrown here

API Reference

Client Methods

QueryBuilder Methods

FilterBuilder Methods

TransformBuilder Methods

Response Structure

type PostgrestResponse[T any] struct {
	Error      *PostgrestError `json:"error,omitempty"`
	Data       T               `json:"data,omitempty"`
	Count      *int64          `json:"count,omitempty"`
	Status     int             `json:"status"`
	StatusText string          `json:"statusText"`
}

Testing

Unit Tests

go test ./...

Integration Tests

Running Integration Tests

go test -v -run TestIntegration

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

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

Integration Test Coverage

Test Database Schema

Package made possible through the efforts of:

License

Sponsors