Categorygithub.com/kipling-engineering/kipling-cn-infradbsqlcassandra
package
0.1.1
Repository: https://github.com/kipling-engineering/kipling-cn-infra.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
14
Dependents
0
Files
608 SLOC

# README

Cassandra implementation of Broker interface

The API was tested with Cassandra 3 and supports:

  • UDT (User Defined Types) / embedded structs and honors gocql.Marshaler/gocql.Unmarshaler
  • handling all primitive types (like int aliases , IP address);
    • net.IP can be stored as ipnet
    • net.IPNet can be stored with a MarshalCQL/UnmarshalCQL wrapper go structure
  • dumping all rows except for Table
  • quering by secondary indexes
  • mocking of gocql behavior (using gockle library)in automated unit tests

Cassandra Timeouts

The API will allow the client to configure either single node or multi-node cluster. Also, the client can configure following timeouts:

  • DialTimeout
    • Initial connection timeout, used during initial dial to server
    • Default value is 600ms
  • OpTimeout
    • Connection timeout, used during executing query
    • Default value is 600ms
  • RedialInterval
    • If not zero, gocql attempt to reconnect known DOWN nodes in every ReconnectSleep (ReconnectInterval)
    • Default value is 60s
  • Example
    config := &cassandra.Config{
        Endpoints:      127.0.0.1,
        Port:           9042,
        DialTimeout:    600 * time.Millisecond,
        OpTimeout:      600 * time.Millisecond,
        RedialInterval: 60 * time.Second,
    }

    clientConfig, err := cassandra.ConfigToClientConfig(config)

The timeout parameters are defined here config.go

Supported by underlying gocql structure ClusterConfig

Cassandra Data Consistency

The API will allow the client to configure consistency level for both

  • Session
  • Query (to be implemented)

Supported by underlying gocql structure Session

Factors to be considered for achieving desired consistency level.

  • Replication strategy

    • A replication strategy determines the nodes where replicas are placed.
      • SimpleStrategy: Use for a single data center only.
      • NetworkTopologyStrategy: Used for more than one data center.

  • Replication factor

    • The total number of replicas across the cluster is referred to as the replication factor.
    • A replication factor of 1 means that there is only one copy of each row on one node.
    • A replication factor of 2 means that there are two copies of each row, and each copy is stored on a different node.
    • The replication factor should not exceed the number of nodes in the cluster.

  • To achieve Quorum

    • Quorum = (sum_of_replication_factors / 2) + 1
    • (nodes_written + nodes_read) > replication_factor

  • References

# Functions

ConfigToClientConfig transforms the yaml configuration into ClientConfig.
CreateSessionFromConfig creates and initializes the cluster based on the supplied config and returns a new session object that can be used to interact with the database.
ExpToString converts expression to string & slice of bindings.
FromExistingSession is used mainly for testing.
HostsAsString converts an array of hosts addresses into a comma separated string.
NewBrokerUsingSession is a Broker constructor.
NewPlugin creates a new Plugin with the provided Options.
PutExpToString converts expression to string & slice of bindings.
SelectExpToString converts expression to string & slice of bindings.
SliceOfFieldsWithValPtrs generates slice of translated (cql tag) field names with field values used for unit testing purposes only - list_values test.
UseDeps returns Option that can inject custom dependencies.

# Variables

DefaultPlugin is a default instance of Plugin.
ErrInvalidEndpointConfig is error returned when endpoint and port are not in valid format.
ErrMissingEntityField is error returned when visitor entity is missing field.
ErrMissingVisitorEntity is error returned when visitor is missing entity.
ErrUnexportedEntityField is error returned when visitor entity has unexported field.

# Structs

BrokerCassa implements interface db.Broker.
ClientConfig wrapping gocql ClusterConfig.
Config Configuration for Cassandra clients loaded from a configuration file.
Deps is here to group injected dependencies of plugin to not mix with other plugin fields.
ErrIterator is an iterator that stops immediately and just returns last error on Close().
Plugin implements Plugin interface therefore can be loaded with other plugins.
TLS used to configure TLS.
ValIterator is an iterator returned by ListValues call.

# Type aliases

Option is a function that can be used in NewPlugin to customize Plugin.