extension

package
v1.22.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 26, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package extension provides the interface to the PowerSync SQLite extension.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ApplySchema 

func ApplySchema(ctx context.Context, db sqlite.DB) error

ApplySchema applies the PowerSync schema to the database. This should be called once after opening the database.

func Path 

func Path() (string, error)

Path returns the path to the PowerSync extension for the current platform. The extension is extracted from the embedded binary to a temporary location.

func Register 

func Register() error

Register configures the SQLite driver to load the PowerSync extension on every new connection. This is called automatically via init().

func SchemaJSON 

func SchemaJSON() string

SchemaJSON returns the embedded PowerSync schema.

Types

type BucketProgress 

type BucketProgress struct {
	Priority    int `json:"priority"`
	AtLast      int `json:"at_last"`
	SinceLast   int `json:"since_last"`
	TargetCount int `json:"target_count"`
}

BucketProgress represents progress for a single bucket.

type ConnectionEvent 

type ConnectionEvent string

ConnectionEvent represents a connection state change. 

const (
	// ConnectionEstablished indicates the sync stream connection was established.
	ConnectionEstablished ConnectionEvent = "established"
	// ConnectionEnded indicates the sync stream connection ended.
	ConnectionEnded ConnectionEvent = "end"
)

type ControlOp 

type ControlOp string

ControlOp represents an operation for powersync_control. 

const (
	// OpStart starts a sync stream. Payload: StartRequest (JSON).
	OpStart ControlOp = "start"
	// OpStop stops the current sync stream. Payload: none.
	OpStop ControlOp = "stop"
	// OpLineText forwards a JSON line from the sync service. Payload: string.
	OpLineText ControlOp = "line_text"
	// OpLineBinary forwards a BSON line from the sync service. Payload: []byte.
	OpLineBinary ControlOp = "line_binary"
	// OpRefreshedToken notifies that the auth token was refreshed. Payload: none.
	OpRefreshedToken ControlOp = "refreshed_token"
	// OpCompletedUpload notifies that CRUD upload completed. Payload: none.
	OpCompletedUpload ControlOp = "completed_upload"
	// OpUpdateSubscriptions updates stream subscriptions. Payload: JSON array.
	OpUpdateSubscriptions ControlOp = "update_subscriptions"
)

type Controller 

type Controller struct {
	// contains filtered or unexported fields
}

Controller wraps the powersync_control SQLite function with type safety. It holds a dedicated database connection to ensure all operations use the same connection, since the PowerSync extension maintains per-connection state.

func NewController 

func NewController(db sqlite.DB) *Controller

NewController creates a new PowerSync controller. Call Close() when done to release the dedicated connection.

func (*Controller) Close 

func (c *Controller) Close() error

Close releases the dedicated connection.

func (*Controller) Control 

func (c *Controller) Control(ctx context.Context, op ControlOp, payload any) ([]Instruction, error)

Control sends a control command and returns the resulting instructions. The powersync_control function always expects 2 arguments (op, payload). All operations use a dedicated connection to ensure state consistency.

func (*Controller) NotifyConnection 

func (c *Controller) NotifyConnection(ctx context.Context, event ConnectionEvent) ([]Instruction, error)

NotifyConnection notifies of a connection state change.

func (*Controller) NotifyTokenRefreshed 

func (c *Controller) NotifyTokenRefreshed(ctx context.Context) ([]Instruction, error)

NotifyTokenRefreshed notifies that the auth token was refreshed.

func (*Controller) NotifyUploadCompleted 

func (c *Controller) NotifyUploadCompleted(ctx context.Context) ([]Instruction, error)

NotifyUploadCompleted notifies that CRUD upload completed.

func (*Controller) SendBinaryLine 

func (c *Controller) SendBinaryLine(ctx context.Context, data []byte) ([]Instruction, error)

SendBinaryLine forwards a BSON line from the sync service.

func (*Controller) SendTextLine 

func (c *Controller) SendTextLine(ctx context.Context, line string) ([]Instruction, error)

SendTextLine forwards a JSON line from the sync service.

func (*Controller) Start 

func (c *Controller) Start(ctx context.Context, req StartRequest) ([]Instruction, error)

Start begins a sync stream with the given parameters.

func (*Controller) Stop 

func (c *Controller) Stop(ctx context.Context) ([]Instruction, error)

Stop stops the current sync stream.

type DownloadProgress 

type DownloadProgress struct {
	Buckets map[string]BucketProgress `json:"buckets"`
}

DownloadProgress represents the current download progress.

func (*DownloadProgress) TotalProgress 

func (d *DownloadProgress) TotalProgress() (int, int)

TotalProgress returns the total progress across all buckets. Returns (downloaded, total) counts.

type Instruction 

type Instruction struct {
	Type InstructionType
	// Fields vary by type
	Request        *api.SyncStreamRequest
	DidExpire      *bool
	HideDisconnect *bool
	SyncStatus     *SyncStatus
	Severity       string
	Line           string
}

Instruction is a command returned by powersync_control. The extension returns instructions as tagged enums: {"InstructionType": {fields...}}

func (*Instruction) UnmarshalJSON 

func (i *Instruction) UnmarshalJSON(data []byte) error

UnmarshalJSON handles the serde-style tagged enum format from the extension. Example: {"EstablishSyncStream": {"request": {...}}}

type InstructionType 

type InstructionType string

InstructionType represents a PowerSync instruction type. 

const (
	InstructionEstablishSyncStream InstructionType = "EstablishSyncStream"
	InstructionFetchCredentials    InstructionType = "FetchCredentials"
	InstructionCloseSyncStream     InstructionType = "CloseSyncStream"
	InstructionFlushFileSystem     InstructionType = "FlushFileSystem"
	InstructionDidCompleteSync     InstructionType = "DidCompleteSync"
	InstructionUpdateSyncStatus    InstructionType = "UpdateSyncStatus"
	InstructionLogLine             InstructionType = "LogLine"
)

InstructionType constants for Instruction.Type.

type PriorityStatus 

type PriorityStatus struct {
	Priority     int   `json:"priority"`
	LastSyncedAt *int  `json:"last_synced_at"`
	HasSynced    *bool `json:"has_synced"`
}

PriorityStatus represents sync status for a specific priority level.

type StartRequest 

type StartRequest struct {
	// Parameters are bucket parameters for the sync request.
	Parameters map[string]any `json:"parameters,omitempty"`
	// Schema defines the tables to sync.
	Schema json.RawMessage `json:"schema,omitempty"`
	// IncludeDefaults whether to request default streams.
	IncludeDefaults bool `json:"include_defaults"`
	// ActiveStreams are currently active stream subscriptions.
	ActiveStreams []StreamKey `json:"active_streams,omitempty"`
}

StartRequest is the payload for OpStart.

type StreamKey 

type StreamKey struct {
	Name       string `json:"name"`
	Parameters string `json:"parameters,omitempty"`
}

StreamKey identifies a stream subscription.

type StreamProgress 

type StreamProgress struct {
	Total      int `json:"total"`
	Downloaded int `json:"downloaded"`
}

StreamProgress represents download progress for a stream.

type StreamStatus 

type StreamStatus struct {
	Name                    string          `json:"name"`
	Parameters              *string         `json:"parameters"`
	Priority                int             `json:"priority"`
	Active                  bool            `json:"active"`
	IsDefault               bool            `json:"is_default"`
	HasExplicitSubscription bool            `json:"has_explicit_subscription"`
	ExpiresAt               *int            `json:"expires_at"`
	LastSyncedAt            *int            `json:"last_synced_at"`
	Progress                *StreamProgress `json:"progress"`
}

StreamStatus represents the status of a sync stream subscription.

type SyncStatus 

type SyncStatus struct {
	Connected      bool              `json:"connected"`
	Connecting     bool              `json:"connecting"`
	PriorityStatus []PriorityStatus  `json:"priority_status"`
	Downloading    *DownloadProgress `json:"downloading"`
	Streams        []StreamStatus    `json:"streams"`
}

SyncStatus represents the detailed sync state from UpdateSyncStatus instructions.

Source Files

View all Source files

Directories

Path Synopsis
Package main generates the PowerSync schema from the PowerSync service.
 Package main generates the PowerSync schema from the PowerSync service.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.