Documentation
¶
Overview ¶
Package rsql provides a typed Go client for the rsql HTTP API.
The package separates administrative namespace lifecycle operations from namespace-bound database operations. Client values are safe for concurrent use and all network operations are controlled by context.Context.
Index ¶
- Constants
- type APIError
- type AdminClient
- type ChangelogClient
- type ChangelogEntry
- type Client
- type ColumnDefinition
- type Config
- type DatabaseClient
- func (d *DatabaseClient) Forward(writer http.ResponseWriter, incoming *http.Request, route DatabaseRoute) error
- func (d *DatabaseClient) Namespace() string
- func (d *DatabaseClient) RoundTrip(ctx context.Context, incoming *http.Request, route DatabaseRoute) (*http.Response, error)
- func (d *DatabaseClient) Table(name string) (*TableClient, error)
- type DatabaseRoute
- type EventStream
- type EventsClient
- type ImportOptions
- type IndexCreateRequest
- type IndexesClient
- type ListMeta
- type MutateOptions
- type MutationResult
- type NamespaceAdmin
- func (n NamespaceAdmin) Create(ctx context.Context, definition NamespaceDefinition) (NamespaceRecord, error)
- func (n NamespaceAdmin) Delete(ctx context.Context, namespace string) error
- func (n NamespaceAdmin) Duplicate(ctx context.Context, source, target string) error
- func (n NamespaceAdmin) Export(ctx context.Context, namespace string) (*StreamResponse, error)
- func (n NamespaceAdmin) Get(ctx context.Context, namespace string) (NamespaceRecord, error)
- func (n NamespaceAdmin) ImportCSV(ctx context.Context, namespace string, table string, upload ImportOptions) (MutationResult, error)
- func (n NamespaceAdmin) ImportDatabase(ctx context.Context, namespace string, upload ImportOptions) error
- func (n NamespaceAdmin) List(ctx context.Context) ([]NamespaceRecord, error)
- func (n NamespaceAdmin) Update(ctx context.Context, namespace string, config NamespaceConfig) (NamespaceRecord, error)
- type NamespaceConfig
- type NamespaceDefinition
- type NamespaceOverview
- type NamespaceRecord
- type OverviewClient
- type OverviewLatency
- type OverviewWindow
- type QueryClient
- type QueryRequest
- type QueryStatement
- type RowsClient
- func (r RowsClient) BulkDelete(ctx context.Context, query map[string][]string, options MutateOptions) (MutationResult, error)
- func (r RowsClient) BulkUpdate(ctx context.Context, query map[string][]string, payload map[string]any, ...) (MutationResult, error)
- func (r RowsClient) Delete(ctx context.Context, id int64, options MutateOptions) (MutationResult, error)
- func (r RowsClient) Get(ctx context.Context, id int64) (map[string]any, error)
- func (r RowsClient) Insert(ctx context.Context, rows []map[string]any, options MutateOptions) (MutationResult, error)
- func (r RowsClient) InsertOne(ctx context.Context, row map[string]any, options MutateOptions) (MutationResult, error)
- func (r RowsClient) List(ctx context.Context, query map[string][]string) (RowsResponse, error)
- func (r RowsClient) Update(ctx context.Context, id int64, payload map[string]any, options MutateOptions) (MutationResult, error)
- type RowsResponse
- type SSEEvent
- type SchemaClient
- type StorageSnapshot
- type StreamResponse
- type SubscribeOptions
- type TableClient
- type TableCreateRequest
- type TableExportOptions
- type TableUpdateRequest
- type TablesClient
- func (t TablesClient) Create(ctx context.Context, request TableCreateRequest) error
- func (t TablesClient) Delete(ctx context.Context, name string, meta json.RawMessage) error
- func (t TablesClient) Get(ctx context.Context, name string) (map[string]any, error)
- func (t TablesClient) List(ctx context.Context) ([]map[string]any, error)
- func (t TablesClient) Update(ctx context.Context, name string, request TableUpdateRequest) error
Constants ¶
const ( PreferReturnRepresentation = "return=representation" PreferMergeDuplicates = "resolution=merge-duplicates" PreferIgnoreDuplicates = "resolution=ignore-duplicates" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AdminClient ¶
type AdminClient struct {
Namespaces NamespaceAdmin
}
AdminClient exposes control-plane operations.
type ChangelogClient ¶
type ChangelogClient struct {
// contains filtered or unexported fields
}
ChangelogClient reads schema changes.
func (ChangelogClient) List ¶
func (c ChangelogClient) List( ctx context.Context, table string, limit int, offset int, ) ([]ChangelogEntry, error)
List returns schema changelog entries.
type ChangelogEntry ¶
type ChangelogEntry struct {
ID int `json:"id"`
Timestamp string `json:"timestamp"`
Action string `json:"action"`
Table string `json:"table"`
Detail json.RawMessage `json:"detail"`
Meta json.RawMessage `json:"_meta,omitempty"`
}
ChangelogEntry is one schema changelog item.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a concurrency-safe rsql API client.
func (*Client) Admin ¶
func (c *Client) Admin() AdminClient
Admin returns the explicit control-plane API.
func (*Client) CloseIdleConnections ¶
func (c *Client) CloseIdleConnections()
CloseIdleConnections closes pooled idle HTTP connections.
type ColumnDefinition ¶
type ColumnDefinition struct {
Name string `json:"name"`
Type string `json:"type"`
NotNull bool `json:"not_null,omitempty"`
Unique bool `json:"unique,omitempty"`
Default any `json:"default,omitempty"`
Index bool `json:"index,omitempty"`
Pattern string `json:"pattern,omitempty"`
MaxLength int `json:"max_length,omitempty"`
Min *float64 `json:"min,omitempty"`
Max *float64 `json:"max,omitempty"`
Auto bool `json:"auto,omitempty"`
Options []string `json:"options,omitempty"`
Formula string `json:"formula,omitempty"`
Metadata json.RawMessage `json:"metadata,omitempty"`
PrimaryKey bool `json:"primary_key,omitempty"`
ReadOnly bool `json:"read_only,omitempty"`
}
ColumnDefinition describes one table column.
type DatabaseClient ¶
type DatabaseClient struct {
Overview OverviewClient
Query QueryClient
Changelog ChangelogClient
Events EventsClient
Tables TablesClient
// contains filtered or unexported fields
}
DatabaseClient exposes data-plane operations for one fixed namespace.
func (*DatabaseClient) Forward ¶
func (d *DatabaseClient) Forward( writer http.ResponseWriter, incoming *http.Request, route DatabaseRoute, ) error
Forward streams an incoming request and its upstream response.
func (*DatabaseClient) Namespace ¶
func (d *DatabaseClient) Namespace() string
Namespace returns the bound namespace name.
func (*DatabaseClient) RoundTrip ¶
func (d *DatabaseClient) RoundTrip( ctx context.Context, incoming *http.Request, route DatabaseRoute, ) (*http.Response, error)
RoundTrip forwards an incoming request to this database without buffering.
Unlike typed methods, non-2xx responses are returned unchanged. The caller owns and must close the response body.
func (*DatabaseClient) Table ¶
func (d *DatabaseClient) Table(name string) (*TableClient, error)
Table binds operations to one table.
type DatabaseRoute ¶
DatabaseRoute identifies a namespace-relative data-plane route.
type EventStream ¶
type EventStream struct {
// contains filtered or unexported fields
}
EventStream is a pull-based SSE iterator without hidden goroutines.
func (*EventStream) Close ¶
func (s *EventStream) Close() error
Close closes the underlying HTTP response body.
func (*EventStream) Err ¶
func (s *EventStream) Err() error
Err returns the terminal stream error, if any.
func (*EventStream) Event ¶
func (s *EventStream) Event() SSEEvent
Event returns the most recent event. It is valid until the next Next call.
func (*EventStream) Header ¶
func (s *EventStream) Header() http.Header
Header returns the subscription response headers.
func (*EventStream) Next ¶
func (s *EventStream) Next() bool
Next blocks until the next event is available or the stream ends.
type EventsClient ¶
type EventsClient struct {
// contains filtered or unexported fields
}
EventsClient opens typed namespace event streams.
func (EventsClient) Subscribe ¶
func (e EventsClient) Subscribe(ctx context.Context, options SubscribeOptions) (*EventStream, error)
Subscribe opens an SSE subscription. The caller must close the stream.
type ImportOptions ¶
ImportOptions describes a streamed multipart upload.
type IndexCreateRequest ¶
type IndexCreateRequest struct {
Type string `json:"type"`
Name string `json:"name,omitempty"`
Columns []string `json:"columns"`
Meta json.RawMessage `json:"_meta,omitempty"`
}
IndexCreateRequest creates a regular, unique, or FTS index.
type IndexesClient ¶
type IndexesClient struct {
// contains filtered or unexported fields
}
IndexesClient manages indexes for one table.
func (IndexesClient) Create ¶
func (i IndexesClient) Create(ctx context.Context, request IndexCreateRequest) error
Create creates a regular, unique, or FTS index.
func (IndexesClient) Delete ¶
func (i IndexesClient) Delete(ctx context.Context, name string, meta json.RawMessage) error
Delete removes an index.
type ListMeta ¶
type ListMeta struct {
TotalCount int `json:"total_count"`
FilterCount int `json:"filter_count"`
Limit int `json:"limit"`
Offset int `json:"offset"`
}
ListMeta describes a paginated row result.
type MutateOptions ¶
type MutateOptions struct {
Prefer string
Meta json.RawMessage
}
MutateOptions controls mutation response and audit metadata.
type MutationResult ¶
type MutationResult struct {
Data []map[string]any `json:"data,omitempty"`
Inserted int `json:"inserted,omitempty"`
Updated int `json:"updated,omitempty"`
Deleted int `json:"deleted,omitempty"`
}
MutationResult represents row mutation response variants.
type NamespaceAdmin ¶
type NamespaceAdmin struct {
// contains filtered or unexported fields
}
NamespaceAdmin manages namespace lifecycle.
func (NamespaceAdmin) Create ¶
func (n NamespaceAdmin) Create(ctx context.Context, definition NamespaceDefinition) (NamespaceRecord, error)
Create provisions a namespace.
func (NamespaceAdmin) Delete ¶
func (n NamespaceAdmin) Delete(ctx context.Context, namespace string) error
Delete removes a namespace.
func (NamespaceAdmin) Duplicate ¶
func (n NamespaceAdmin) Duplicate(ctx context.Context, source, target string) error
Duplicate copies a namespace into target.
func (NamespaceAdmin) Export ¶
func (n NamespaceAdmin) Export(ctx context.Context, namespace string) (*StreamResponse, error)
Export streams a consistent namespace database snapshot.
func (NamespaceAdmin) Get ¶
func (n NamespaceAdmin) Get(ctx context.Context, namespace string) (NamespaceRecord, error)
Get returns one namespace record and its config.
func (NamespaceAdmin) ImportCSV ¶
func (n NamespaceAdmin) ImportCSV( ctx context.Context, namespace string, table string, upload ImportOptions, ) (MutationResult, error)
ImportCSV streams CSV rows into an existing table.
func (NamespaceAdmin) ImportDatabase ¶
func (n NamespaceAdmin) ImportDatabase(ctx context.Context, namespace string, upload ImportOptions) error
ImportDatabase replaces a namespace from a streamed SQLite upload.
func (NamespaceAdmin) List ¶
func (n NamespaceAdmin) List(ctx context.Context) ([]NamespaceRecord, error)
List returns all active namespaces without opening their database files.
func (NamespaceAdmin) Update ¶
func (n NamespaceAdmin) Update(ctx context.Context, namespace string, config NamespaceConfig) (NamespaceRecord, error)
Update applies a namespace config.
type NamespaceConfig ¶
type NamespaceConfig struct {
JournalMode string `json:"journal_mode"`
BusyTimeout int `json:"busy_timeout"`
MaxDBSize int64 `json:"max_db_size,omitempty"`
QueryTimeout int `json:"query_timeout"`
ForeignKeys *bool `json:"foreign_keys,omitempty"`
ReadOnly bool `json:"read_only,omitempty"`
}
NamespaceConfig configures one namespace database.
func DefaultNamespaceConfig ¶
func DefaultNamespaceConfig() NamespaceConfig
DefaultNamespaceConfig returns the server's standard namespace settings.
type NamespaceDefinition ¶
type NamespaceDefinition struct {
Name string `json:"name"`
Config *NamespaceConfig `json:"config,omitempty"`
}
NamespaceDefinition describes a namespace to create.
type NamespaceOverview ¶
type NamespaceOverview struct {
GeneratedAt string `json:"generated_at"`
Window struct {
Name OverviewWindow `json:"name"`
From string `json:"from"`
To string `json:"to"`
Resolution string `json:"resolution"`
} `json:"window"`
Health struct {
Status string `json:"status"`
Mode string `json:"mode"`
Issues []string `json:"issues"`
} `json:"health"`
Storage struct {
StorageSnapshot
ReclaimableBytes int64 `json:"reclaimable_bytes"`
QuotaBytes int64 `json:"quota_bytes"`
RemainingBytes *int64 `json:"remaining_bytes"`
UsageRatio *float64 `json:"usage_ratio"`
DatabaseFileBytes int64 `json:"database_file_bytes"`
SHMBytes int64 `json:"shm_bytes"`
} `json:"storage"`
Activity struct {
Requests uint64 `json:"requests"`
Reads uint64 `json:"reads"`
Writes uint64 `json:"writes"`
Errors uint64 `json:"errors"`
ErrorRate float64 `json:"error_rate"`
ResponseBytes uint64 `json:"response_bytes"`
LastActivityAt *string `json:"last_activity_at"`
Series []struct {
Timestamp string `json:"timestamp"`
Reads uint64 `json:"reads"`
Writes uint64 `json:"writes"`
Errors uint64 `json:"errors"`
} `json:"series"`
} `json:"activity"`
ReadLatency OverviewLatency `json:"read_latency"`
WriteLatency OverviewLatency `json:"write_latency"`
WriteContention struct {
Wait OverviewLatency `json:"wait"`
BusyErrors uint64 `json:"busy_errors"`
Timeouts uint64 `json:"timeouts"`
QuotaRejections uint64 `json:"quota_rejections"`
} `json:"write_contention"`
Schema struct {
Tables int `json:"tables"`
Views int `json:"views"`
Indexes int `json:"indexes"`
FTSIndexes int `json:"fts_indexes"`
} `json:"schema"`
Realtime struct {
Subscribers int `json:"subscribers"`
} `json:"realtime"`
TopOperations []struct {
Name string `json:"name"`
Count uint64 `json:"count"`
Errors uint64 `json:"errors"`
ErrorRate float64 `json:"error_rate"`
Latency OverviewLatency `json:"latency"`
} `json:"top_operations"`
Growth *struct {
BytesPerDay float64 `json:"bytes_per_day"`
SampleCount int `json:"sample_count"`
ProjectedFullAt *string `json:"projected_full_at"`
} `json:"growth,omitempty"`
}
NamespaceOverview is the tenant-facing operational summary.
type NamespaceRecord ¶
type NamespaceRecord struct {
Name string `json:"name"`
CreatedAt string `json:"created_at,omitempty"`
DBPath string `json:"db_path,omitempty"`
Config *NamespaceConfig `json:"config,omitempty"`
LastActivityAt string `json:"last_activity_at,omitempty"`
Storage *StorageSnapshot `json:"storage,omitempty"`
}
NamespaceRecord is namespace control-plane metadata.
type OverviewClient ¶
type OverviewClient struct {
// contains filtered or unexported fields
}
OverviewClient reads namespace health and usage.
func (OverviewClient) Get ¶
func (o OverviewClient) Get(ctx context.Context, window OverviewWindow) (NamespaceOverview, error)
Get returns a namespace overview for window.
type OverviewLatency ¶
type OverviewLatency struct {
Count uint64 `json:"count"`
AverageMS float64 `json:"average_ms"`
P50MS float64 `json:"p50_ms"`
P95MS float64 `json:"p95_ms"`
P99MS float64 `json:"p99_ms"`
}
OverviewLatency summarizes request latency.
type OverviewWindow ¶
type OverviewWindow string
OverviewWindow identifies a supported telemetry window.
const ( Window1Hour OverviewWindow = "1h" Window24Hour OverviewWindow = "24h" Window7Days OverviewWindow = "7d" Window30Days OverviewWindow = "30d" )
type QueryClient ¶
type QueryClient struct {
// contains filtered or unexported fields
}
QueryClient runs read-only SQL.
func (QueryClient) Batch ¶
func (q QueryClient) Batch(ctx context.Context, statements []QueryStatement) (map[string]any, error)
Batch executes read-only statements in one request.
func (QueryClient) Run ¶
func (q QueryClient) Run(ctx context.Context, request QueryRequest) (map[string]any, error)
Run executes a single query or request-defined batch.
type QueryRequest ¶
type QueryRequest struct {
SQL string `json:"sql,omitempty"`
Params []any `json:"params,omitempty"`
Statements []QueryStatement `json:"statements,omitempty"`
}
QueryRequest executes a single statement or a batch.
type QueryStatement ¶
QueryStatement is one read-only SQL statement.
type RowsClient ¶
type RowsClient struct {
// contains filtered or unexported fields
}
RowsClient manages rows for one table.
func (RowsClient) BulkDelete ¶
func (r RowsClient) BulkDelete( ctx context.Context, query map[string][]string, options MutateOptions, ) (MutationResult, error)
BulkDelete removes all rows matching query.
func (RowsClient) BulkUpdate ¶
func (r RowsClient) BulkUpdate( ctx context.Context, query map[string][]string, payload map[string]any, options MutateOptions, ) (MutationResult, error)
BulkUpdate updates all rows matching query.
func (RowsClient) Delete ¶
func (r RowsClient) Delete(ctx context.Context, id int64, options MutateOptions) (MutationResult, error)
Delete removes one row by id.
func (RowsClient) Insert ¶
func (r RowsClient) Insert( ctx context.Context, rows []map[string]any, options MutateOptions, ) (MutationResult, error)
Insert inserts multiple rows.
func (RowsClient) InsertOne ¶
func (r RowsClient) InsertOne( ctx context.Context, row map[string]any, options MutateOptions, ) (MutationResult, error)
InsertOne inserts one row.
func (RowsClient) List ¶
func (r RowsClient) List(ctx context.Context, query map[string][]string) (RowsResponse, error)
List returns filtered and paginated rows.
func (RowsClient) Update ¶
func (r RowsClient) Update( ctx context.Context, id int64, payload map[string]any, options MutateOptions, ) (MutationResult, error)
Update updates one row by id.
type RowsResponse ¶
type RowsResponse struct {
Data []map[string]any `json:"data"`
Meta *ListMeta `json:"meta,omitempty"`
}
RowsResponse represents regular and aggregate row-list responses.
type SSEEvent ¶
type SSEEvent struct {
Namespace string `json:"namespace,omitempty"`
Table string `json:"table"`
Action string `json:"action"`
SourceTable string `json:"source_table,omitempty"`
SourceAction string `json:"source_action,omitempty"`
Row map[string]any `json:"row,omitempty"`
RowCount int `json:"row_count,omitempty"`
RowIDs []any `json:"row_ids,omitempty"`
Detail map[string]any `json:"detail,omitempty"`
Meta json.RawMessage `json:"_meta,omitempty"`
Timestamp string `json:"timestamp"`
}
SSEEvent represents one namespace change event.
type SchemaClient ¶
type SchemaClient struct {
// contains filtered or unexported fields
}
SchemaClient manages one table or view schema.
func (SchemaClient) Delete ¶
func (s SchemaClient) Delete(ctx context.Context, meta json.RawMessage) error
Delete removes the table or view.
func (SchemaClient) Update ¶
func (s SchemaClient) Update(ctx context.Context, request TableUpdateRequest) error
Update applies a schema update.
type StorageSnapshot ¶
type StorageSnapshot struct {
UsedBytes int64 `json:"used_bytes"`
AllocatedBytes int64 `json:"allocated_bytes"`
WALBytes int64 `json:"wal_bytes"`
DiskBytes int64 `json:"disk_bytes"`
}
StorageSnapshot contains lightweight storage values.
type StreamResponse ¶
type StreamResponse struct {
Status int
Header http.Header
Body io.ReadCloser
}
StreamResponse is a successful streaming response. Callers must close Body.
type SubscribeOptions ¶
type SubscribeOptions struct {
Tables []string
}
SubscribeOptions filters a namespace event stream.
type TableClient ¶
type TableClient struct {
Schema SchemaClient
Indexes IndexesClient
Rows RowsClient
// contains filtered or unexported fields
}
TableClient exposes operations for one fixed table.
func (*TableClient) Export ¶
func (t *TableClient) Export(ctx context.Context, options TableExportOptions) (*StreamResponse, error)
Export streams this table as CSV.
type TableCreateRequest ¶
type TableCreateRequest struct {
Type string `json:"type"`
Name string `json:"name"`
Metadata json.RawMessage `json:"metadata,omitempty"`
Columns []ColumnDefinition `json:"columns,omitempty"`
SQL string `json:"sql,omitempty"`
Meta json.RawMessage `json:"_meta,omitempty"`
}
TableCreateRequest creates a table or view.
type TableExportOptions ¶
TableExportOptions configures streamed CSV export.
type TableUpdateRequest ¶
type TableUpdateRequest struct {
Rename string `json:"rename,omitempty"`
AddColumns []ColumnDefinition `json:"add_columns,omitempty"`
DropColumns []string `json:"drop_columns,omitempty"`
RenameColumns map[string]string `json:"rename_columns,omitempty"`
SQL string `json:"sql,omitempty"`
Metadata json.RawMessage `json:"metadata,omitempty"`
Meta json.RawMessage `json:"_meta,omitempty"`
}
TableUpdateRequest updates a table or view.
type TablesClient ¶
type TablesClient struct {
// contains filtered or unexported fields
}
TablesClient manages tables and views inside a namespace.
func (TablesClient) Create ¶
func (t TablesClient) Create(ctx context.Context, request TableCreateRequest) error
Create creates a table or view.
func (TablesClient) Delete ¶
func (t TablesClient) Delete(ctx context.Context, name string, meta json.RawMessage) error
Delete removes a table or view.
func (TablesClient) Update ¶
func (t TablesClient) Update(ctx context.Context, name string, request TableUpdateRequest) error
Update updates table or view schema.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
rsql
command
|
|
|
internal
|
|
|
app
Package app provides application bootstrap and runtime lifecycle management for the rsql server process.
|
Package app provides application bootstrap and runtime lifecycle management for the rsql server process. |
|
auth
Package auth provides bearer-token authentication helpers for rsql HTTP APIs.
|
Package auth provides bearer-token authentication helpers for rsql HTTP APIs. |
|
cli
Package cli provides the command-line interface for running and inspecting the rsql server.
|
Package cli provides the command-line interface for running and inspecting the rsql server. |
|
config
Package config provides runtime configuration loading and validation for rsql.
|
Package config provides runtime configuration loading and validation for rsql. |
|
domain
Package domain defines shared API contracts and typed errors used by rsql.
|
Package domain defines shared API contracts and typed errors used by rsql. |
|
httpapi
Package httpapi defines HTTP routing, middleware composition, and API response behavior for the rsql service.
|
Package httpapi defines HTTP routing, middleware composition, and API response behavior for the rsql service. |
|
namespace
Package namespace manages namespace lifecycle and in-memory DB handles.
|
Package namespace manages namespace lifecycle and in-memory DB handles. |
|
observability
Package observability provides runtime metrics primitives for the rsql service.
|
Package observability provides runtime metrics primitives for the rsql service. |
|
service
Package service orchestrates rsql business logic on top of storage and runtime components.
|
Package service orchestrates rsql business logic on top of storage and runtime components. |
|
sse
Package sse provides server-sent-events subscription and fanout primitives.
|
Package sse provides server-sent-events subscription and fanout primitives. |
|
store/control
Package control provides global namespace lookup persistence in control.db.
|
Package control provides global namespace lookup persistence in control.db. |
|
store/sqlite
Package sqlite provides SQLite-backed schema, row, and query operations.
|
Package sqlite provides SQLite-backed schema, row, and query operations. |
|
telemetry
Package telemetry records bounded, namespace-scoped usage aggregates.
|
Package telemetry records bounded, namespace-scoped usage aggregates. |