Package: cr8
A collection of command line tools forCratedevelopers (and maybe users as well).TOCWhy cr8? 🤔Install 💾UsageSub-commandstimeit 🕐insert-fake-datainsert-jsoninsert-from-sqlrun-specrun-crateScript reproductionFind regressionsProfilingCreating a CrateDB clusterrun-trackreindexProtocolsDevelopment ☢Why cr8? 🤔To quickly produce sample data. Often if someone reports an issue sample
data is required to be able to reproduce it.insert-fake-dataandinsert-jsonaddress this problem.To benchmark queries & compare runtime across Crate versions.timeit 🕐,run-specandrun-trackcan be used to get runtime statistics of
queries.
These tools focus on response latencies. Being able to benchmark throughput
is NOT a goal of cr8. Similarly, being able to simulate real-world use
cases is also NOT a goal of cr8.NoteAlthough most commands output text by default. Most take a--output-fmtjsonargument to output JSON.
This is useful if used together withjqto post-process the outputInstall 💾Python >= 3.7 is required to use the command line tools.Install them usingpip:python3.7 -m pip install --user cr8This will installcr8into~/.local/bin. Either use~/.local/bin/cr8to launch it or add~/.local/binto your$PATHenvironment variable.An alternative is to download a singlezipappfile from thereleases page.UsageThe main binary is calledcr8which contains a couple of sub-commands.Usecr8-horcr8 <subcommand>-hto get a more detailed usage
description.The included sub-commands are described in more detail below:Tip:Any<subcommand>with--hostsargument supports password authentication
like this:cr8 <subcommand> --hosts http://username:password@localhost:4200 <remaining args>Sub-commandstimeit 🕐A tool that can be used to measure the runtime of a given SQL statement on a
cluster:>>> echo "select name from sys.cluster" | cr8 timeit --hosts localhost:4200
Runtime (in ms):
    mean:    ... ± ...
    min/max: ... → ...
Percentile:
    50:   ... ± ... (stdev)
    95:   ...
    99.9: ...insert-fake-dataA tool that can be used to fill a table with random data. The script will
generate the records usingfaker.For example given the table as follows:create table x.demo (
    id int,
    name text,
    country text
);The following command can be used to insert 1000 records:>>> cr8 insert-fake-data --hosts localhost:4200 --table x.demo --num-records 200
Found schema:
{
    "country": "text",
    "id": "integer",
    "name": "text"
}
Using insert statement:
insert into "x"."demo" ("id", "name", "country") values ($1, $2, $3)
Will make 1 requests with a bulk size of 200
Generating fake data and executing inserts
<BLANKLINE>It will automatically read the schema from the table and map the columns to
fakerprovidersand insert the
give number of records.(Currently only top-level columns are supported)An alternative way to generate random records ismkjsonwhich can be used together withinsert-json.insert-jsoninsert-jsoncan be used to insert records from a JSON file:>>> cat tests/demo.json | cr8 insert-json --table x.demo --hosts localhost:4200
Executing inserts: bulk_size=1000 concurrency=25
Runtime (in ms):
    mean:    ... ± 0.000Or simply print the insert statement generated from a JSON string:>>> echo '{"name": "Arthur"}' | cr8 insert-json --table mytable
('insert into mytable ("name") values ($1)', ['Arthur'])
...insert-from-sqlCopies data from one CrateDB cluster or PostgreSQL server to another.>>> cr8 insert-from-sql \
...   --src-uri "postgresql://crate@localhost:5432/doc" \
...   --query "SELECT name FROM x.demo" \
...   --hosts localhost:4200 \
...   --table y.demo \
INSERT INTO y.demo ("name") VALUES ($1)
Runtime (in ms):
...Theconcurrencyoption of the command only affects the number of concurrent
write operations that will be made. There will always be a single read
operation, so copy operations may be bound by the read performance.run-specA tool to run benchmarks against a cluster and store the result in another
cluster. The benchmark itself is defined in a spec file which definessetup,benchmarkandteardowninstructions.The instructions itself are just SQL statements (or files containing SQL
statements).In thespecsfolder is an example spec file.Usage:>>> cr8 run-spec specs/sample.toml localhost:4200 -r localhost:4200
# Running setUp
# Running benchmark
<BLANKLINE>
## Running Query:
   Name: count countries
   Statement: select count(*) from countries
   Concurrency: 2
   Duration: 1
Runtime (in ms):
    mean:    ... ± ...
    min/max: ... → ...
Percentile:
    50:   ... ± ... (stdev)
    95:   ...
    99.9: ...
...
## Skipping (Version ...
   Statement: ...
# Running tearDown
<BLANKLINE>-ris optional and can be used to save the benchmark result into a cluster.
A table namedbenchmarkswill be created if it doesn’t exist.Writing spec files in python is also supported:>>> cr8 run-spec specs/sample.py localhost:4200
# Running setUp
# Running benchmark
...run-crateLaunch a Crate instance:> cr8 run-crate 0.55.0This requires Java 8.run-cratesupports chaining of additional commands using--. Under the
context ofrun-crateany host urls can be formatted using the{node.http_url}format string:>>> cr8 run-crate latest-stable -- timeit -s "select 1" --hosts '{node.http_url}'
 # run-crate
===========
<BLANKLINE>
...
Starting Crate process
CrateDB launching:
    PID: ...
    Logs: ...
    Data: ...
<BLANKLINE>
...
Cluster ready to process requests
<BLANKLINE>
<BLANKLINE>
# timeit
========
<BLANKLINE>
<BLANKLINE>
<BLANKLINE>
<BLANKLINE>In the above exampletimeitis acr8specific sub-command. But it’s
also possible to use arbitrary commands by prefixing them with@:cr8 run-crate latest-nightly -- @http '{node.http_url}'Script reproductionOne common use of this feature is to quickly reproduce bug reports:cr8 run-crate latest-nightly -- @crash --hosts {node.http_url} <<EOF
    create table mytable (x int);
    insert into mytable (x) values (1);
    refresh mytable;
    ...
EOFFind regressionsAnother use case is to userun-cratein combination withrun-specandgit bisect:git bisect run cr8 run-crate path/to/crate/src \
    -- run-spec path/to/spec.toml '{node.http_url}' --fail-if '{runtime_stats.mean} > 15'This could also be combined withtimeout.ProfilingThis can also be used in combination with the Java flight recorder to do
profiling:cr8 run-crate latest-nightly \
    -e CRATE_HEAP_SIZE=4g \
    -e CRATE_JAVA_OPTS="-Dcrate.signal_handler.disabled=true -XX:+UnlockDiagnosticVMOptions -XX:+DebugNonSafepoints -XX:+UnlockCommercialFeatures -XX:+FlightRecorder" \
    -s discovery.type=single-node \
    -- run-spec path/to/specs/example.toml {node.http_url} --action setup \
    -- @jcmd {node.process.pid} JFR.start duration=60s filename=myrecording.jfr \
    -- run-spec path/to/specs/example.toml {node.http_url} --action queries \
    -- @jcmd {node.process.pid} JFR.stopCreating a CrateDB clustercr8doesn’t contain a dedicated command to spawn a CrateDB cluster. But you
can runcr8run-crate<version>-scluster.name=<name>to launch multiple
nodes. If the cluster name matches, it will form a cluster.run-trackA tool to run.tomltrack files.
A track is a matrix definition of node version, configurations and spec files.For each version and configuration a Crate node will be launched and all specs
will be executed:>>> cr8 run-track tracks/sample.toml
# Version:  latest-testing
## Starting Crate latest-testing, configuration: default.toml
### Running spec file:  sample.toml
# Running setUp
# Running benchmark
...reindexA command to re-index all tables on a cluster which have been created in the
previous major versions. So if you’re running a 3.x CrateDB cluster, all tables
from 2.x would be re-created:>>> cr8 reindex --help
usage: cr8 reindex [-h] --hosts HOSTS
...Protocolscr8supports usingHTTPor thepostgresprotocol.Note that using the postgres protocol will causecr8to measure the
round-trip time instead of the service time. So measurements will be different.To use thepostgresprotocol, theasyncpgscheme must be used inside hosts URIs:>>> echo "select 1" | cr8 timeit --hosts asyncpg://localhost:5432
Runtime (in ms):
...Development ☢To get a sandboxed environment with all dependencies installed usevenv:python -m venv .venv
source .venv/bin/activateInstall thecr8package using pip:python -m pip install -e .Runcr8:cr8 -hTests are run withpython-munittest