Documentation
¶
Overview ¶
Package rest provides a PostgreSQL REST API server similar to PostgREST.
The server automatically exposes database tables and views as REST endpoints. Each endpoint supports standard HTTP methods: GET, POST, PATCH, DELETE.
Tables and views are exposed at /table_or_view_name or `/schema_name/table_or_view_name` path. If schema_name is skipped `schema_name=public` is used
Query parameters control filtering, pagination, and ordering:
Parameter | Description --------------------|------------------------------------------------ ?select=col1,col2 | Select specific columns ?order=col.desc | Order results (supports nullsfirst/nullslast) ?order=similarity(col, 'search string') | Order by similarity (requires pg_trgm extension) ?limit=100 | Limit number of results (default: 100) ?offset=0 | Pagination offset (default: 0) ?col=eq.val | Filter by column equality ?col=gt.val | Filter with greater than comparison ?col=lt.val | Filter with less than comparison ?col=gte.val | Filter with greater than or equal comparison ?col=lte.val | Filter with less than or equal comparison ?col=like.val | Filter with pattern matching ?col=in.a,b,c | Filter with value lists ?col=is.null | Filter for null values ?or=(a.eq.x,b.lt.y) | Combine filters with logical operators ?col=cs.example,new | contains (@>) The column contains all these values. JSON object can be passed with urlencoded string ?col=cd.1,2,3. | is contained in (<@) The column’s values are all within this set
HTTP headers control response format for POST/PATCH/DELETE operations:
Header | Description -------------------------------|---------------------------------------- Prefer: return=minimal | Return status code only (default) Prefer: return=representation | Return modified rows in response body Prefer: count=exact | Add exact total count of rows for the query in Content-Range header Prefer: return=headers-only | Return headers with metadata only
API is compatible with PostgREST. For more details, see: https://docs.postgrest.org/en/stable/references/api/tables_views.html
Example usage:
server, err := rest.NewServer("postgres://user:pass@localhost/db", "")
if err != nil {
log.Fatal(err)
}
defer server.Shutdown()
log.Fatal(server.Start(":8080"))
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AGEHandler ¶
type AGEHandler struct {
// contains filtered or unexported fields
}
AGEHandler exposes AGE (Apache Graph Extension) graphs via REST WIP: only basic queries / functionalities have been tested
Example ¶
package main
import (
"cmp"
"context"
"fmt"
"log"
"net/http"
"net/http/httptest"
"os"
"strings"
"github.com/edgeflare/pigo/pkg/rest"
"github.com/jackc/pgx/v5/pgxpool"
)
func main() {
// Initialize a connection pool
ctx := context.Background()
graphName := "test_cypher"
pool, err := pgxpool.New(ctx, cmp.Or(os.Getenv("DATABASE_URL"), "postgres://postgres:secret@localhost:5432/testdb"))
if err != nil {
log.Fatalf("failed to create connection pool: %v", err)
}
defer pool.Close()
// Create an AGE handler with a default graph
handler, err := rest.NewAGEHandler(ctx, pool, graphName)
if err != nil {
log.Fatalf("failed to create AGE handler: %v", err)
}
defer handler.Close()
// Setup a test HTTP server
server := httptest.NewServer(handler)
defer server.Close()
// // or mount on specific /path
// mux := http.NewServeMux()
// mux.Handle("POST /graph", handler)
// if err = http.ListenAndServe(":8080", mux); err != nil {
// log.Fatalf("Server error: %v", err)
// }
// Example 1: Create a vertex
createReq := `{
"cypher": "CREATE (n:Person {name: 'Alice', age: 30}) RETURN n",
"columnCount": 1
}`
resp, err := http.Post(server.URL, "application/json", strings.NewReader(createReq))
if err != nil {
log.Fatalf("failed to send request: %v", err)
}
defer resp.Body.Close()
fmt.Printf("Create vertex status: %d\n", resp.StatusCode)
// Example 2: Query vertices
queryReq := `{
"cypher": "MATCH (n:Person) RETURN n",
"columnCount": 1
}`
resp, err = http.Post(server.URL, "application/json", strings.NewReader(queryReq))
if err != nil {
log.Fatalf("failed to send request: %v", err)
}
defer resp.Body.Close()
fmt.Printf("Query vertices status: %d\n", resp.StatusCode)
}
Output: Create vertex status: 200 Query vertices status: 200
func NewAGEHandler ¶
NewAGEHandler creates and configures a new API server
func (*AGEHandler) Close ¶
func (s *AGEHandler) Close()
Close performs cleanup when shutting down the server
func (*AGEHandler) ServeHTTP ¶
func (s *AGEHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP processes Cypher queries
type AGERequest ¶
type AGERequest struct {
Cypher string `json:"cypher"`
ColumnCount int `json:"columnCount,omitempty"` // for read requests. not required for write requests
}
AGERequest is the expected format for incoming API requests
type AGEResponse ¶
type AGEResponse struct {
Success bool `json:"success"`
Data any `json:"data,omitempty"`
Error string `json:"error,omitempty"`
}
AGEResponse is the format for API responses
type FilterParam ¶
type Headers ¶
type Headers struct {
Prefer *Prefer
}
Headers holds all parsed HTTP headers relevant to REST actions.
type OrderParam ¶
type OrderParam struct {
Column string
Direction string // asc or desc
NullsPosition string // first or last
Similarity string // https://www.postgresql.org/docs/current/pgtrgm.html
}
type Prefer ¶
type Prefer struct {
Return string // "minimal", "representation", "headers-only"
Count string // "exact", "planned", "estimated"
}
Prefer holds preferences from the Prefer header (RFC 7240).
func (*Prefer) WantsCountEstimated ¶
WantsCountEstimated reports whether the client wants an estimated count in the response.
func (*Prefer) WantsCountExact ¶
WantsCountExact reports whether the client wants an exact count in the response.
func (*Prefer) WantsCountPlanned ¶
WantsCountPlanned reports whether the client wants a planned count in the response.
func (*Prefer) WantsHeadersOnly ¶
WantsHeadersOnly reports whether the client prefers only headers with no response body for mutation operations.
func (*Prefer) WantsRepresentation ¶
WantsRepresentation reports whether the client prefers full representation in the response body for mutation operations.
type QueryParams ¶
type QueryParams struct {
Select []string // Columns to select
Order []OrderParam // Order by columns
Limit int // Limit results
Offset int // Offset results
Filters map[string][]FilterParam // Column filters
EmbedJoins []JoinParam // Embedded resource joins (foreign keys)
}
QueryParams holds parsed query parameters in a structured way
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
func (*Server) AddMiddleware ¶
func (s *Server) AddMiddleware(middleware ...httputil.Middleware)
Source Files