Help us shape the future of Go! Take the 2026 Go Developer Survey

ocinosql

package
v1.9.1 Latest Latest
Warning

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

 Go to latest Published: Nov 1, 2026 License: MIT Imports: 32 Imported by: 0

README

OCI NoSQL Database Cloud Service

Parity grade: B · SDK github.com/oracle/oci-go-sdk/v65@v65.126.2 · last audited 2026-10-29 (57ea757db)

Coverage

Metric Value
PARITY entries audited 21 (18 ok, 3 partial)
Feature families 9 (6 ok, 3 partial)
Known gaps 9
Deferred items 0
Resource leaks unknown
Known gaps
  • CreateReplica, DeleteReplica, GetConfiguration, UpdateConfiguration, UnassignKmsKey and DeleteWorkRequest are not routed (multi-region tables, tenancy KMS configuration and work request deletion).
  • Throughput and storage limits are validated but not enforced: no read or write throttling, no storage quota, so the throttle counts of ListTableUsage stay 0.
  • The 50/50/25 auto-reclaimable (Always Free) defaults and the minimum of 1 unit are not found in any primary source reached; the documented region-level limits (30 tables, 3 on-demand tables, 4 DDL operations per minute, 100 schema updates per table, 4 limit decreases per day, once-a-day capacity mode change, 10000/5000 on-demand ceiling) are not enforced.
  • The REST error code for oversize keys, rows and query strings is LimitExceeded (400) by inference from the OCI error reference; the NoSQL REST reference page itself could not be fetched. Key and row size are approximated from string and number bytes, not the server's serialized form.
  • Queries scan all rows of a table; indexes only validate and order ORDER BY clauses, there is no index selection, and maxReadInKBs is accepted but not used to cut a batch.
  • Timestamps in WHERE comparisons are compared as normalized strings, so a literal must use the column's ISO 8601 form.
  • opc-retry-token idempotency, IAM policy checks, resource principals and instance principals are not applied; only API-key signatures are verified.
  • The dashboard has no OCI NoSQL page.
  • Tag values and defined-tag namespaces are stored verbatim, not validated against a tag namespace; systemTags are never set.

More

Documentation

Index

Constants

View Source 
const DefaultPort = 8162

DefaultPort is the dedicated listener's default TCP port.

View Source 
const (
	// Region is the fixed region baked into emulated OCIDs.
	Region = "us-ashburn-1"
)

Variables

View Source 
var ErrNilAppContext = errors.New("ocinosql: nil app context")

ErrNilAppContext is returned when Init is called with a nil AppContext.

View Source 
var ErrSnapshotNull = errors.New("ocinosql: null entry in snapshot")

ErrSnapshotNull is returned when a snapshot contains a null entry.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	Code    string
	Message string
	Status  int
}

APIError is an OCI error response: HTTP status plus the `code` and `message` body fields.

func (*APIError) Error 

func (e *APIError) Error() string

type Column 

type Column struct {
	Name    string          `json:"name"`
	Type    string          `json:"type"`
	Default json.RawMessage `json:"default,omitempty"`
	NotNull bool            `json:"notNull,omitempty"`
	AsUUID  bool            `json:"asUuid,omitempty"`
	Gen     bool            `json:"generated,omitempty"`
}

Column is one table column.

type ConfigProvider 

type ConfigProvider interface {
	GetOCINoSQLSettings() Settings
}

ConfigProvider extracts OCI NoSQL configuration from the AppContext Config.

type DeleteRowResult 

type DeleteRowResult struct {
	ExistingVersion *string         `json:"existingVersion,omitempty"`
	ExistingValue   json.RawMessage `json:"existingValue,omitempty"`
	IsSuccess       bool            `json:"isSuccess"`
	Usage           usageWire       `json:"usage"`
}

DeleteRowResult is the DeleteRow response body.

type Handler 

type Handler struct {
	Backend *InMemoryBackend

	Port        int
	EnforceAuth bool
	// contains filtered or unexported fields
}

Handler serves OCI NoSQL Database: tables, indexes, rows, queries and work requests.

func NewHandler 

func NewHandler(backend *InMemoryBackend) *Handler

NewHandler creates a Handler; callers override Port and EnforceAuth from Settings.

func (*Handler) ExtractOperation 

func (h *Handler) ExtractOperation(c *echo.Context) string

ExtractOperation returns the operation name for metrics.

func (*Handler) ExtractResource 

func (h *Handler) ExtractResource(c *echo.Context) string

ExtractResource returns the addressed resource id for metrics.

func (*Handler) GetSupportedOperations 

func (h *Handler) GetSupportedOperations() []string

GetSupportedOperations lists the supported operations.

func (*Handler) Handler 

func (h *Handler) Handler() echo.HandlerFunc

Handler returns the Echo handler for all OCINoSQL requests.

func (*Handler) MatchPriority 

func (h *Handler) MatchPriority() int

MatchPriority is irrelevant because RouteMatcher never matches.

func (*Handler) Name 

func (h *Handler) Name() string

Name returns the service name.

func (*Handler) Reset 

func (h *Handler) Reset()

Reset clears all in-memory state.

func (*Handler) Restore 

func (h *Handler) Restore(ctx context.Context, data []byte) error

Restore implements persistence.Persistable by delegating to the backend.

func (*Handler) RouteMatcher 

func (h *Handler) RouteMatcher() service.Matcher

RouteMatcher never matches: OCINoSQL runs on its own listener.

func (*Handler) Shutdown 

func (h *Handler) Shutdown(ctx context.Context)

Shutdown stops the listener and the sweeper.

func (*Handler) Snapshot 

func (h *Handler) Snapshot(ctx context.Context) []byte

Snapshot implements persistence.Persistable by delegating to the backend.

func (*Handler) StartWorker 

func (h *Handler) StartWorker(ctx context.Context) error

StartWorker binds the dedicated listener synchronously so a port conflict is returned to the caller.

func (*Handler) Trusted 

func (h *Handler) Trusted() echo.HandlerFunc

Trusted returns a handler that skips request-signature verification, for the in-process dashboard proxy.

type Identity 

type Identity struct {
	Column    string `json:"column"`
	Always    bool   `json:"always"`
	OnNull    bool   `json:"onNull,omitempty"`
	Next      int64  `json:"next"`
	Increment int64  `json:"increment"`
}

Identity is the table's identity column spec and its counter.

type InMemoryBackend 

type InMemoryBackend struct {
	Auth *ociauth.Registry
	// contains filtered or unexported fields
}

InMemoryBackend holds every table and work request under one lock.

func NewInMemoryBackend 

func NewInMemoryBackend() *InMemoryBackend

NewInMemoryBackend creates an empty backend.

func (*InMemoryBackend) ChangeTableCompartment 

func (b *InMemoryBackend) ChangeTableCompartment(ref, ifMatch string, in changeCompartmentIn) (string, error)

ChangeTableCompartment moves a table to another compartment.

func (*InMemoryBackend) Compartments 

func (b *InMemoryBackend) Compartments() []string

Compartments lists the distinct compartments that hold tables.

func (*InMemoryBackend) CreateIndex 

func (b *InMemoryBackend) CreateIndex(ref string, in createIndexIn) (string, error)

CreateIndex adds a secondary index to a table and returns its work request id.

func (*InMemoryBackend) CreateTable 

func (b *InMemoryBackend) CreateTable(in createTableIn) (string, error)

CreateTable creates a table from a CREATE TABLE statement and returns its work request id.

func (*InMemoryBackend) DeleteIndex 

func (b *InMemoryBackend) DeleteIndex(ref, name, compartment string, ifExists bool) (string, error)

DeleteIndex removes an index; ifExists turns a missing index into a no-op (empty work request id).

func (*InMemoryBackend) DeleteRow 

func (b *InMemoryBackend) DeleteRow(
	ref, compartment string,
	key []string,
	ifMatch string,
	returnRow bool,
) (DeleteRowResult, error)

DeleteRow removes one row by primary key.

func (*InMemoryBackend) DeleteTable 

func (b *InMemoryBackend) DeleteTable(ref, compartment, ifMatch string, ifExists bool) (string, error)

DeleteTable drops a table; ifExists turns a missing table into a no-op (empty work request id).

func (*InMemoryBackend) GetIndex 

func (b *InMemoryBackend) GetIndex(ref, name, compartment string) (IndexWire, error)

GetIndex returns one index.

func (*InMemoryBackend) GetRow 

func (b *InMemoryBackend) GetRow(ref, compartment string, key []string, consistency string) (RowResult, string, error)

GetRow reads one row by primary key.

func (*InMemoryBackend) GetTable 

func (b *InMemoryBackend) GetTable(ref, compartment string) (TableWire, string, error)

GetTable returns one table and its etag.

func (*InMemoryBackend) GetWorkRequest 

func (b *InMemoryBackend) GetWorkRequest(id string) (WorkRequestWire, error)

GetWorkRequest returns one work request.

func (*InMemoryBackend) ListIndexes 

func (b *InMemoryBackend) ListIndexes(ref, compartment, name, state string, o ListOpts) (page.Page[IndexWire], error)

ListIndexes lists the indexes of a table.

func (*InMemoryBackend) ListTableUsage 

func (b *InMemoryBackend) ListTableUsage(
	ref, compartment, start, end string,
	o ListOpts,
) (page.Page[UsageWire], error)

ListTableUsage reports per-minute consumption recorded for a table.

func (*InMemoryBackend) ListTables 

func (b *InMemoryBackend) ListTables(
	compartment, name, state string,
	o ListOpts,
) (page.Page[TableWire], TableList, error)

ListTables lists tables of a compartment.

func (*InMemoryBackend) ListWorkRequests 

func (b *InMemoryBackend) ListWorkRequests(compartment string, o ListOpts) (page.Page[WorkRequestWire], error)

ListWorkRequests lists the work requests of a compartment, optionally for one resource.

func (*InMemoryBackend) PrepareStatement 

func (b *InMemoryBackend) PrepareStatement(compartment, statement string, withPlan bool) (PreparedStatement, error)

PrepareStatement validates a SELECT against its table and returns an opaque prepared form.

func (*InMemoryBackend) Query 

func (b *InMemoryBackend) Query(in queryIn, limit int, token string) (page.Page[map[string]any], usageWire, error)

Query runs a SELECT statement and returns one page of results.

func (*InMemoryBackend) Reset 

func (b *InMemoryBackend) Reset()

Reset clears all state.

func (*InMemoryBackend) Restore 

func (b *InMemoryBackend) Restore(ctx context.Context, data []byte) error

Restore loads backend state from a snapshot.

func (*InMemoryBackend) SetClock 

func (b *InMemoryBackend) SetClock(now func() time.Time)

SetClock injects the time source used for lifecycle transitions and TTL expiry.

func (*InMemoryBackend) SetCompartmentChecker 

func (b *InMemoryBackend) SetCompartmentChecker(fn func(string) bool)

SetCompartmentChecker validates compartmentId arguments against another service (OCI Identity).

func (*InMemoryBackend) SetTransition 

func (b *InMemoryBackend) SetTransition(d time.Duration)

SetTransition sets how long CREATING, UPDATING and DELETING states last.

func (*InMemoryBackend) Snapshot 

func (b *InMemoryBackend) Snapshot(ctx context.Context) []byte

Snapshot serialises the backend state, including registered API keys.

func (*InMemoryBackend) SummarizeStatement 

func (b *InMemoryBackend) SummarizeStatement(compartment, statement string) (StatementSummary, error)

SummarizeStatement classifies a statement and reports syntax errors without executing anything.

func (*InMemoryBackend) Sweep 

func (b *InMemoryBackend) Sweep()

Sweep applies lifecycle transitions against the backend clock.

func (*InMemoryBackend) SweepRows 

func (b *InMemoryBackend) SweepRows()

SweepRows removes expired rows from every table.

func (*InMemoryBackend) UpdateRow 

func (b *InMemoryBackend) UpdateRow(ref, ifMatch string, in updateRowIn) (UpdateRowResult, error)

UpdateRow puts a row into a table.

func (*InMemoryBackend) UpdateTable 

func (b *InMemoryBackend) UpdateTable(ref, ifMatch string, in updateTableIn) (string, error)

UpdateTable alters a table's schema, limits or tags.

func (*InMemoryBackend) WorkRequestExists 

func (b *InMemoryBackend) WorkRequestExists(id string) error

WorkRequestExists reports whether a work request exists (its error list is always empty).

func (*InMemoryBackend) WorkRequestLogs 

func (b *InMemoryBackend) WorkRequestLogs(id string, o ListOpts) (page.Page[wrLogWire], error)

WorkRequestLogs returns the log entries of a work request.

type Index 

type Index struct {
	Created      time.Time  `json:"created"`
	TransitionAt *time.Time `json:"transitionAt,omitempty"`
	Name         string     `json:"name"`
	State        string     `json:"state"`
	Keys         []IndexKey `json:"keys"`
}

Index is a secondary index on a table.

type IndexKey 

type IndexKey struct {
	Column   string `json:"column"`
	JSONPath string `json:"jsonPath,omitempty"`
	JSONType string `json:"jsonType,omitempty"`
}

IndexKey is one key of a secondary index.

type IndexWire 

type IndexWire struct {
	Name           string         `json:"name"`
	CompartmentID  string         `json:"compartmentId,omitempty"`
	TableName      string         `json:"tableName,omitempty"`
	TableID        string         `json:"tableId,omitempty"`
	LifecycleState string         `json:"lifecycleState"`
	Keys           []indexKeyWire `json:"keys"`
}

IndexWire is the full index representation.

type Limits 

type Limits struct {
	Mode       string `json:"mode"`
	ReadUnits  int    `json:"readUnits"`
	WriteUnits int    `json:"writeUnits"`
	StorageGB  int    `json:"storageGb"`
}

Limits are a table's throughput and storage limits.

type ListOpts 

type ListOpts struct {
	SortBy string
	Order  string
	Page   string
	Limit  int
}

ListOpts carries the shared list query parameters.

type PreparedStatement 

type PreparedStatement struct {
	QueryPlan any       `json:"queryPlan,omitempty"`
	Statement string    `json:"statement"`
	Usage     usageWire `json:"usage"`
}

PreparedStatement is the PrepareStatement response body.

type Provider 

type Provider struct{}

Provider implements service.Provider for OCI NoSQL. It runs on its own listener (see Handler.StartWorker) and never matches on the shared AWS router.

func (*Provider) Init 

func (p *Provider) Init(ctx *service.AppContext) (service.Registerable, error)

Init creates the backend and handler; the port is bound in StartWorker.

func (*Provider) Name 

func (p *Provider) Name() string

Name returns the service provider name.

type QueryResult 

type QueryResult struct {
	Items []map[string]any `json:"items"`
	Usage usageWire        `json:"usage"`
}

QueryResult is the Query response body.

type Row 

type Row struct {
	Expire  *time.Time      `json:"expire,omitempty"`
	Version string          `json:"version"`
	Value   json.RawMessage `json:"value"`
}

Row is one stored table row.

type RowResult 

type RowResult struct {
	TimeOfExpiration *time.Time      `json:"timeOfExpiration,omitempty"`
	Value            json.RawMessage `json:"value"`
	Usage            usageWire       `json:"usage"`
}

RowResult is the GetRow response body.

type Settings 

type Settings struct {
	Port int `` //nolint:lll // config struct tags are intentionally verbose
	/* 187-byte string literal not displayed */
	EnforceAuth bool `` //nolint:lll // config struct tags are intentionally verbose
	/* 221-byte string literal not displayed */
}

Settings holds service-level configuration, embedded in the root CLI as CLI.OCINoSQL.

func DefaultSettings 

func DefaultSettings() Settings

DefaultSettings returns the settings used when no ConfigProvider is available.

type StatementSummary 

type StatementSummary struct {
	SyntaxError   *string `json:"syntaxError,omitempty"`
	Operation     string  `json:"operation,omitempty"`
	TableName     string  `json:"tableName,omitempty"`
	IndexName     string  `json:"indexName,omitempty"`
	IsIfExists    bool    `json:"isIfExists"`
	IsIfNotExists bool    `json:"isIfNotExists"`
}

StatementSummary is the SummarizeStatement response body.

type Table 

type Table struct {
	TimeCreated   time.Time         `json:"timeCreated"`
	TimeUpdated   time.Time         `json:"timeUpdated"`
	Tags          Tags              `json:"tags"`
	TransitionAt  *time.Time        `json:"transitionAt,omitempty"`
	Rows          map[string]*Row   `json:"rows,omitempty"`
	Indexes       map[string]*Index `json:"indexes,omitempty"`
	Usage         map[int64]*Usage  `json:"usage,omitempty"`
	Identity      *Identity         `json:"identity,omitempty"`
	CompartmentID string            `json:"compartmentId"`
	ID            string            `json:"id"`
	Name          string            `json:"name"`
	State         string            `json:"state"`
	DDL           string            `json:"ddl"`
	Etag          string            `json:"etag"`
	Columns       []Column          `json:"columns"`
	PrimaryKey    []string          `json:"primaryKey"`
	ShardKey      []string          `json:"shardKey"`
	Limits        Limits            `json:"limits"`
	TTLHours      int               `json:"ttlHours"`
	RowSeq        int64             `json:"rowSeq"`
	AutoReclaim   bool              `json:"autoReclaimable,omitempty"`
}

Table is a NoSQL table with its rows and indexes.

type TableList 

type TableList struct {
	Items                  []TableWire `json:"items"`
	AutoReclaimableTables  int         `json:"autoReclaimableTables"`
	OnDemandCapacityTables int         `json:"onDemandCapacityTables"`
}

TableList is the ListTables result body.

type TableWire 

type TableWire struct {
	TimeCreated       time.Time                 `json:"timeCreated"`
	TimeUpdated       time.Time                 `json:"timeUpdated"`
	Schema            *schemaWire               `json:"schema,omitempty"`
	FreeformTags      map[string]string         `json:"freeformTags,omitempty"`
	DefinedTags       map[string]map[string]any `json:"definedTags,omitempty"`
	DDLStatement      string                    `json:"ddlStatement,omitempty"`
	ID                string                    `json:"id"`
	CompartmentID     string                    `json:"compartmentId"`
	Name              string                    `json:"name"`
	LifecycleState    string                    `json:"lifecycleState"`
	SchemaState       string                    `json:"schemaState"`
	TableLimits       limitsWire                `json:"tableLimits"`
	IsAutoReclaimable bool                      `json:"isAutoReclaimable"`
	IsMultiRegion     bool                      `json:"isMultiRegion"`
}

TableWire is the full table representation.

type Tags 

type Tags struct {
	FreeformTags map[string]string         `json:"freeformTags,omitempty"`
	DefinedTags  map[string]map[string]any `json:"definedTags,omitempty"`
}

Tags are the shared freeform and defined tag sets of a resource.

type UpdateRowResult 

type UpdateRowResult struct {
	Version         *string         `json:"version"`
	ExistingVersion *string         `json:"existingVersion,omitempty"`
	GeneratedValue  *string         `json:"generatedValue,omitempty"`
	ExistingValue   json.RawMessage `json:"existingValue,omitempty"`
	Usage           usageWire       `json:"usage"`
}

UpdateRowResult is the UpdateRow response body.

type Usage 

type Usage struct {
	Reads  int `json:"reads"`
	Writes int `json:"writes"`
}

Usage is the consumption recorded for one minute.

type UsageWire 

type UsageWire struct {
	TimeStarted          time.Time `json:"timeStarted"`
	SecondsInPeriod      int       `json:"secondsInPeriod"`
	ReadUnits            int       `json:"readUnits"`
	WriteUnits           int       `json:"writeUnits"`
	StorageInGBs         int       `json:"storageInGBs"`
	ReadThrottleCount    int       `json:"readThrottleCount"`
	WriteThrottleCount   int       `json:"writeThrottleCount"`
	StorageThrottleCount int       `json:"storageThrottleCount"`
}

UsageWire is one ListTableUsage item.

type WorkRequest 

type WorkRequest struct {
	Accepted      time.Time `json:"accepted"`
	FinishAt      time.Time `json:"finishAt"`
	ID            string    `json:"id"`
	Operation     string    `json:"operation"`
	CompartmentID string    `json:"compartmentId"`
	EntityID      string    `json:"entityId"`
	Action        string    `json:"action"`
	Seq           int64     `json:"seq"`
}

WorkRequest records an asynchronous admin operation.

type WorkRequestWire 

type WorkRequestWire struct {
	TimeAccepted    time.Time        `json:"timeAccepted"`
	TimeStarted     *time.Time       `json:"timeStarted,omitempty"`
	TimeFinished    *time.Time       `json:"timeFinished,omitempty"`
	OperationType   string           `json:"operationType"`
	Status          string           `json:"status"`
	ID              string           `json:"id"`
	CompartmentID   string           `json:"compartmentId"`
	Resources       []wrResourceWire `json:"resources"`
	PercentComplete float32          `json:"percentComplete"`
}

WorkRequestWire is the wire form of a work request.

Source Files

View all Source files

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.