testserver

package
v2.3.7 Latest Latest
Warning

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

 Go to latest Published: Mar 6, 2024 License: Apache-2.0 Imports: 31 Imported by: 10

README

cockroach-go Testserver

The testserver package helps running cockroachDB binary with tests. It automatically downloads the latest stable cockroach binary for your runtimeOS, or attempts to run "cockroach" from your PATH.

Example

To run the test server, call NewTestServer(opts) and with test server options.

Here's an example of starting a test server without server options (i.e. in Insecure mode).

  import "github.com/cockroachdb/cockroach-go/v2/testserver"
  import "testing"
  import "time"

  func TestRunServer(t *testing.T) {
     ts, err := testserver.NewTestServer()
     if err != nil {
       t.Fatal(err)
     }
     defer ts.Stop()

     db, err := sql.Open("postgres", ts.PGURL().String())
     if err != nil {
       t.Fatal(err)
     }
   }

Note: please always use testserver.NewTestServer() to start a test server. Never use testserver.Start().

Test Server Options

The default configuration is :

  • in insecure mode, so not using TLS certificates to encrypt network;
  • storing data to memory, with 20% of hard drive space assigned to the node;
  • auto-downloading the latest stable release of cockroachDB.

You can also choose from the following options and pass them to testserver. NewTestServer().

  • Secure Mode: run a secure multi-node cluster locally, using TLS certificates to encrypt network communication. See also https://www.cockroachlabs.com/docs/stable/secure-a-cluster.html.
    • Usage: NewTestServer(testserver.SecureOpt())
  • Set Root User's Password: set the given password for the root user for the PostgreSQL server, so to avoid having to use client certificates. This option can only be passed under secure mode.
    • Usage: NewTestServer(testserver.RootPasswordOpt (your_password))
  • Store On Disk: store the database to the local disk. By default, the database is saved at /tmp/cockroach-testserverxxxxxxxx, with randomly generated xxxxxxxx postfix.
    • Usage: NewTestServer(testserver.StoreOnDiskOpt())
  • Set Memory Allocation for Databse Storage: set the maximum percentage of total memory space assigned to store the database. See also https://www.cockroachlabs. com/docs/stable/cockroach-start.html.
    • Usage: NewTestServer(testserver.SetStoreMemSizeOpt(0.3))
Test Server for Multi Tenants

The usage of test server as a tenant server is still under development. Please check testserver/tenant.go for more information.

Documentation

Overview

Package testserver provides helpers to run a cockroach binary within tests. It automatically downloads the latest cockroach binary for your platform, or attempts to run "cockroach" from your PATH.

To use, run as follows: 

import "github.com/cockroachdb/cockroach-go/v2/testserver"
import "testing"
import "time"

func TestRunServer(t *testing.T) {
   ts, err := testserver.NewTestServer()
   if err != nil {
     t.Fatal(err)
   }
   defer ts.Stop()

   db, err := sql.Open("postgres", ts.PGURL().String())
   if err != nil {
     t.Fatal(err)
   }
 }

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DownloadBinary added in v2.3.0 

func DownloadBinary(tc *TestConfig, desiredVersion string, nonStable bool) (string, error)

DownloadBinary saves the latest version of CRDB into a local binary file, and returns the path for this local binary. To download a specific cockroach version, specify desiredVersion. Otherwise, the latest stable or non-stable version will be chosen. To download the latest STABLE version of CRDB, set `nonStable` to false. To download the bleeding edge version of CRDB, set `nonStable` to true.

func DownloadFromURL added in v2.3.6 

func DownloadFromURL(downloadURL string) (*http.Response, error)

DownloadFromURL starts a download of the cockroach binary from the given URL.

func GetDownloadFilename added in v2.2.0 

func GetDownloadFilename(desiredVersion string) (string, error)

GetDownloadFilename returns the local filename of the downloaded CRDB binary file.

func GetDownloadURL added in v2.3.6 

func GetDownloadURL(desiredVersion string, nonStable bool) (string, string, error)

GetDownloadURL returns the URL of a CRDB download. It creates the URL for downloading a CRDB binary for current runtime OS. If desiredVersion is specified, it will return the URL of the specified version. Otherwise, it will return the URL of the latest stable cockroach binary. If nonStable is true, the latest cockroach binary will be used.

func NewDBForTest 

func NewDBForTest(t *testing.T, opts ...TestServerOpt) (*sql.DB, func())

NewDBForTest creates a new CockroachDB TestServer instance and opens a SQL database connection to it. Returns a sql *DB instance and a shutdown function. The caller is responsible for executing the returned shutdown function on exit.

func NewDBForTestWithDatabase 

func NewDBForTestWithDatabase(
	t *testing.T, database string, opts ...TestServerOpt,
) (*sql.DB, func())

NewDBForTestWithDatabase creates a new CockroachDB TestServer instance and opens a SQL database connection to it. If database is specified, the returned connection will explicitly connect to it. Returns a sql *DB instance a shutdown function. The caller is responsible for executing the returned shutdown function on exit.

Types

type Release added in v2.3.6 

type Release struct {
	Name      string `yaml:"release_name"`
	Withdrawn bool   `yaml:"withdrawn"`
	CloudOnly bool   `yaml:"cloud_only"`
}

Release contains the information we extract from the YAML file in `releaseDataURL`.

type TestConfig added in v2.2.0 

type TestConfig struct {
	IsTest               bool
	StopDownloadInMiddle bool
}

type TestServer 

type TestServer interface {
	// Start starts the server.
	Start() error
	// Stop stops the server and cleans up any associated resources.
	Stop()

	// Stdout returns the entire contents of the first node's stdout.
	Stdout() string
	// Stdout returns the entire contents of the first node's stderr.
	Stderr() string
	// StdoutForNode returns the entire contents of the node's stdout.
	StdoutForNode(i int) string
	// StderrForNode returns the entire contents of the node's stderr.
	StderrForNode(i int) string
	// PGURL returns the postgres connection URL to this server.
	PGURL() *url.URL
	// WaitForInit retries until a SQL connection is successfully established to
	// this server.
	WaitForInit() error
	// BaseDir returns directory StoreOnDiskOpt writes to if used.
	BaseDir() string

	// WaitForInitFinishForNode waits until a node has completed
	// initialization and is available to connect to and query on.
	WaitForInitFinishForNode(numNode int) error
	// StartNode runs the "cockroach start" command for the node.
	StartNode(i int) error
	// StopNode kills the node's process.
	StopNode(i int) error
	// UpgradeNode stops the node, then starts the node on the with the
	// binary specified at "upgradeBinaryPath".
	UpgradeNode(i int) error
	// PGURLForNode returns the PGUrl for the node.
	PGURLForNode(nodeNum int) *url.URL
}

TestServer is a helper to run a real cockroach node.

func NewTestServer 

func NewTestServer(opts ...TestServerOpt) (TestServer, error)

NewTestServer creates a new TestServer and starts it. It also waits until the server is ready to accept clients, so it safe to connect to the server returned by this function right away. The cockroach binary for your OS and ARCH is downloaded automatically. If the download fails, we attempt just call "cockroach", hoping it is found in your path.

type TestServerOpt added in v2.0.7 

type TestServerOpt func(args *testServerArgs)

TestServerOpt is passed to NewTestServer.

func AddHttpPortOpt added in v2.2.16 

func AddHttpPortOpt(port int) TestServerOpt

AddHttpPortOpt is a TestServer option that can be passed to NewTestServer to specify the http ports for the Cockroach nodes.

func AddListenAddrPortOpt added in v2.2.16 

func AddListenAddrPortOpt(port int) TestServerOpt

AddListenAddrPortOpt is a TestServer option that can be passed to NewTestServer to specify the ports for the Cockroach nodes. In the case of restarting nodes, it is up to the user of TestServer to make sure the port used here cannot be re-used.

func CacheSizeOpt added in v2.3.7 

func CacheSizeOpt(cacheSize float64) TestServerOpt

CacheSizeOpt sets the proportion of available memory that is allocated to the CockroachDB cache.

func CockroachBinaryPathOpt added in v2.2.10 

func CockroachBinaryPathOpt(executablePath string) TestServerOpt

CockroachBinaryPathOpt is a TestServer option that can be passed to NewTestServer to specify the path of the cockroach binary. This can be used to avoid downloading cockroach if running tests in an environment with no internet connection, for instance.

func CockroachLogsDirOpt added in v2.3.4 

func CockroachLogsDirOpt(dir string) TestServerOpt

CockroachLogsDirOpt allows callers to control where the stdout and stderr of cockroach processes created by the testserver are located. Files will be in the format: $nodeID/cockroach.std{out,err}.

func CustomVersionOpt added in v2.2.17 

func CustomVersionOpt(ver string) TestServerOpt

CustomVersionOpt is a TestServer option that can be passed to NewTestServer to download the a specific version of CRDB.

func EnvVarOpt added in v2.2.18 

func EnvVarOpt(vars []string) TestServerOpt

EnvVarOpt is a list of environment variables to be passed to the start command. Each entry in the slice should be in `key=value` format.

func ExposeConsoleOpt added in v2.2.9 

func ExposeConsoleOpt(port int) TestServerOpt

ExposeConsoleOpt is a TestServer option that can be passed to NewTestServer to expose the console of the server on the given port. Warning: This is kept around for backwards compatibility, use AddHttpPortOpt instead.

func ExternalIODirOpt added in v2.2.17 

func ExternalIODirOpt(ioDir string) TestServerOpt

ExternalIODirOpt is a TestServer option that can be passed to NewTestServer to specify the external IO directory to be used for the cluster.

func InitTimeoutOpt added in v2.2.17 

func InitTimeoutOpt(timeout int) TestServerOpt

func ListenAddrHostOpt added in v2.3.0 

func ListenAddrHostOpt(host string) TestServerOpt

ListenAddrHostOpt is a TestServer option that can be passed to NewTestServer to specify the host for Cockroach to listen on. By default, this is `localhost`, and the most common override is 0.0.0.0.

func LocalityFlagsOpt added in v2.3.4 

func LocalityFlagsOpt(locality ...string) TestServerOpt

LocalityFlagsOpt is used to specify the --locality flag for each node.

Example Usage: 

localities := LocalityFlagsOpt("region=us-west", "region=us-east", "region=us-central")
server, err := NewTestServer(ThreeNodeOpt(), localities)

func NonStableDbOpt added in v2.2.0 

func NonStableDbOpt() TestServerOpt

NonStableDbOpt is a TestServer option that can be passed to NewTestServer to download the latest beta version of CRDB, but not necessary a stable one.

func PollListenURLTimeoutOpt added in v2.2.17 

func PollListenURLTimeoutOpt(timeout int) TestServerOpt

func RootPasswordOpt added in v2.0.7 

func RootPasswordOpt(pw string) TestServerOpt

RootPasswordOpt is a TestServer option that, when passed to NewTestServer, sets the given password for the root user (and returns a URL using it from PGURL(). This avoids having to use client certs.

func SecureOpt added in v2.0.2 

func SecureOpt() TestServerOpt

SecureOpt is a TestServer option that can be passed to NewTestServer to enable secure mode.

func SetStoreMemSizeOpt added in v2.2.0 

func SetStoreMemSizeOpt(memSize float64) TestServerOpt

SetStoreMemSizeOpt is a TestServer option that can be passed to NewTestServer to set the proportion of available memory that is allocated to the test server.

func StopDownloadInMiddleOpt added in v2.2.0 

func StopDownloadInMiddleOpt() TestServerOpt

StopDownloadInMiddleOpt is a TestServer option used only in testing. It is used to test the flock over downloaded CRDB binary. It should not be used in production.

func StoreOnDiskOpt added in v2.2.0 

func StoreOnDiskOpt() TestServerOpt

StoreOnDiskOpt is a TestServer option that can be passed to NewTestServer to enable storing database in memory.

func ThreeNodeOpt added in v2.2.14 

func ThreeNodeOpt() TestServerOpt

func UpgradeCockroachBinaryPathOpt added in v2.2.14 

func UpgradeCockroachBinaryPathOpt(executablePath string) TestServerOpt

Source Files

View all Source files

Directories

Path Synopsis

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.