Fully automated database experiments. THIS IS A MIRROR OF https://gitlab.com/postgres.ai/nancy
:warning: Nancy CLI project is on hold now. See details: https://gitlab.com/postgres-ai/nancy/-/issues/228
Nancy helps to conduct automated database experiments.
The Nancy Command Line Interface is a unified way to manage automated database experiments either in clouds or on-premise.
Database experiment is a set of actions performed to test
Two main goals for any database experiment:
Database experiments are needed when you:
pg_stat_statements
snapshotpg_stat_database
, ...To use Nancy CLI you need Linux or MacOS with installed Docker.
To run on AWS EC2 instances, you also need:
In the minimal configuration, only a few steps are needed:
NOTICE: The Additional notes section contains
instructions useful in case of docker-related errors during nancy run
calls.
Alternatively, see Docker's official post-installation instructions for Linux.
Ubuntu/Debian:
sudo apt-get -y install docker
sudo systemctl enable docker
sudo systemctl start docker
RHEL7:
yum -y install docker
systemctl enable docker
systemctl start docker
MacOS (assuming that Homebrew is installed):
brew install docker
See also: https://docs.docker.com/docker-for-mac/install/
$PATH
:git clone https://gitlab.com/postgres.ai/nancy.git
echo "export PATH=\$PATH:"$(pwd)"/nancy" >> ~/.bashrc
source ~/.bashrc
sudo apt-get -y install jq
sudo yum install jq
brew install jq
Additionally, to allow use of AWS EC2 instances:
Install AWS CLI https://docs.aws.amazon.com/cli/latest/userguide/installing.html
Install Docker Machine tools https://docs.docker.com/machine/install-machine/
Start with these commands:
nancy help
nancy run help
Locally, on any Linux or macOS machine:
echo "create table hello_world as select i from generate_series(1, (10^6)::int) _(i);" \
| bzip2 > ./sample.dump.bz2
# "Clean run": w/o index
# (seqscan is expected, total time ~150ms, depending on resources)
nancy run \
--db-dump file://$(pwd)/sample.dump.bz2 \
--workload-custom-sql "select i from hello_world where i between 10 and 20;"
# Now check how a regular btree index affects performance
# (expected total time: ~0.05ms)
nancy run \
--db-dump file://$(pwd)/sample.dump.bz2 \
--workload-custom-sql "select i from hello_world where i between 10 and 20;" \
--delta-sql-do "create index i_hello_world_i on hello_world(i);" \
--delta-sql-undo "drop index i_hello_world_i;"
AWS EC2:
nancy run \
--run-on aws \
--aws-ec2-type "i3.large" \
--aws-keypair-name awskey \
--aws-ssh-key-path file://$(echo ~)/.ssh/awskey.pem \
--db-dump "create table hello_world as select i from generate_series(1, (10^6)::int) _(i);" \
--workload-custom-sql "select i from hello_world where i between 10 and 20;"
On Linux, if you experience issues with running (locally) nancy run
inside screen
or
tmux
, double-check that Docker is running and add your user to the docker
group, as described below. See also: https://docs.docker.com/install/linux/linux-postinstall/.
Ubuntu/Debian:
# Ubuntu/Debian
sudo usermod -aG docker ${USER}
newgrp docker
CentOS/RHEL:
sudo usermod -aG dockerroot ${USER}
newgrp dockerroot
On MacOS, it is recommended to specify --tmp-path
explicitly, similar to this:
mkdir ./tmp
nancy run ... --tmp-path "$(pwd)/tmp"