README
¶
cockroach-go Testserver
The testserver package helps running cockroachDB binary with tests. It
automatically downloads the latest stable cockroach binary for your runtimeOS
(Linux-amd64 and Darwin-amd64 only for now), 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())
- Usage:
- 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))
- Usage:
- Store On Disk: store the database to the local disk. By default, the database is
saved at
/tmp/cockroach-testserverxxxxxxxx, with randomly generatedxxxxxxxxpostfix.- Usage:
NewTestServer(testserver.StoreOnDiskOpt())
- Usage:
- 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))
- Usage:
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 (Linux-amd64 and Darwin-amd64 only for now), 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 ¶
- func GetDownloadFilename(response *http.Response, nonStableDB bool, latestStableVersion string) (string, error)
- func GetDownloadResponse(nonStable bool) (*http.Response, string, error)
- func NewDBForTest(t *testing.T, opts ...TestServerOpt) (*sql.DB, func())
- func NewDBForTestWithDatabase(t *testing.T, database string, opts ...TestServerOpt) (*sql.DB, func())
- type TestConfig
- type TestServer
- type TestServerOpt
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetDownloadFilename ¶
func GetDownloadFilename( response *http.Response, nonStableDB bool, latestStableVersion string, ) (string, error)
GetDownloadFilename returns the local filename of the downloaded CRDB binary file.
func GetDownloadResponse ¶
GetDownloadResponse return the http response of a CRDB download. It creates the url for downloading a CRDB binary for current runtime OS, makes a request to this url, and return the response.
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 TestConfig ¶
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 process' stdout.
Stdout() string
// Stdout returns the entire contents of the process' stderr.
Stderr() 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
}
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 ¶
type TestServerOpt func(args *testServerArgs)
TestServerOpt is passed to NewTestServer.
func NonStableDbOpt ¶
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 RootPasswordOpt ¶
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 ¶
func SecureOpt() TestServerOpt
SecureOpt is a TestServer option that can be passed to NewTestServer to enable secure mode.
func SetStoreMemSizeOpt ¶
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 ¶
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 ¶
func StoreOnDiskOpt() TestServerOpt
StoreOnDiskOpt is a TestServer option that can be passed to NewTestServer to enable storing database in memory.
Source Files
Directories