cassandra

README

What

This package contains the tooling for cadence cassandra operations.

How

• Run make bins
• You should see an executable cadence-cassandra-tool

Setting up cassandra schema on a new cluster shortcut

make install-schema

Setting up schema for production use

The default Makefile sets up a replication factor of 1. This should be used for developer setups when running Cadence server on a laptop. For production clusters we recommend to use a replication factor of 3. Please use 'cadence-cassandra-tool' to create both the cadence and cadence_visibility keyspaces. It already has an option to configure the replication factor.

cadence-cassandra-tool --ep $CASSANDRA_SEEDS create -k $KEYSPACE --rf $RF

See https://www.ecyrd.com/cassandracalculator for an easy way to determine how many nodes and what replication factor you will want to use. Note that Cadence by default uses Quorum for read and write consistency.

Setting up schema on a new cluster manually

./cadence-cassandra-tool -ep 127.0.0.1 -k cadence setup-schema -v 0.0 -- this sets up just the schema version tables with initial version of 0.0
./cadence-cassandra-tool -ep 127.0.0.1 -k cadence update-schema -d ./schema/cassandra/cadence/versioned -- upgrades your schema to the latest version

./cadence-cassandra-tool -ep 127.0.0.1 -k cadence_visibility setup-schema -v 0.0 -- this sets up just the schema version tables with initial version of 0.0 for visibility
./cadence-cassandra-tool -ep 127.0.0.1 -k cadence_visibility update-schema -d ./schema/cassandra/visibility/versioned -- upgrades your schema to the latest version for visibility

Updating schema on an existing cluster

You can only upgrade to a new version after the initial setup done above.

./cadence-cassandra-tool -ep 127.0.0.1 -k cadence update-schema -d ./schema/cassandra/cadence/versioned -v x.x -y -- executes a dryrun of upgrade to version x.x
./cadence-cassandra-tool -ep 127.0.0.1 -k cadence update-schema -d ./schema/cassandra/cadence/versioned -v x.x    -- actually executes the upgrade to version x.x

./cadence-cassandra-tool -ep 127.0.0.1 -k cadence_visibility update-schema -d ./schema/cassandra/visibility/versioned -v x.x -y -- executes a dryrun of upgrade to version x.x
./cadence-cassandra-tool -ep 127.0.0.1 -k cadence_visibility update-schema -d ./schema/cassandra/visibility/versioned -v x.x    -- actually executes the upgrade to version x.x

Documentation

Index

• func NewCassandraCluster(hostsCsv string, port int, user, password, keyspace string, timeoutSeconds int) (*gocql.ClusterConfig, error)
• func ParseCQLFile(filePath string) ([]string, error)
• func RunTool(args []string) error
• func SetupSchema(config *SetupSchemaConfig) error
• func VerifyCompatibleVersion(cfg config.Persistence, rootPath string) error
• type BaseConfig
• type CQLClient
• type ConfigError
  • func (e *ConfigError) Error() string
• type CreateKeyspaceConfig
• type SetupSchemaConfig
• type SetupSchemaTask
• type UpdateSchemaConfig
• type UpdateSchemaTask
  • func NewUpdateSchemaTask(config *UpdateSchemaConfig) (*UpdateSchemaTask, error)

Functions

func NewCassandraCluster

func NewCassandraCluster(hostsCsv string, port int, user, password, keyspace string, timeoutSeconds int) (*gocql.ClusterConfig, error)

NewCassandraCluster return gocql clusterConfig

func ParseCQLFile

func ParseCQLFile(filePath string) ([]string, error)

ParseCQLFile takes a cql file path as input and returns an array of cql statements on success.

func RunTool

func RunTool(args []string) error

RunTool runs the cadence-cassandra-tool command line tool

func SetupSchema

func SetupSchema(config *SetupSchemaConfig) error

SetupSchema setups the cassandra schema

func VerifyCompatibleVersion

func VerifyCompatibleVersion(cfg config.Persistence, rootPath string) error

VerifyCompatibleVersion ensures that the installed version of cadence and visibility keyspaces is greater than or equal to the expected version. In most cases, the versions should match. However if after a schema upgrade there is a code rollback, the code version (expected version) would fall lower than the actual version in cassandra.

Types

type BaseConfig

type BaseConfig struct {
	CassHosts    string
	CassPort     int
	CassUser     string
	CassPassword string
	CassKeyspace string
	CassTimeout  int
}

BaseConfig is the common config for all of the tasks that work with cassandra

type CQLClient

type CQLClient interface {
	// Exec executes a cql statement
	Exec(stmt string) error
	// ListTables lists the table names in a keyspace
	ListTables() ([]string, error)
	// ListTypes lists the user defined types in a keyspace
	ListTypes() ([]string, error)
	// CreateKeyspace creates a keyspace, if it doesn't exist
	// it uses SimpleStrategy by default
	CreateKeyspace(name string, replicas int) error
	// DropTable drops the given table
	DropTable(name string) error
	// DropType drops a user defined type from keyspace
	DropType(name string) error
	// DropKeyspace drops a keyspace
	DropKeyspace(keyspace string) error
	// CreateSchemaVersionTables sets up the schema version tables
	CreateSchemaVersionTables() error
	// ReadSchemaVersion returns the current schema version for the keyspace
	ReadSchemaVersion() (string, error)
	// UpdateSchemaVersion updates the schema version for the keyspace
	UpdateSchemaVersion(newVersion string, minCompatibleVersion string) error
	// WriteSchemaUpdateLog adds an entry to the schema update history table
	WriteSchemaUpdateLog(oldVersion string, newVersion string, manifestMD5 string, desc string) error
	// Close gracefully closes the client object
	Close()
}

CQLClient is the interface for implementations that provide a way to talk to cassandra through CQL

type ConfigError

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

ConfigError is an error type that represents a problem with the config

func (*ConfigError) Error

func (e *ConfigError) Error() string

type CreateKeyspaceConfig

type CreateKeyspaceConfig struct {
	BaseConfig
	ReplicationFactor int
}

CreateKeyspaceConfig holds the config params needed to create a cassandra keyspace

type SetupSchemaConfig

type SetupSchemaConfig struct {
	BaseConfig
	SchemaFilePath    string
	InitialVersion    string
	Overwrite         bool // overwrite previous data
	DisableVersioning bool // do not use schema versioning
}

SetupSchemaConfig holds the config params need by the SetupSchemaTask

type SetupSchemaTask

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

SetupSchemaTask represents a task that sets up cassandra schema on a specified keyspace

type UpdateSchemaConfig

type UpdateSchemaConfig struct {
	BaseConfig
	TargetVersion string
	SchemaDir     string
	IsDryRun      bool
}

UpdateSchemaConfig holds the config params for executing a UpdateSchemaTask

type UpdateSchemaTask

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

UpdateSchemaTask represents a task that executes a cassandra schema upgrade

func NewUpdateSchemaTask

func NewUpdateSchemaTask(config *UpdateSchemaConfig) (*UpdateSchemaTask, error)

NewUpdateSchemaTask returns a new instance of UpdateSchemaTask