frogodb

package
v1.2.1 Latest Latest
Warning

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

 Go to latest Published: May 14, 2026 License: GPL-3.0 Imports: 9 Imported by: 0

README

db/frogodb

Import path: github.com/InsideGallery/core/db/frogodb

Package frogodb provides FrogoDB smart-client configuration, connection ownership, and core-owned record operation types. New code should use DatabaseClient or the Database interface when callers should not depend directly on github.com/FrogoAI/fdb-client/pkg/client.

Main APIs

  • ConnectionConfig configures seeds, timeouts, pool sizes, error-rate limits, and multiplexing.
  • DefaultConnectionConfig(seeds...) returns the package defaults.
  • GetConnectionConfigFromEnv(prefix) reads config from prefix, defaulting to FDB when prefix is empty.
  • NewDatabase(config) creates a DatabaseClient.
  • Database is the core-owned contract for ping, put, get, delete, count, and close operations.
  • Key, PutOptions, GetOptions, DeleteOptions, CountOptions, and WriteOptions describe record operations without exposing FrogoDB SDK option types.
  • RecordResult reports whether a record was found. Missing records return Found: false without an error.
  • ConnectionRegistry owns named low-level clients for explicit application composition.
  • NewConnection, NewConnectionFromEnv, Set, Get, and Default expose or manage low-level SDK clients for compatibility.

Usage

package example

import (
	"context"

	"github.com/InsideGallery/core/db/frogodb"
)

func putRecord(ctx context.Context) (err error) {
	database, err := frogodb.NewDatabase(frogodb.DefaultConnectionConfig("localhost:3000"))
	if err != nil {
		return err
	}
	defer func() {
		if closeErr := database.Close(); err == nil {
			err = closeErr
		}
	}()

	_, err = database.PutRecord(ctx, frogodb.PutOptions{
		Key: frogodb.Key{
			Namespace: "app",
			Set:       "profiles",
			Value:     "profile:1",
		},
		Bins: map[string]any{"name": "Ada"},
	})

	return err
}

Configuration And Operations

Environment variables use names such as FDB_SEEDS, FDB_CONNECTION_TIMEOUT, FDB_IDLE_TIMEOUT, FDB_POOL_SIZE_PER_NODE, FDB_MAX_CONNS_PER_NODE, and FDB_MULTIPLEXING. CountOptions.AllNodes selects the all-node count path. Call Close on DatabaseClient or ConnectionRegistry during shutdown.

Documentation

Overview

Package frogodb provides FrogoDB connection and record helpers.

New code should use explicit connection ownership and core-owned operation shapes: 

import "github.com/InsideGallery/core/db/frogodb"

store, err := frogodb.NewDatabase(frogodb.DefaultConnectionConfig("localhost:3000"))

Prefer Database, DatabaseClient, Key, PutOptions, GetOptions, DeleteOptions, Record, RecordResult, and Result when consumer code should not depend directly on the FrogoDB client package.

Compatibility: NewConnection, NewConnectionFromEnv, Set, Get, and Default expose the FrogoDB SDK-shaped client for advanced callers and existing low-level integration points.

Index

Constants

View Source 
const (
	// EnvPrefix is the default environment prefix for FrogoDB configuration.
	EnvPrefix = "FDB"
)

Variables

View Source 
var ErrConnectionConfigIsNotSet = errors.New("connection config is not set")

ErrConnectionConfigIsNotSet reports that FrogoDB connection configuration is missing.

View Source 
var ErrConnectionIsNotSet = errors.New("connection is not set")

ErrConnectionIsNotSet reports that no FrogoDB client is registered.

Functions

func Default deprecated 

func Default(names ...string) (*fdbclient.Client, error)

Default returns the package-level FrogoDB client.

Deprecated: use NewConnection or ConnectionRegistry.Default with explicit config.

func Get deprecated 

func Get(name string) (*fdbclient.Client, error)

Get returns the package-level FrogoDB client.

Deprecated: use ConnectionRegistry.Get on an explicit registry.

func NewConnection 

func NewConnection(config *ConnectionConfig) (*fdbclient.Client, error)

NewConnection creates a FrogoDB client from explicit config.

func NewConnectionFromEnv 

func NewConnectionFromEnv(prefix string) (*fdbclient.Client, error)

NewConnectionFromEnv creates a FrogoDB client from an explicit environment prefix.

func Set deprecated 

func Set(name string, client *fdbclient.Client)

Set stores the package-level FrogoDB client.

Deprecated: use ConnectionRegistry.Set on an explicit registry.

Types

type ConnectionConfig 

type ConnectionConfig struct {
	Seeds                    []string      `env:"_SEEDS" envDefault:"localhost:3000" envSeparator:","`
	TendInterval             time.Duration `env:"_TEND_INTERVAL" envDefault:"10ms"`
	ConnectionTimeout        time.Duration `env:"_CONNECTION_TIMEOUT" envDefault:"5s"`
	IdleTimeout              time.Duration `env:"_IDLE_TIMEOUT" envDefault:"55s"`
	PoolSizePerNode          int           `env:"_POOL_SIZE_PER_NODE" envDefault:"64"`
	MaxConnsPerNode          int           `env:"_MAX_CONNS_PER_NODE" envDefault:"256"`
	MaxErrorRate             int           `env:"_MAX_ERROR_RATE" envDefault:"100"`
	ErrorRateWindow          time.Duration `env:"_ERROR_RATE_WINDOW" envDefault:"1s"`
	Multiplexing             bool          `env:"_MULTIPLEXING" envDefault:"false"`
	MultiplexConnsPerNode    int           `env:"_MULTIPLEX_CONNS_PER_NODE" envDefault:"0"`
	MultiplexMinConnsPerNode int           `env:"_MULTIPLEX_MIN_CONNS_PER_NODE" envDefault:"0"`
}

ConnectionConfig contains FrogoDB client connection settings.

func DefaultConnectionConfig 

func DefaultConnectionConfig(seeds ...string) *ConnectionConfig

DefaultConnectionConfig returns FrogoDB connection defaults for the supplied seed addresses.

func GetConnectionConfigFromEnv 

func GetConnectionConfigFromEnv(prefix string) (*ConnectionConfig, error)

GetConnectionConfigFromEnv returns FrogoDB config from the supplied environment prefix.

type ConnectionRegistry 

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

ConnectionRegistry owns FrogoDB clients for explicit application composition.

func NewConnectionRegistry 

func NewConnectionRegistry() *ConnectionRegistry

NewConnectionRegistry creates an isolated FrogoDB connection registry.

func (*ConnectionRegistry) Close 

func (r *ConnectionRegistry) Close() error

Close closes all clients stored in this registry and clears it.

func (*ConnectionRegistry) Default 

func (r *ConnectionRegistry) Default(name string, config *ConnectionConfig) (*fdbclient.Client, error)

Default returns or creates a registry-scoped FrogoDB client from explicit config.

func (*ConnectionRegistry) Get 

func (r *ConnectionRegistry) Get(name string) (*fdbclient.Client, error)

Get returns a FrogoDB client from this registry.

func (*ConnectionRegistry) Set 

func (r *ConnectionRegistry) Set(name string, client *fdbclient.Client)

Set stores a FrogoDB client in this registry.

type CountOptions 

type CountOptions struct {
	Namespace string
	Set       string
	AllNodes  bool
}

CountOptions is the core-owned input for counting records.

type Database 

type Database interface {
	Ping(ctx context.Context) error
	PutRecord(ctx context.Context, options PutOptions) (Result, error)
	GetRecord(ctx context.Context, options GetOptions) (RecordResult, error)
	DeleteRecord(ctx context.Context, options DeleteOptions) (Result, error)
	CountRecords(ctx context.Context, options CountOptions) (Result, error)
	Close() error
}

Database is the core-owned FrogoDB contract for new consumers.

type DatabaseClient 

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

DatabaseClient wraps the FrogoDB smart client behind core-owned operation inputs and results.

func DefaultDatabase 

func DefaultDatabase(names ...string) (*DatabaseClient, error)

DefaultDatabase returns the default FrogoDB client behind the core-owned DatabaseClient API.

func NewDatabase 

func NewDatabase(config *ConnectionConfig) (*DatabaseClient, error)

NewDatabase creates a FrogoDB database client from core-owned config.

func WrapClient 

func WrapClient(client *fdbclient.Client) *DatabaseClient

WrapClient adapts an existing FrogoDB client to DatabaseClient.

func (*DatabaseClient) Client 

func (c *DatabaseClient) Client() *fdbclient.Client

Client returns the wrapped FrogoDB smart client for advanced operations.

func (*DatabaseClient) Close 

func (c *DatabaseClient) Close() error

Close closes the FrogoDB client.

func (*DatabaseClient) CountRecords 

func (c *DatabaseClient) CountRecords(ctx context.Context, options CountOptions) (Result, error)

CountRecords counts records through a core-owned input and result shape.

func (*DatabaseClient) DeleteRecord 

func (c *DatabaseClient) DeleteRecord(ctx context.Context, options DeleteOptions) (Result, error)

DeleteRecord deletes a record through a core-owned input and result shape.

func (*DatabaseClient) GetRecord 

func (c *DatabaseClient) GetRecord(ctx context.Context, options GetOptions) (RecordResult, error)

GetRecord reads a record through a core-owned input and result shape.

func (*DatabaseClient) Ping 

func (c *DatabaseClient) Ping(ctx context.Context) error

Ping verifies FrogoDB connectivity.

func (*DatabaseClient) PutRecord 

func (c *DatabaseClient) PutRecord(ctx context.Context, options PutOptions) (Result, error)

PutRecord writes a record through a core-owned input and result shape.

type DeleteOptions 

type DeleteOptions struct {
	Key   Key
	Write WriteOptions
}

DeleteOptions is the core-owned input for deleting a record.

type GetOptions 

type GetOptions struct {
	Key      Key
	BinNames []string
}

GetOptions is the core-owned input for reading a record.

type Key 

type Key struct {
	Namespace string
	Set       string
	Value     string
}

Key is a core-owned FrogoDB record identity.

type PutOptions 

type PutOptions struct {
	Key   Key
	Bins  map[string]any
	Write WriteOptions
}

PutOptions is the core-owned input for writing a record.

type Record 

type Record struct {
	Key        Key
	Bins       map[string]any
	Generation uint32
}

Record is the core-owned FrogoDB record result.

type RecordResult 

type RecordResult struct {
	Found  bool
	Record Record
}

RecordResult reports a record lookup result.

type Result 

type Result struct {
	Affected int64
	Deleted  bool
}

Result reports a write/delete/count operation result.

type WriteOptions 

type WriteOptions struct {
	TTLSeconds   uint32
	Generation   uint32
	MergeBins    bool
	ReplaceBins  bool
	CreateOnly   bool
	Replace      bool
	PreserveTTL  bool
	ClearTTL     bool
	CommitMaster bool
}

WriteOptions is a core-owned subset of FrogoDB write behavior.

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.