testcluster

Documentation

Index

• type ClusterArgs
• type ReplicationMode
• type ReplicationTarget
• type TestCluster
  • func StartTestCluster(t testing.TB, nodes int, args ClusterArgs) *TestCluster
  • func (tc *TestCluster) AddReplicas(rangeDesc *roachpb.RangeDescriptor, dests ...ReplicationTarget) (*roachpb.RangeDescriptor, error)
  • func (tc *TestCluster) FindRangeLeaseHolder(rangeDesc *roachpb.RangeDescriptor, hint *ReplicationTarget) (ReplicationTarget, error)
  • func (tc *TestCluster) SplitRange(splitKey roachpb.Key) (*roachpb.RangeDescriptor, *roachpb.RangeDescriptor, error)
  • func (tc *TestCluster) Stopper() *stop.Stopper
  • func (tc *TestCluster) Target(serverIdx int) ReplicationTarget
  • func (tc *TestCluster) TransferRangeLease(rangeDesc *roachpb.RangeDescriptor, dest ReplicationTarget) error
  • func (tc *TestCluster) WaitForFullReplication() error

Types

type ClusterArgs

type ClusterArgs struct {
	// ServerArgs will be copied to each constituent TestServer.
	ServerArgs base.TestServerArgs
	// ReplicationMode controls how replication is to be done in the cluster.
	ReplicationMode ReplicationMode
	// Stopper can be used to stop the cluster. If not set, a stopper will be
	// constructed and it can be gotten through TestCluster.Stopper().
	Stopper *stop.Stopper
}

ClusterArgs contains the parameters one can set when creating a test cluster. It contains a base.TestServerArgs instance which will be copied over to every server.

The zero value means "full replication".

type ReplicationMode

type ReplicationMode int

ReplicationMode represents the replication settings for a TestCluster.

const (
	// ReplicationFull means that each range is to be replicated everywhere. This
	// will be done by overriding the default zone config. The replication will be
	// performed as in production, by the replication queue.
	// TestCluster.WaitForFullReplication() can be used to wait for replication to
	// be stable at any point in a test.
	// TODO(andrei): ReplicationFull should not be an option, or at least not the
	// default option. Instead, the production default replication should be the
	// default for TestCluster too. But I'm not sure how to implement
	// `WaitForFullReplication` for that.
	ReplicationFull ReplicationMode = iota
	// ReplicationManual means that the split and replication queues of all
	// servers are stopped, and the test must manually control splitting and
	// replication through the TestServer.
	ReplicationManual
)

type ReplicationTarget

type ReplicationTarget struct {
	NodeID  roachpb.NodeID
	StoreID roachpb.StoreID
}

ReplicationTarget identifies a node/store pair.

type TestCluster

type TestCluster struct {
	Servers []*server.TestServer
	Conns   []*gosql.DB
}

TestCluster represents a set of TestServers. The hope is that it can be used analoguous to TestServer, but with control over range replication.

func StartTestCluster

func StartTestCluster(t testing.TB, nodes int, args ClusterArgs) *TestCluster

StartTestCluster starts up a TestCluster made up of `nodes` in-memory testing servers. The cluster should be stopped using cluster.Stopper().Stop().

func (*TestCluster) AddReplicas

func (tc *TestCluster) AddReplicas(
	rangeDesc *roachpb.RangeDescriptor, dests ...ReplicationTarget,
) (*roachpb.RangeDescriptor, error)

AddReplicas adds replicas for a range on a set of stores. It's illegal to have multiple replicas of the same range on stores of a single node. The method blocks until a snapshot of the range has been copied to all the new replicas and the new replicas become part of the Raft group.

func (*TestCluster) FindRangeLeaseHolder

func (tc *TestCluster) FindRangeLeaseHolder(
	rangeDesc *roachpb.RangeDescriptor,
	hint *ReplicationTarget,
) (ReplicationTarget, error)

FindRangeLeaseHolder returns the current lease holder for the given range. If there is no lease at the time of the call, a replica is gets one as a side-effect of calling this; if hint is not nil, that replica will be the one.

One of the Stores in the cluster is used as a Sender to send a dummy read command, which will either result in success (if a replica on that Node has the lease), in a NotLeaseHolderError pointing to the current lease holder (if there is an active lease), or in the replica on that store acquiring the lease (if there isn't an active lease). If an active lease existed for the range, it's extended as a side-effect.

func (*TestCluster) SplitRange

func (tc *TestCluster) SplitRange(
	splitKey roachpb.Key,
) (*roachpb.RangeDescriptor, *roachpb.RangeDescriptor, error)

SplitRange splits the range containing splitKey. The right range created by the split starts at the split key and extends to the original range's end key. Returns the new descriptors of the left and right ranges.

splitKey must correspond to a SQL table key (it must end with a family ID / col ID).

func (*TestCluster) Stopper

func (tc *TestCluster) Stopper() *stop.Stopper

Stopper returns a Stopper to be used to stop the TestCluster.

func (*TestCluster) Target

func (tc *TestCluster) Target(serverIdx int) ReplicationTarget

Target returns a ReplicationTarget for the specified server.

func (*TestCluster) TransferRangeLease

func (tc *TestCluster) TransferRangeLease(
	rangeDesc *roachpb.RangeDescriptor, dest ReplicationTarget,
) error

TransferRangeLease transfers the lease for a range from whoever has it to a particular store. That store must already have a replica of the range. If that replica already has the (active) lease, this method is a no-op.

func (*TestCluster) WaitForFullReplication

func (tc *TestCluster) WaitForFullReplication() error

WaitForFullReplication waits until all of the nodes in the cluster have the same number of replicas.