geode

package module
v0.1.16 Latest Latest
Warning

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

 Go to latest Published: Mar 31, 2026 License: Apache-2.0 Imports: 28 Imported by: 0

README

Geode Go Client Library

A Go database/sql driver for the Geode graph database.

Features

  • Full database/sql driver implementation
  • Dual transport support: QUIC (default) and gRPC
  • Protobuf wire protocol
  • TLS 1.3 security
  • Connection pooling via database/sql
  • Prepared statements
  • Transaction support
  • Context cancellation and timeouts
  • Rich error types with ISO/IEC 39075 status codes

Installation

go get geodedb.com/geode

Usage

package main

import (
    "context"
    "database/sql"
    "log"
    "time"

    _ "geodedb.com/geode"
)

func main() {
    // Connect via QUIC (default)
    db, err := sql.Open("geode", "quic://localhost:3141?ca=/path/to/ca.crt")
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    // Or connect via gRPC
    // db, err := sql.Open("geode", "grpc://localhost:50051?ca=/path/to/ca.crt")

    // Configure connection pool
    db.SetMaxOpenConns(10)
    db.SetMaxIdleConns(5)

    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    // Execute a query
    rows, err := db.QueryContext(ctx, "MATCH (n:Person) RETURN n.name LIMIT 10")
    if err != nil {
        log.Fatal(err)
    }
    defer rows.Close()

    for rows.Next() {
        var name string
        if err := rows.Scan(&name); err != nil {
            log.Fatal(err)
        }
        log.Println(name)
    }
}

DSN Format

Note: See geode/docs/DSN.md for the complete DSN specification.

The driver supports multiple DSN formats with scheme-based transport selection:

quic://host:port?options     # QUIC transport (recommended)
grpc://host:port?options     # gRPC transport
host:port?options            # QUIC transport (scheme-less)
host:port
host
Transport Schemes
Scheme Transport Default Port Description
quic:// QUIC 3141 High-performance UDP-based transport
grpc:// gRPC 50051 Standard gRPC over HTTP/2
(none) QUIC 3141 Scheme-less defaults to QUIC
IPv6 Support

IPv6 addresses are fully supported:

quic://[::1]:3141
grpc://[2001:db8::1]:50051
[::1]:3141
Options
Option Description Default
page_size Results page size 1000
hello_name Client name for HELLO geode-go
hello_ver Client version for HELLO 0.1
conformance GQL conformance level min
ca Path to CA certificate (must exist; no fallback)
cert Path to client certificate (mTLS)
key Path to client key (mTLS)
insecure_tls_skip_verify Skip TLS verification (testing only) false
tls Enable/disable TLS (0 or false to disable) enabled
user/username Authentication username
pass/password Authentication password
Environment Variables
Variable Description
GEODE_HOST Default host
GEODE_PORT Default port
GEODE_TLS_CA Default CA certificate path

Transactions

tx, err := db.BeginTx(ctx, nil)
if err != nil {
    log.Fatal(err)
}

_, err = tx.ExecContext(ctx, "CREATE (n:Person {name: 'Alice'})")
if err != nil {
    tx.Rollback()
    log.Fatal(err)
}

if err := tx.Commit(); err != nil {
    log.Fatal(err)
}

Prepared Statements

stmt, err := db.PrepareContext(ctx, "MATCH (n:Person {name: ?}) RETURN n")
if err != nil {
    log.Fatal(err)
}
defer stmt.Close()

rows, err := stmt.QueryContext(ctx, "Alice")
// ...

Error Handling

The driver provides rich error types:

import "geodedb.com/geode"

rows, err := db.QueryContext(ctx, "INVALID QUERY")
if err != nil {
    var derr *geode.DriverError
    if errors.As(err, &derr) {
        log.Printf("Code: %s, Message: %s", derr.Code, derr.Message)
        if derr.IsRetryable() {
            // Retry the operation
        }
    }
}

Security Limits

  • Inbound protocol frames are capped at 32MB to prevent memory exhaustion. Oversized frames are rejected.

Unicode Utilities

Helper functions for Unicode conversion:

import "geodedb.com/geode"

// UTF-8 to UTF-16
utf16 := geode.Utf8ToUtf16("Hello 🌍")

// UTF-16 to UTF-8
utf8 := geode.Utf16ToUtf8(utf16)

// WTF-8 lossy decode (replaces invalid sequences with U+FFFD)
safe := geode.Wtf8Lossy([]byte{0x61, 0x80, 0x62})

Testing

# Unit tests (no server required)
go test -v -short ./...

# Integration tests with manual server (QUIC)
GEODE_TEST_DSN="quic://localhost:3141?insecure_tls_skip_verify=true" go test -v ./...

# Integration tests with manual server (gRPC)
GEODE_TEST_DSN="grpc://localhost:50051?tls=0" go test -v ./...

# Docker-based integration tests (recommended)
go test -v -tags=integration ./...

# Docker integration tests with custom image
GEODE_IMAGE="myregistry/geode:tag" go test -v -tags=integration ./...

# Unit benchmarks (no server required)
go test -bench=. -benchmem ./...

# Docker-based benchmarks
go test -tags=integration -bench=BenchmarkDocker -benchmem ./...

# Fuzzing
go test -fuzz=FuzzParseDSN -fuzztime=30s
Docker Integration Tests

The Docker-based integration tests provide comprehensive coverage using testcontainers-go. They automatically:

  • Pull and start a Geode container from geodedb/geode:latest
  • Run a full test suite covering CRUD operations, transactions, queries, and more
  • Clean up after tests complete

Test categories include:

  • Basic Operations: Ping, simple queries, parameterized queries
  • Node CRUD: Create, read, update, delete operations
  • Relationships: Creating and traversing relationships
  • Transactions: Commit, rollback, multi-operation transactions
  • Query Operations: WHERE, ORDER BY, LIMIT, SKIP
  • Aggregations: COUNT, SUM, AVG, MIN, MAX
  • Error Handling: Syntax errors, non-existent properties
  • Prepared Statements: Parameterized query reuse
  • Concurrent Access: Connection pooling under load
  • Data Types: Null, lists, maps
  • Social Network Fixtures: Complex relationship queries

QUIC Performance Tuning

The Go client uses quic-go for QUIC transport. For optimal throughput on high-bandwidth connections, configure the following system-level optimizations.

UDP Buffer Sizes

Increase the maximum UDP buffer size to ~7MB for high-throughput transfers:

Linux:

sudo sysctl -w net.core.rmem_max=7340032
sudo sysctl -w net.core.wmem_max=7340032

# Persist across reboots
echo "net.core.rmem_max=7340032" | sudo tee -a /etc/sysctl.d/99-geode-quic.conf
echo "net.core.wmem_max=7340032" | sudo tee -a /etc/sysctl.d/99-geode-quic.conf

BSD/macOS:

sudo sysctl -w kern.ipc.maxsockbuf=8441037
Generic Segmentation Offload (GSO)

GSO batches UDP packets to reduce syscall overhead. It's automatically enabled on Linux 4.18+.

  • No configuration required - enabled automatically
  • To disable (not recommended): Set QUIC_GO_DISABLE_GSO=true environment variable
  • Requirements: Linux kernel 4.18+
Path MTU Discovery (DPLPMTUD)

DPLPMTUD probes for optimal MTU size, reducing per-packet overhead. It's enabled by default in the client.

  • Sends fewer than 10 probe packets over a connection's lifetime
  • Particularly beneficial on paths supporting MTUs larger than 1200 bytes
  • Configured via quic.Config.DisablePathMTUDiscovery (default: false)

Wire Protocol

The driver uses Protocol Buffers (protobuf) for wire encoding over both QUIC and gRPC transports.

QUIC Transport
  • Length-prefixed protobuf messages (4-byte big-endian length prefix)
  • Single bidirectional stream per connection
  • TLS 1.3 with ALPN protocol geode/1
gRPC Transport
  • Standard gRPC over HTTP/2
  • Streaming responses for query execution
  • TLS 1.3 by default (can be disabled with tls=0 for testing)

Go Module Configuration

This module uses a vanity import path (geodedb.com/geode) that redirects to the GitLab repository. The standard go get command works out of the box:

go get geodedb.com/geode
Private/Self-Hosted GitLab

If you're using a private GitLab instance or need to configure authentication:

# Configure Git to use SSH for GitLab
git config --global url."[email protected]:".insteadOf "https://gitlab.com/"

# Or use a personal access token
git config --global url."https://oauth2:${GITLAB_TOKEN}@gitlab.com/".insteadOf "https://gitlab.com/"
GOPROXY Configuration

The module works with the default Go proxy (proxy.golang.org). For air-gapped environments or private proxies:

# Use direct fetching (bypasses proxy)
GOPROXY=direct go get geodedb.com/geode

# Use a private proxy
GOPROXY=https://your-proxy.example.com,direct go get geodedb.com/geode
GOPRIVATE / GONOSUMDB

If you need to bypass the checksum database or proxy for this module:

# Add to your shell profile or CI environment
export GOPRIVATE=geodedb.com
export GONOSUMDB=geodedb.com

# Or configure globally
go env -w GOPRIVATE=geodedb.com
go env -w GONOSUMDB=geodedb.com
GitLab Go Proxy (Self-Hosted)

GitLab Premium includes a built-in Go proxy. To use it:

  1. Enable the Go proxy in GitLab Admin > Settings > CI/CD
  2. Configure your Go environment:
export GOPROXY="https://gitlab.example.com/api/v4/projects/${PROJECT_ID}/packages/go,https://proxy.golang.org,direct"
export GONOSUMDB="gitlab.example.com/*"
Verifying Installation

After installation, verify the module:

go list -m geodedb.com/geode
# Should output: geodedb.com/geode v0.x.x

License

See LICENSE for details.

Documentation

Overview

Package geode provides a database/sql driver for the Geode graph database.

The driver connects to Geode servers over QUIC with TLS 1.3 and implements the full GQL (Graph Query Language) specification.

Usage

Import the driver anonymously to register it with database/sql: 

import (
    "database/sql"
    _ "geodedb.com/geode"
)

db, err := sql.Open("geode", "localhost:3141")

DSN Format

The driver supports multiple DSN formats: 

quic://host:port?options (QUIC transport - recommended)
grpc://host:port?options (gRPC transport)
host:port?options (defaults to QUIC)
host:port
host

Options:

  • page_size: Results page size (default: 1000)
  • hello_name: Client name (default: "geode-go")
  • hello_ver: Client version (default: "0.1")
  • conformance: GQL conformance level (default: "min")
  • ca: Path to CA certificate
  • cert: Path to client certificate (for mTLS)
  • key: Path to client key (for mTLS)
  • insecure: Skip TLS verification (testing only)
  • connect_timeout: Connection timeout in seconds (default: 0 = no timeout)

Environment variables:

  • GEODE_HOST: Default host if DSN is empty
  • GEODE_PORT: Default port if not specified
  • GEODE_TLS_CA: Default CA certificate path

Example 

db, err := sql.Open("geode", "quic://localhost:3141?page_size=500")
if err != nil {
    log.Fatal(err)
}
defer db.Close()

rows, err := db.QueryContext(ctx, "MATCH (n:Person) RETURN n.name LIMIT 10")
if err != nil {
    log.Fatal(err)
}
defer rows.Close()

for rows.Next() {
    var name string
    if err := rows.Scan(&name); err != nil {
        log.Fatal(err)
    }
    fmt.Println(name)
}

Index

Constants

View Source 
const (
	// DefaultPort is the default Geode server port for QUIC.
	DefaultPort = "3141"

	// DefaultGRPCPort is the default Geode server port for gRPC.
	DefaultGRPCPort = "50051"

	// DefaultPageSize is the default number of rows per page.
	DefaultPageSize = 1000

	// MaxPageSize is the maximum allowed page size.
	// This prevents potential DoS via memory exhaustion with extremely large page sizes.
	MaxPageSize = 100000

	// DefaultHelloName is the default client name sent in HELLO.
	DefaultHelloName = "geode-go"

	// DefaultHelloVersion is the default client version sent in HELLO.
	DefaultHelloVersion = "0.1"

	// DefaultConformance is the default GQL conformance level.
	DefaultConformance = "min"

	// MaxQueryLength is the maximum allowed query length.
	MaxQueryLength = 1 << 20 // 1MB

)
View Source 
const (
	StatusSuccess          = "00000" // Successful completion
	StatusNoData           = "02000" // No data
	StatusWarning          = "01000" // Warning
	StatusTransactionState = "25000" // Invalid transaction state
	StatusAuth             = "28000" // Authorization error
	StatusSerialization    = "40001" // Serialization failure (retryable)
	StatusDeadlock         = "40502" // Transaction deadlock (retryable)
	StatusSyntax           = "42000" // Syntax error
	StatusConstraint       = "23000" // Constraint violation
	StatusDuplicate        = "42P07" // Duplicate object
	StatusInvalidParam     = "22023" // Invalid parameter value
	StatusSystem           = "58000" // System error
)

ISO/IEC 39075 status class constants.

View Source 
const (
	// DefaultMaxOpenConns is the default maximum number of open connections.
	// Matches typical parallel worker counts (e.g. 8 chunk workers).
	DefaultMaxOpenConns = 16

	// DefaultMaxIdleConns is the default maximum number of idle connections.
	DefaultMaxIdleConns = 4

	// DefaultConnMaxLifetime is the default maximum lifetime of a connection.
	// Prevents connections from growing stale in long-running processes.
	DefaultConnMaxLifetime = 5 * time.Minute

	// DefaultConnMaxIdleTime is the default maximum idle time for a connection.
	// Set below QUIC's 30-second idle timeout to proactively recycle
	// connections before the server closes them.
	DefaultConnMaxIdleTime = 25 * time.Second

	// DefaultPingTimeout is the timeout for the initial ping when creating a pool.
	DefaultPingTimeout = 10 * time.Second
)

Default pool settings tuned for Geode's QUIC transport.

View Source 
const (
	// DefaultQUICPoolSize is the maximum number of QUIC connections in the pool.
	DefaultQUICPoolSize = 4
)

Default QUIC pool settings.

Variables

View Source 
var (
	ErrClosed          = errors.New("geode: connection closed")
	ErrQueryInProgress = errors.New("geode: query already in progress")
	ErrTxInProgress    = errors.New("geode: transaction already in progress")
	ErrNoTx            = errors.New("geode: no transaction in progress")
	ErrTxDone          = errors.New("geode: transaction already committed or rolled back")
	ErrStmtClosed      = errors.New("geode: statement closed")
	ErrRowsClosed      = errors.New("geode: rows closed")
	ErrBadConn         = errors.New("geode: bad connection")
	ErrInvalidState    = errors.New("geode: invalid connection state")
)

Sentinel errors for common conditions.

Functions

func IsRetryableError 

func IsRetryableError(err error) bool

IsRetryableError checks if an error is retryable.

func NewTLSConfig 

func NewTLSConfig(cfg *Config) (*tls.Config, error)

NewTLSConfig creates a TLS configuration for connecting to a Geode server.

The configuration enforces TLS 1.3 minimum and uses the ALPN protocol "geode/1". Certificate verification is always enabled unless explicitly disabled via Config.InsecureSkipVerify (which should only be used for testing).

CA certificates are loaded from (in order of precedence):

  1. Config.TLSCA (explicit path)
  2. GEODE_TLS_CA environment variable
  3. System certificate pool

If Config.TLSCert and Config.TLSKey are provided, mutual TLS (mTLS) is enabled.

func ParseTime added in v0.1.15 

func ParseTime(s string) (time.Time, error)

ParseTime parses a time string returned by the Geode server. It strips the Go monotonic clock suffix if present, then tries each supported layout in order from most specific to least specific. An error is returned for empty strings or unrecognised input.

func Retry added in v0.1.15 

func Retry(ctx context.Context, policy RetryPolicy, fn func(ctx context.Context) error) error

Retry executes fn up to policy.MaxAttempts times, retrying only when IsRetryableError returns true. Non-retryable errors and non-Geode errors are returned immediately without further attempts. Context cancellation is checked before each retry sleep.

func Utf8ToUtf16 

func Utf8ToUtf16(s string) []uint16

Utf8ToUtf16 converts a UTF-8 string to UTF-16 code units.

CANARY: REQ=REQ-GQL-UNICODE-012; FEATURE="UTF-8 -> UTF-16 Conversion"; ASPECT=ClientWrapperGo; STATUS=IMPL; TEST=TestCANARY_ClientGo_Utf8Utf16RoundTrip; OWNER=clients; UPDATED=2025-09-27

func Utf16ToUtf8 

func Utf16ToUtf8(u []uint16) string

Utf16ToUtf8 converts UTF-16 code units to a UTF-8 string.

CANARY: REQ=REQ-GQL-UNICODE-013; FEATURE="UTF-16 -> UTF-8 Conversion"; ASPECT=ClientWrapperGo; STATUS=IMPL; TEST=TestCANARY_ClientGo_Utf8Utf16RoundTrip; OWNER=clients; UPDATED=2025-09-27

func Wtf8Lossy 

func Wtf8Lossy(b []byte) string

Wtf8Lossy converts a byte slice to a UTF-8 string, replacing invalid sequences with the Unicode replacement character (U+FFFD).

CANARY: REQ=REQ-GQL-UNICODE-014; FEATURE="WTF-8 Lossy Decode"; ASPECT=ClientWrapperGo; STATUS=IMPL; TEST=TestCANARY_ClientGo_Wtf8Lossy; OWNER=clients; UPDATED=2025-09-27

Types

type ColumnInfo 

type ColumnInfo struct {
	Name string
	Type GQLType
}

ColumnInfo holds metadata about a column.

type Config 

type Config struct {
	// Transport specifies the transport protocol (QUIC or gRPC).
	Transport TransportType

	// Host is the server hostname or IP address.
	Host string

	// Port is the server port.
	Port string

	// Username for authentication.
	Username string

	// Password for authentication.
	Password string

	// PageSize is the number of rows to fetch per page.
	PageSize int

	// HelloName is the client name sent in HELLO.
	HelloName string

	// HelloVersion is the client version sent in HELLO.
	HelloVersion string

	// Conformance is the GQL conformance level.
	Conformance string

	// TLS configuration
	TLSCA   string // Path to CA certificate
	TLSCert string // Path to client certificate (for mTLS)
	TLSKey  string // Path to client private key (for mTLS)

	// TLSDisabled disables TLS entirely (plaintext gRPC, for testing only).
	TLSDisabled bool

	// InsecureSkipVerify allows skipping TLS verification (for testing only).
	// This should never be used in production.
	InsecureSkipVerify bool

	// ConnectTimeout is the maximum time to wait for a connection.
	// Zero means no timeout. This helps prevent connection storms.
	// For rate limiting, use database/sql's connection pool settings:
	//   db.SetMaxOpenConns(n) - limits concurrent connections
	//   db.SetMaxIdleConns(n) - limits idle connections
	//   db.SetConnMaxLifetime(d) - limits connection age
	//   db.SetConnMaxIdleTime(d) - limits idle time
	ConnectTimeout int // in seconds, 0 = no timeout

	// Graph is the name of the graph to select after connecting.
	// When set, the driver automatically executes
	// CREATE GRAPH IF NOT EXISTS <graph> and USE GRAPH <graph>
	// after the HELLO handshake. This ensures every pooled connection
	// targets the correct graph without manual initialization.
	Graph string
}

Config holds the configuration for a Geode connection.

func ParseDSN 

func ParseDSN(dsn string) (*Config, error)

ParseDSN parses a data source name into a Config.

See geode/docs/DSN.md for the complete DSN specification.

Supported formats:

  • quic://host:port?options (QUIC transport)
  • grpc://host:port?options (gRPC transport)
  • host:port?options (QUIC transport, scheme-less)
  • host:port (QUIC transport)
  • host (QUIC transport, uses default port)

IPv6 hosts are supported:

  • quic://[::1]:3141
  • grpc://[2001:db8::1]:50051

Supported options:

  • page_size: Results page size (default: 1000)
  • hello_name: Client name (default: "geode-go")
  • hello_ver: Client version (default: "0.1")
  • conformance: GQL conformance level (default: "min")
  • ca: Path to CA certificate
  • cert: Path to client certificate (for mTLS)
  • key: Path to client key (for mTLS)
  • insecure_tls_skip_verify: Skip TLS verification (testing only, aliases: insecure, skip_verify)
  • tls: Enable/disable TLS ("0" or "false" to disable, gRPC only)

Environment variables:

  • GEODE_HOST: Default host if DSN is empty
  • GEODE_PORT: Default port if not specified
  • GEODE_TLS_CA: Default CA certificate path

func (*Config) Addr 

func (c *Config) Addr() string

Addr returns the server address in host:port format.

func (*Config) Clone 

func (c *Config) Clone() *Config

Clone returns a deep copy of the configuration.

func (*Config) Validate 

func (c *Config) Validate() error

Validate validates the configuration.

type ConfigError 

type ConfigError struct {
	Field   string // Configuration field name
	Value   string // Invalid value
	Message string // Error message
}

ConfigError represents DSN/configuration errors.

func (*ConfigError) Error 

func (e *ConfigError) Error() string

Error implements the error interface.

func (*ConfigError) IsRetryable 

func (e *ConfigError) IsRetryable() bool

IsRetryable indicates if the operation can be retried.

func (*ConfigError) StatusClass 

func (e *ConfigError) StatusClass() string

StatusClass returns the status class.

type Conn 

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

Conn represents a connection to a Geode database.

func (*Conn) Begin deprecated 

func (c *Conn) Begin() (driver.Tx, error)

Begin starts a transaction.

Deprecated: Use BeginTx instead for explicit timeout control. This method uses a default 30-second timeout.

func (*Conn) BeginTx 

func (c *Conn) BeginTx(ctx context.Context, opts driver.TxOptions) (driver.Tx, error)

BeginTx starts a transaction with context and options.

func (*Conn) CheckNamedValue 

func (c *Conn) CheckNamedValue(nv *driver.NamedValue) error

CheckNamedValue validates a named value before use.

func (*Conn) Close 

func (c *Conn) Close() error

Close closes the connection.

func (*Conn) ExecContext 

func (c *Conn) ExecContext(ctx context.Context, query string, args []driver.NamedValue) (driver.Result, error)

ExecContext executes a query that doesn't return rows.

func (*Conn) IsValid 

func (c *Conn) IsValid() bool

IsValid returns true if the connection is still valid.

func (*Conn) Ping 

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

Ping verifies the connection is alive.

func (*Conn) Prepare deprecated 

func (c *Conn) Prepare(query string) (driver.Stmt, error)

Prepare returns a prepared statement. Note: Geode doesn't have server-side prepared statements, so this is a client-side implementation.

Deprecated: Use PrepareContext instead for explicit timeout control. This method uses a default 30-second timeout.

func (*Conn) PrepareContext 

func (c *Conn) PrepareContext(_ context.Context, query string) (driver.Stmt, error)

PrepareContext returns a prepared statement with context.

func (*Conn) QueryContext 

func (c *Conn) QueryContext(ctx context.Context, query string, args []driver.NamedValue) (driver.Rows, error)

QueryContext executes a query that returns rows.

func (*Conn) ResetSession 

func (c *Conn) ResetSession(ctx context.Context) error

ResetSession resets the session state.

type ConnState 

type ConnState int

ConnState represents the connection state. 

const (
	StateIdle ConnState = iota
	StateExecuting
	StateInTransaction
	StateFetching
	StateClosed
	StateInError
)

func (ConnState) String 

func (s ConnState) String() string

String returns a string representation of the connection state.

type Connector 

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

Connector implements driver.Connector.

func (*Connector) Config 

func (c *Connector) Config() *Config

Config returns a copy of the connector's configuration.

func (*Connector) Connect 

func (c *Connector) Connect(ctx context.Context) (driver.Conn, error)

Connect returns a new connection to the database.

For QUIC transport with a shared pool, this opens a new QUIC stream on a pooled connection rather than dialing a new QUIC connection. The HELLO handshake is performed once per underlying QUIC connection, and subsequent streams inherit the authenticated state.

func (*Connector) Driver 

func (c *Connector) Driver() driver.Driver

Driver returns the underlying Driver.

type Driver 

type Driver struct{}

Driver implements driver.Driver and driver.DriverContext.

func (*Driver) Open deprecated 

func (d *Driver) Open(name string) (driver.Conn, error)

Open opens a new connection to the database. The name is a DSN (data source name) in the format described above.

Deprecated: Use OpenConnector and Connector.Connect with an explicit context for timeout control. This method uses defaultDeprecatedMethodTimeout (30s).

func (*Driver) OpenConnector 

func (d *Driver) OpenConnector(name string) (driver.Connector, error)

OpenConnector returns a Connector for the given DSN. This allows for connection pooling with context support.

For QUIC transport, a shared connection pool is created so that multiple database/sql connections can multiplex streams over a small number of underlying QUIC connections, avoiding per-query TLS handshake overhead.

type DriverError 

type DriverError struct {
	Class      string   // ISO/IEC 39075 status class (00000, 25000, etc.)
	Subclass   string   // Status subclass
	Code       string   // Error code (US001, IllegalOrderKey, etc.)
	Message    string   // Human-readable message
	Anchor     string   // Source location in query
	Additional []string // Additional diagnostic info
	Findings   []string // Flagger findings
	// contains filtered or unexported fields
}

DriverError represents errors returned from the Geode server.

func IsDriverError 

func IsDriverError(err error) (*DriverError, bool)

IsDriverError checks if err is a DriverError and returns it.

func (*DriverError) Error 

func (e *DriverError) Error() string

Error implements the error interface.

func (*DriverError) Is 

func (e *DriverError) Is(target error) bool

Is provides errors.Is support.

func (*DriverError) IsRetryable 

func (e *DriverError) IsRetryable() bool

IsRetryable indicates if the operation can be retried.

func (*DriverError) StatusClass 

func (e *DriverError) StatusClass() string

StatusClass returns the ISO/IEC 39075 status class.

func (*DriverError) Unwrap 

func (e *DriverError) Unwrap() error

Unwrap returns the underlying cause.

type Error 

type Error interface {
	error

	// StatusClass returns ISO/IEC 39075 status class.
	StatusClass() string

	// IsRetryable indicates if the operation can be retried.
	IsRetryable() bool
}

Error is the interface for all Geode errors.

type GQLType 

type GQLType string

GQLType represents a GQL data type. 

const (
	GQLTypeInt     GQLType = "INT"
	GQLTypeFloat   GQLType = "FLOAT"
	GQLTypeString  GQLType = "STRING"
	GQLTypeBool    GQLType = "BOOL"
	GQLTypeNull    GQLType = "NULL"
	GQLTypeList    GQLType = "LIST"
	GQLTypeMap     GQLType = "MAP"
	GQLTypeNode    GQLType = "NODE"
	GQLTypeEdge    GQLType = "EDGE"
	GQLTypePath    GQLType = "PATH"
	GQLTypeUnknown GQLType = "UNKNOWN"
)

GQL type constants.

func ParseGQLType 

func ParseGQLType(s string) GQLType

ParseGQLType parses a GQL type string.

func (GQLType) GoType 

func (t GQLType) GoType() reflect.Type

GoType returns the Go reflect.Type for a GQL type.

type GRPCTransport 

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

GRPCTransport implements Transport over gRPC.

func NewGRPCTransport 

func NewGRPCTransport(_ context.Context, cfg *Config) (*GRPCTransport, error)

NewGRPCTransport creates a new gRPC transport to the Geode server.

func (*GRPCTransport) Addr 

func (t *GRPCTransport) Addr() string

Addr returns the remote address.

func (*GRPCTransport) Close 

func (t *GRPCTransport) Close() error

Close closes the transport.

func (*GRPCTransport) IsClosed 

func (t *GRPCTransport) IsClosed() bool

IsClosed returns true if the transport is closed.

func (*GRPCTransport) ReceiveProto 

func (t *GRPCTransport) ReceiveProto(_ context.Context) (*proto.QuicServerMessage, error)

ReceiveProto reads a protobuf message from the gRPC stream.

func (*GRPCTransport) SendProto 

func (t *GRPCTransport) SendProto(ctx context.Context, msg *proto.QuicClientMessage) error

SendProto sends a protobuf message via gRPC.

func (*GRPCTransport) TryReceiveProtoBuffered 

func (t *GRPCTransport) TryReceiveProtoBuffered() (*proto.QuicServerMessage, bool, error)

TryReceiveProtoBuffered attempts to read a buffered message without blocking.

type Pool added in v0.1.13 

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

Pool manages a pool of Geode database connections. It wraps a *sql.DB with Geode-appropriate defaults and provides convenience methods for executing GQL queries.

Consumers should create a single Pool per DSN and share it across goroutines. The Pool handles connection lifecycle, health checking, and automatic reconnection through database/sql's built-in pooling.

Usage: 

pool, err := geode.NewPool("quic://localhost:3141?graph=mydb&user=admin&pass=secret")
if err != nil {
    log.Fatal(err)
}
defer pool.Close()

rows, err := pool.QueryContext(ctx, "MATCH (n:Person) RETURN n.name")

func NewPool added in v0.1.13 

func NewPool(dsn string, opts ...PoolOption) (*Pool, error)

NewPool creates a connection pool for the given DSN. The DSN format is the same as for sql.Open("geode", dsn), with an additional optional `graph` parameter that auto-selects a graph on each new connection.

The pool is immediately validated with a ping. If the server is unreachable, NewPool returns an error.

Example DSNs: 

quic://localhost:3141?graph=mydb&user=admin&pass=secret
grpc://localhost:50051?graph=mydb&tls=0

func (*Pool) BeginTx added in v0.1.13 

func (p *Pool) BeginTx(ctx context.Context, opts *sql.TxOptions) (*sql.Tx, error)

BeginTx starts a transaction with the given options.

func (*Pool) Close added in v0.1.13 

func (p *Pool) Close() error

Close closes all connections in the pool.

func (*Pool) Config added in v0.1.13 

func (p *Pool) Config() *Config

Config returns a copy of the pool's parsed configuration.

func (*Pool) DB added in v0.1.13 

func (p *Pool) DB() *sql.DB

DB returns the underlying *sql.DB for advanced use cases such as running transactions or using sql.Conn for connection-pinned operations.

func (*Pool) ExecContext added in v0.1.13 

func (p *Pool) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)

ExecContext executes a GQL query that doesn't return rows.

func (*Pool) PingContext added in v0.1.13 

func (p *Pool) PingContext(ctx context.Context) error

PingContext verifies a connection to the database is still alive.

func (*Pool) QueryContext added in v0.1.13 

func (p *Pool) QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)

QueryContext executes a GQL query that returns rows.

func (*Pool) QueryRowContext added in v0.1.13 

func (p *Pool) QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row

QueryRowContext executes a GQL query that returns at most one row.

func (*Pool) Stats added in v0.1.13 

func (p *Pool) Stats() sql.DBStats

Stats returns pool statistics.

type PoolOption added in v0.1.13 

type PoolOption func(*poolConfig)

PoolOption configures a Pool.

func WithConnMaxIdleTime added in v0.1.13 

func WithConnMaxIdleTime(d time.Duration) PoolOption

WithConnMaxIdleTime sets the maximum amount of time a connection may sit idle. Should be shorter than the server's idle timeout (QUIC default: 30s). Default: 25 seconds.

func WithConnMaxLifetime added in v0.1.13 

func WithConnMaxLifetime(d time.Duration) PoolOption

WithConnMaxLifetime sets the maximum amount of time a connection may be reused. Expired connections are lazily closed before reuse. Default: 5 minutes.

func WithMaxIdleConns added in v0.1.13 

func WithMaxIdleConns(n int) PoolOption

WithMaxIdleConns sets the maximum number of idle connections in the pool. Default: 4.

func WithMaxOpenConns added in v0.1.13 

func WithMaxOpenConns(n int) PoolOption

WithMaxOpenConns sets the maximum number of open connections to the database. Zero means unlimited. Default: 16.

type QUICPool added in v0.1.15 

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

QUICPool manages a small pool of persistent QUIC connections. Each database/sql Conn gets a new QUIC stream on a pooled connection, amortizing the TLS handshake cost across many logical connections.

func NewQUICPool added in v0.1.15 

func NewQUICPool(cfg *Config, maxSize int) *QUICPool

NewQUICPool creates a new QUIC connection pool for the given config. The pool starts empty and creates connections on demand, up to maxSize.

func (*QUICPool) Close added in v0.1.15 

func (p *QUICPool) Close() error

Close closes all pooled QUIC connections.

type QUICTransport 

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

QUICTransport implements Transport over QUIC with TLS using length-prefixed protobuf.

QUICTransport operates in one of two modes:

  • Standalone mode: owns a dedicated QUIC connection (conn != nil, pool == nil). Created via NewQUICTransport. Close() shuts down both stream and connection.
  • Pooled mode: uses a stream on a shared pooled connection (pool != nil, pc != nil). Created via NewPooledQUICTransport. Close() shuts down only the stream and releases the pooled connection back to the pool.

func NewPooledQUICTransport added in v0.1.15 

func NewPooledQUICTransport(ctx context.Context, pool *QUICPool) (*QUICTransport, error)

NewPooledQUICTransport creates a new QUIC transport that uses a stream from a shared QUIC connection pool. This avoids the TLS handshake overhead for each new database/sql connection.

func NewQUICTransport 

func NewQUICTransport(ctx context.Context, cfg *Config) (*QUICTransport, error)

NewQUICTransport creates a new QUIC transport to the Geode server.

func (*QUICTransport) Addr 

func (t *QUICTransport) Addr() string

Addr returns the remote address.

func (*QUICTransport) Close 

func (t *QUICTransport) Close() error

Close closes the transport.

In standalone mode, both the stream and QUIC connection are closed. In pooled mode, only the stream is closed and the pooled connection is released back to the pool for reuse by other transports.

func (*QUICTransport) IsClosed 

func (t *QUICTransport) IsClosed() bool

IsClosed returns true if the transport is closed.

func (*QUICTransport) ReceiveProto 

func (t *QUICTransport) ReceiveProto(ctx context.Context) (*proto.QuicServerMessage, error)

ReceiveProto reads a length-prefixed protobuf message from the server. Note: This is a blocking call. Use context deadline for timeout control.

func (*QUICTransport) SendProto 

func (t *QUICTransport) SendProto(ctx context.Context, msg *proto.QuicClientMessage) error

SendProto writes a length-prefixed protobuf message to the server.

func (*QUICTransport) TryReceiveProtoBuffered 

func (t *QUICTransport) TryReceiveProtoBuffered() (*proto.QuicServerMessage, bool, error)

TryReceiveProtoBuffered reads a complete protobuf message if enough data is buffered. This avoids blocking when probing for inline frames.

type Result 

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

Result represents the result of an Exec query.

func (*Result) LastInsertId 

func (r *Result) LastInsertId() (int64, error)

LastInsertId returns the last insert ID. Note: Geode doesn't support auto-increment IDs in the traditional sense, so this always returns 0.

func (*Result) RowsAffected 

func (r *Result) RowsAffected() (int64, error)

RowsAffected returns the number of rows affected. Note: Geode doesn't always provide this information, so this may return 0 even when rows were affected.

type RetryPolicy added in v0.1.15 

type RetryPolicy struct {
	// MaxAttempts is the maximum number of attempts including the initial call.
	// Values less than 1 are treated as 1.
	MaxAttempts int

	// InitialBackoff is the delay before the first retry.
	InitialBackoff time.Duration

	// MaxBackoff is the maximum backoff duration. The exponential backoff is
	// clamped to this value.
	MaxBackoff time.Duration

	// Multiplier is the exponential backoff multiplier applied on each retry.
	Multiplier float64
}

RetryPolicy configures retry behavior for transient errors.

func DefaultRetryPolicy added in v0.1.15 

func DefaultRetryPolicy() RetryPolicy

DefaultRetryPolicy returns a RetryPolicy with sensible defaults: 3 max attempts, 1s initial backoff, 30s max backoff, 2.0 multiplier.

type Rows 

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

Rows represents a result set from a query.

func (*Rows) Close 

func (r *Rows) Close() error

Close closes the rows iterator.

func (*Rows) ColumnTypeDatabaseTypeName 

func (r *Rows) ColumnTypeDatabaseTypeName(index int) string

ColumnTypeDatabaseTypeName returns the database type name for a column.

func (*Rows) ColumnTypeNullable 

func (r *Rows) ColumnTypeNullable(_ int) (nullable, ok bool)

ColumnTypeNullable reports whether a column may be null.

func (*Rows) ColumnTypeScanType 

func (r *Rows) ColumnTypeScanType(index int) reflect.Type

ColumnTypeScanType returns the Go type suitable for scanning.

func (*Rows) Columns 

func (r *Rows) Columns() []string

Columns returns the column names.

func (*Rows) IsOrdered 

func (r *Rows) IsOrdered() bool

IsOrdered returns true if the result set is ordered.

func (*Rows) Next 

func (r *Rows) Next(dest []driver.Value) error

Next fetches the next row.

func (*Rows) OrderKeys 

func (r *Rows) OrderKeys() []string

OrderKeys returns the order keys for the result set.

type SecurityError 

type SecurityError struct {
	Type    string // Error type: "tls", "input", "validation"
	Message string // Error message
	// contains filtered or unexported fields
}

SecurityError represents security validation failures.

func (*SecurityError) Error 

func (e *SecurityError) Error() string

Error implements the error interface.

func (*SecurityError) IsRetryable 

func (e *SecurityError) IsRetryable() bool

IsRetryable indicates if the operation can be retried.

func (*SecurityError) StatusClass 

func (e *SecurityError) StatusClass() string

StatusClass returns the status class.

func (*SecurityError) Unwrap 

func (e *SecurityError) Unwrap() error

Unwrap returns the underlying cause.

type StateError 

type StateError struct {
	Current  ConnState // Current state
	Expected ConnState // Expected state (if applicable)
	Op       string    // Operation attempted
	Message  string    // Additional message
}

StateError represents invalid connection state transitions.

func (*StateError) Error 

func (e *StateError) Error() string

Error implements the error interface.

func (*StateError) IsRetryable 

func (e *StateError) IsRetryable() bool

IsRetryable indicates if the operation can be retried.

func (*StateError) StatusClass 

func (e *StateError) StatusClass() string

StatusClass returns the status class.

type Stmt 

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

Stmt represents a prepared statement. Note: Geode doesn't have server-side prepared statements, so this is a client-side implementation that stores the query and validates parameters.

func (*Stmt) Close 

func (s *Stmt) Close() error

Close closes the statement.

func (*Stmt) Exec deprecated 

func (s *Stmt) Exec(args []driver.Value) (driver.Result, error)

Exec executes a query that doesn't return rows.

Deprecated: Use ExecContext instead for explicit timeout control. This method uses a default 30-second timeout.

func (*Stmt) ExecContext 

func (s *Stmt) ExecContext(ctx context.Context, args []driver.NamedValue) (driver.Result, error)

ExecContext executes a query that doesn't return rows.

func (*Stmt) NumInput 

func (s *Stmt) NumInput() int

NumInput returns the number of placeholder parameters.

func (*Stmt) Query deprecated 

func (s *Stmt) Query(args []driver.Value) (driver.Rows, error)

Query executes a query that returns rows.

Deprecated: Use QueryContext instead for explicit timeout control. This method uses a default 30-second timeout.

func (*Stmt) QueryContext 

func (s *Stmt) QueryContext(ctx context.Context, args []driver.NamedValue) (driver.Rows, error)

QueryContext executes a query that returns rows.

type Transport 

type Transport interface {
	// SendProto writes a protobuf message to the server.
	SendProto(ctx context.Context, msg *proto.QuicClientMessage) error

	// ReceiveProto reads a protobuf message from the server.
	ReceiveProto(ctx context.Context) (*proto.QuicServerMessage, error)

	// TryReceiveProtoBuffered reads a message only if enough data is already buffered.
	// Returns (nil, false, nil) when no complete message is buffered.
	TryReceiveProtoBuffered() (*proto.QuicServerMessage, bool, error)

	// Close closes the transport.
	Close() error

	// IsClosed returns true if the transport is closed.
	IsClosed() bool

	// Addr returns the remote address.
	Addr() string
}

Transport defines the interface for communication with a Geode server.

type TransportError 

type TransportError struct {
	Op   string // Operation that failed
	Addr string // Remote address (if applicable) - see Security Note above
	// contains filtered or unexported fields
}

TransportError represents transport-layer failures.

Security Note: The Addr field contains the remote server address for diagnostic purposes. When logging errors to public locations (e.g., client telemetry, user-facing UI), callers should sanitize or omit this field to prevent internal network topology disclosure. For internal logs and debugging, the full address is valuable for troubleshooting.

func (*TransportError) Error 

func (e *TransportError) Error() string

Error implements the error interface.

func (*TransportError) IsRetryable 

func (e *TransportError) IsRetryable() bool

IsRetryable indicates if the operation can be retried.

func (*TransportError) StatusClass 

func (e *TransportError) StatusClass() string

StatusClass returns the status class (always system error for transport).

func (*TransportError) Temporary 

func (e *TransportError) Temporary() bool

Temporary indicates if this is a temporary error.

func (*TransportError) Unwrap 

func (e *TransportError) Unwrap() error

Unwrap returns the underlying cause.

type TransportType 

type TransportType int

TransportType specifies the transport protocol to use. 

const (
	// TransportQUIC uses QUIC transport with TLS 1.3 (default).
	TransportQUIC TransportType = iota

	// TransportGRPC uses gRPC transport.
	TransportGRPC
)

func (TransportType) String 

func (t TransportType) String() string

String returns the string representation of the transport type.

type Tx 

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

Tx represents a database transaction.

func (*Tx) Commit 

func (t *Tx) Commit() error

Commit commits the transaction.

func (*Tx) Rollback 

func (t *Tx) Rollback() error

Rollback rolls back the transaction.

type UnsupportedSchemeError 

type UnsupportedSchemeError struct {
	Scheme string
}

UnsupportedSchemeError is returned when an unsupported DSN scheme is used.

func (*UnsupportedSchemeError) Error 

func (e *UnsupportedSchemeError) Error() string

Source Files

View all Source files

Directories

Path Synopsis
cmd
benchmark command
Native Go client benchmark for Geode
 Native Go client benchmark for Geode
Package crypto provides field-level encryption for Geode node and edge properties.
 Package crypto provides field-level encryption for Geode node and edge properties.
Package graph provides a high-level API for the Geode graph database, built on top of the database/sql-compatible driver.
 Package graph provides a high-level API for the Geode graph database, built on top of the database/sql-compatible driver.
internal
redact
Package redact provides utilities to mask sensitive information before logging.
 Package redact provides utilities to mask sensitive information before logging.
validate
Package validate provides input validation utilities.
 Package validate provides input validation utilities.
Package proto provides protobuf message types and gRPC client for Geode.
 Package proto provides protobuf message types and gRPC client for Geode.

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.