cassandra

README

Using the cassandra schema tool

This package contains the tooling for cadence cassandra operations.

For localhost development

make install-schema

NOTE: See CONTRIBUTING for prerequisite of make command.

For production

Get the Cassandra Schema tool

• Use brew to install CLI: brew install cadence-workflow which includes cadence-cassandra-tool
• Or build yourself, with make cadence-cassandra-tool. See CONTRIBUTING for prerequisite of make command.

Note: The binaries can also be found in the ubercadence/server docker images

Do one time database creation and schema setup for a new cluster

This uses Cassandra's SimpleStratagey for replication. For production, we recommend using a replication factor of 3 with NetworkTopologyStrategy.

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.

./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

Update schema as part of a release

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

• Constants
• func BuildCLIOptions() *cli.App
• func CheckCompatibleVersion(cfg config.Cassandra, expectedVersion string) error
• func RunTool(args []string) error
• func SetupSchema(config *SetupSchemaConfig) error
• func VerifyCompatibleVersion(cfg config.Persistence) error
• type CQLClientConfig
• type CqlClient
  • func NewCQLClient(cfg *CQLClientConfig) (*CqlClient, error)
  • func (client *CqlClient) Close()
  • func (client *CqlClient) CreateDatabase(name string) error
  • func (client *CqlClient) CreateKeyspace(name string) error
  • func (client *CqlClient) CreateSchemaVersionTables() error
  • func (client *CqlClient) DropAllTables() error
  • func (client *CqlClient) DropDatabase(name string) error
  • func (client *CqlClient) DropKeyspace(name string) error
  • func (client *CqlClient) Exec(stmt string, args ...interface{}) error
  • func (client *CqlClient) ListTables() ([]string, error)
  • func (client *CqlClient) ReadSchemaVersion() (string, error)
  • func (client *CqlClient) UpdateSchemaVersion(newVersion string, minCompatibleVersion string) error
  • func (client *CqlClient) WriteSchemaUpdateLog(oldVersion string, newVersion string, manifestMD5 string, desc string) error
• type SetupSchemaConfig

Constants

const (
	DefaultTimeout       = 30 // Timeout in seconds
	DefaultCassandraPort = 9042
	SystemKeyspace       = "system"
)

Functions

func BuildCLIOptions

func BuildCLIOptions() *cli.App

func CheckCompatibleVersion

func CheckCompatibleVersion(
	cfg config.Cassandra,
	expectedVersion string,
) error

CheckCompatibleVersion check the version compatibility

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,
) 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 CQLClientConfig

type CQLClientConfig struct {
	Hosts        string
	Port         int
	User         string
	Password     string
	Keyspace     string
	Timeout      int
	NumReplicas  int
	ProtoVersion int
	TLS          *config.TLS
}

CQLClientConfig contains the configuration for cql client

type CqlClient

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

func NewCQLClient

func NewCQLClient(cfg *CQLClientConfig) (*CqlClient, error)

NewCQLClient returns a new instance of CQLClient

func (*CqlClient) Close

func (client *CqlClient) Close()

Close closes the cql client

func (*CqlClient) CreateDatabase

func (client *CqlClient) CreateDatabase(name string) error

func (*CqlClient) CreateKeyspace

func (client *CqlClient) CreateKeyspace(name string) error

createKeyspace creates a cassandra Keyspace if it doesn't exist

func (*CqlClient) CreateSchemaVersionTables

func (client *CqlClient) CreateSchemaVersionTables() error

CreateSchemaVersionTables sets up the schema version tables

func (*CqlClient) DropAllTables

func (client *CqlClient) DropAllTables() error

func (*CqlClient) DropDatabase

func (client *CqlClient) DropDatabase(name string) error

func (*CqlClient) DropKeyspace

func (client *CqlClient) DropKeyspace(name string) error

DropKeyspace drops a Keyspace

func (*CqlClient) Exec

func (client *CqlClient) Exec(stmt string, args ...interface{}) error

Exec executes a cql statement

func (*CqlClient) ListTables

func (client *CqlClient) ListTables() ([]string, error)

ListTables lists the table names in a Keyspace

func (*CqlClient) ReadSchemaVersion

func (client *CqlClient) ReadSchemaVersion() (string, error)

ReadSchemaVersion returns the current schema version for the Keyspace

func (*CqlClient) UpdateSchemaVersion

func (client *CqlClient) UpdateSchemaVersion(newVersion string, minCompatibleVersion string) error

UpdateShemaVersion updates the schema version for the Keyspace

func (*CqlClient) WriteSchemaUpdateLog

func (client *CqlClient) WriteSchemaUpdateLog(oldVersion string, newVersion string, manifestMD5 string, desc string) error

WriteSchemaUpdateLog adds an entry to the schema update history table

type SetupSchemaConfig

type SetupSchemaConfig struct {
	CQLClientConfig
	schema.SetupConfig
}

SetupSchemaConfig contains the configuration params needed to setup schema tables