Xata Documentation

After deploying the platform, install the Xata CLI and authenticate using a local profile. For local development, use the following credentials:

• Email: dev@xata.tech
• Password: Xata1234!

1. Install the CLI:

curl -fsSL https://xata.io/install.sh | bash

2. Authenticate to the local profile:

xata auth login --profile local --issuer http://localhost:8080/realms/xata --api-url http://localhost:5001 --client-secret devsecret

3. Switch to the local profile:

xata auth switch local

# Install CLI
curl -fsSL https://xata.io/install.sh | bash

# Authenticate to a local profile
xata auth login --profile local --issuer http://localhost:8080/realms/xata --api-url http://localhost:5001 --client-secret devsecret

# Set the profile
xata auth switch local

To run a local development instance of Xata, you must have Docker, Kind, and Tilt installed. The process involves creating a Kubernetes cluster via Kind and then using Tilt to deploy the platform components.

1. Create a Kind cluster:

kind create cluster --wait 10m

2. Deploy the platform using Tilt:

tilt up

Wait for all resources to become ready. Note that the initial deployment may take significant time due to image downloads.

Once authenticated, you can manage your Postgres instances using the CLI. You can create a new project (which includes a main branch) and subsequently create child branches for testing or development.

1. Create a project and its main branch:

xata project create --name my-project

2. Create a child branch:

xata branch create

# Create project and main branch
xata project create --name my-project

# Create a child branch
xata branch create

The Xata CLI is structured around services. When running a service command, the CLI automatically handles configuration loading, service initialization, and graceful shutdown.

Running the service command without arguments typically starts the service in its default mode. The CLI lifecycle for any service command follows this sequence:

1. Read Config: Loads configuration settings.
2. Init: Initializes the service.
3. Run: Executes the specific command (e.g., run, setup, or version).
4. Close: Performs cleanup and closes the service.

# Example of the command structure (conceptual)
xata <service-name> [command]

Available commands for a service:
- `<service-name>` (default): Starts the service
- `run`: Executes the service run logic
- `setup`: Executes the service setup logic
- `version`: Displays the service version

The gen-scopes.go tool is a CLI utility used to parse an OpenAPI specification (YAML) and generate Go code that maps API routes and HTTP methods to their required authentication scopes.

It produces a file named scopes.gen.go containing two primary functions:

1. GetScopes(method, path string) []string: Returns the required scopes for a specific HTTP method and path.
2. GetAllScopes() []string: Returns a list of all unique scopes defined in the specification.

Requirements for OpenAPI Scopes: All scopes defined in the security section of your OpenAPI spec must use one of two suffixes:

• :read
• :write

If a scope does not end with one of these suffixes, the tool will fail with an error.

Usage: Run the tool using go run and provide the path to your OpenAPI YAML file as the first argument.

go run gen-scopes.go <openapi.yaml>

The Config struct defines the operational parameters for the serverless gateway.

type Config struct {
	ListenAddress string
	TLSCert       *tls.Certificate
}

The Client interface provides methods for tracking individual events and group-level events in Xata's analytics system. It supports tracking single events, tracking events associated with a specific group, registering new groups, and gracefully closing the client connection.

// Example usage of the Client interface
type Client interface {
	Track(ctx context.Context, event events.Event)
	TrackGroup(ctx context.Context, event events.Event)
	RegisterGroup(ctx context.Context, groupType, groupKey string) error
	Close(ctx context.Context) error
}

The gen-scopes.go tool generates a Go file (scopes.gen.go) in the spec package. This file provides the following API for looking up authentication scopes:

func GetScopes(method, path string) []string

Returns the required scopes for a given route and method. The method argument is case-insensitive (it is converted to uppercase internally). The path argument should match the route pattern used in the OpenAPI spec (e.g., /users/{id}).

func GetAllScopes() []string

Returns all unique scopes defined in the OpenAPI spec as a slice of strings.

package spec

// Example usage of generated functions:

// Get scopes for a specific route
scopes := GetScopes("GET", "/users/:id")

// Get all available scopes
allScopes := GetAllScopes()

Use NewClient to create a new *Client instance. This function requires a clientName (string) and an openfeature.FeatureProvider. It automatically sets the global provider using openfeature.SetProviderAndWait before returning the client. If setting the provider fails, an error is returned.

import (
	"github.com/open-feature/go-sdk/openfeature"
	"your-project/internal/openfeature/client"
)

// Assuming you have a provider implementation
provider := myProvider
client, err := client.NewClient("my-client", provider)
if err != nil {
	// handle error
}

The NewServer function initializes a new Server instance for the serverless gateway. It configures the underlying Echo router with CORS support (allowing all origins), body size limits, and header normalization middleware. It also registers the core gateway handlers defined in the spec package.

To use NewServer, you must provide:

• An observability object (*o11y.O)
• A session.BranchResolver for resolving branches
• A session.ClusterDialer for cluster connections
• *metrics.GatewayMetrics for telemetry
• A session.IPFilter for IP-based access control
• A Config struct containing the ListenAddress and an optional TLSCert.

server, err := serverless.NewServer(
    o,
    resolver,
    dialer,
    gwMetrics,
    ipFilter,
    serverless.Config{
        ListenAddress: ":8080",
        TLSCert:       &cert,
    },
)