{"id":13880590,"url":"https://github.com/postgres-ai/nancy","last_synced_at":"2025-07-16T17:30:43.122Z","repository":{"id":114767937,"uuid":"130894142","full_name":"postgres-ai/nancy","owner":"postgres-ai","description":"Fully automated database experiments. THIS IS A MIRROR OF https://gitlab.com/postgres.ai/nancy","archived":true,"fork":false,"pushed_at":"2020-07-31T19:06:29.000Z","size":1249,"stargazers_count":104,"open_issues_count":3,"forks_count":7,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-11-24T09:34:00.421Z","etag":null,"topics":["aws-ec2","database-experiment","docker","postgres","sql-queries","workload"],"latest_commit_sha":null,"homepage":"https://postgres.ai","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/postgres-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-24T17:59:33.000Z","updated_at":"2023-10-10T15:24:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"2edbfd68-28cd-4db1-b5a0-2942cbdec36b","html_url":"https://github.com/postgres-ai/nancy","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/postgres-ai/nancy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postgres-ai%2Fnancy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postgres-ai%2Fnancy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postgres-ai%2Fnancy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postgres-ai%2Fnancy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/postgres-ai","download_url":"https://codeload.github.com/postgres-ai/nancy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postgres-ai%2Fnancy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265527541,"owners_count":23782480,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws-ec2","database-experiment","docker","postgres","sql-queries","workload"],"created_at":"2024-08-06T08:03:14.988Z","updated_at":"2025-07-16T17:30:43.110Z","avatar_url":"https://github.com/postgres-ai.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"\u003ca href=\"https://postgres.ai\"\u003e\u003cimg src=\"https://img.shields.io/badge/Postgres-AI-orange.svg\" alt=\"Postgres.AI\" /\u003e\u003c/a\u003e\n  \u0026nbsp;\n[![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/badges/shields.svg)](github.com/postgres-ai/nancy)\n  \u0026nbsp;\n\u003cimg src=\"https://img.shields.io/docker/pulls/postgresmen/postgres-with-stuff.svg\" /\u003e\n  \u0026nbsp;\n[![CircleCI](https://circleci.com/gh/postgres-ai/nancy.svg?style=svg)](https://circleci.com/gh/postgres-ai/nancy)\n\n:warning: Nancy CLI project is on hold now. See details: https://gitlab.com/postgres-ai/nancy/-/issues/228\n\n# About\n\u003cimg width=\"200\" src=\"https://gitlab.com/postgres-ai-team/nancy/uploads/c5ebf02e1c39cc91c95e8beac8028b62/nancy.png\" align=\"right\"\u003e\n\nNancy helps to conduct automated database experiments.\n\nThe Nancy Command Line Interface is a unified way to manage automated\ndatabase experiments either in clouds or on-premise.\n\n### What is a Database Experiment?\n\nDatabase experiment is a set of actions performed to test\n * (a) specified SQL queries (\"workload\")\n * (b) on specified machine / OS / Postgres version (\"environment\")\n * (c) against specified database (\"object\")\n * (d) with an optional change – some DDL or config change (\"target\" or \"delta\").\n\nTwo main goals for any database experiment:\n * (1) validation – check that the specified workload is valid,\n * (2) benchmark – perform deep SQL query analysis.\n\nDatabase experiments are needed when you:\n - add or remove indexes;\n - for a new DB schema change, want to validate it and estimate migration time;\n - want to verify some query optimization ideas;\n - tune database configuration parameters;\n - do capacity planning and want to stress-test your DB in some environment;\n - plan to upgrade your DBMS to a new major version;\n - want to train ML model related to DB optimization.\n\n# Currently Supported Features\n\n* Works anywhere where Docker can run (checked: Linux Ubuntu/Debian, macOS)\n* Experiments are conducted in a Docker container with extended Postgres setup\n* Supported Postgres versions: 12 (default), 11, 10, 9.6\n* Postgres config specified via options, may be partial\n* Supported locations for experimental runs:\n  * Any machine with Docker installed\n  * AWS EC2:\n    * Run on AWS EC2 Spot Instances (using Docker Machine)\n    * Allow to specify EC2 instance type\n    * Auto-detect and use current lowest EC2 Spot Instance prices\n    * Support i3 instances (with NVMe SSD drives)\n    * Support arbitrary-size EBS volumes\n* Support local or remote (S3) files – config, dump, etc\n* The object (database) can be specified in various ways:\n  * Plain text\n  * Synthetic database generated by [pgbench](https://www.postgresql.org/docs/current/static/pgbench.html)\n  * Dump file (.sql, .gz, .bz2)\n* What to test (a.k.a. \"target\" or \"delta\"):\n  * Test Postgres parameters change\n  * Test DDL change (specified as \"do\" and \"undo\" SQL to return state)\n* Supported types of workload:\n  * Any custom SQL\n  * Synthetic workload generated by [pgbench](https://www.postgresql.org/docs/current/static/pgbench.html)\n  * \"Real workload\" based on Postgres logs (using [pgreplay](https://github.com/laurenz/pgreplay))\n* For \"real workload\", allow replaying it with increased speed\n* Allow to keep container alive for specified time after all steps are done\n* Collected artifacts:\n  * `pg_stat_statements` snapshot\n  * `pg_stat_database`, ...\n  * Workload SQL logs\n  * Deep SQL query analysis report\n\n# Requirements\n\n1) To use Nancy CLI you need Linux or MacOS with installed Docker.\n\n2) To run on AWS EC2 instances, you also need:\n  * AWS CLI https://aws.amazon.com/en/cli/\n  * Docker Machine https://docs.docker.com/machine/\n  * jq https://stedolan.github.io/jq/\n\n\n# Installation\n\nIn the minimal configuration, only a few steps are needed:\n\nNOTICE: The [Additional notes](#additional-notes)\u003c/a\u003e section contains\ninstructions useful in case of docker-related errors during `nancy run` calls.\nAlternatively, see Docker's official [post-installation instructions for Linux](https://docs.docker.com/install/linux/linux-postinstall/).\n\n1) Install Docker\n\nUbuntu/Debian:\n```shell\nsudo apt-get -y install docker\nsudo systemctl enable docker\nsudo systemctl start docker\n```\n\nRHEL7:\n```shell\nyum -y install docker\nsystemctl enable docker\nsystemctl start docker\n```\n\nMacOS (assuming that [Homebrew](https://brew.sh/) is installed):\n```shell\nbrew install docker\n```\nSee also: https://docs.docker.com/docker-for-mac/install/\n\n2) Clone this repo and adjust `$PATH`:\n```shell\ngit clone https://gitlab.com/postgres.ai/nancy.git\necho \"export PATH=\\$PATH:\"$(pwd)\"/nancy\" \u003e\u003e ~/.bashrc\nsource ~/.bashrc\n```\n\n3) Install jq\n- Ubuntu/Debian: `sudo apt-get -y install jq`\n- CentOS/RHEL: `sudo yum install jq`\n- MacOS: `brew install jq`\n\nAdditionally, to allow use of AWS EC2 instances:\n\n4) Install AWS CLI https://docs.aws.amazon.com/cli/latest/userguide/installing.html\n\n5) Install Docker Machine tools https://docs.docker.com/machine/install-machine/\n\n# Getting started\n\nStart with these commands:\n```shell\nnancy help\nnancy run help\n```\n\n# \"Hello World!\"\n\nLocally, on any Linux or macOS machine:\n```shell\necho \"create table hello_world as select i from generate_series(1, (10^6)::int) _(i);\" \\\n  | bzip2 \u003e ./sample.dump.bz2\n\n# \"Clean run\": w/o index\n# (seqscan is expected, total time ~150ms, depending on resources)\nnancy run \\\n  --db-dump file://$(pwd)/sample.dump.bz2 \\\n  --workload-custom-sql \"select i from hello_world where i between 10 and 20;\"\n\n# Now check how a regular btree index affects performance\n# (expected total time: ~0.05ms)\nnancy run \\\n  --db-dump file://$(pwd)/sample.dump.bz2 \\\n  --workload-custom-sql \"select i from hello_world where i between 10 and 20;\" \\\n  --delta-sql-do \"create index i_hello_world_i on hello_world(i);\" \\\n  --delta-sql-undo \"drop index i_hello_world_i;\"\n```\n\nAWS EC2:\n```shell\nnancy run \\\n  --run-on aws \\\n  --aws-ec2-type \"i3.large\" \\\n  --aws-keypair-name awskey \\\n  --aws-ssh-key-path file://$(echo ~)/.ssh/awskey.pem  \\\n  --db-dump \"create table hello_world as select i from generate_series(1, (10^6)::int) _(i);\" \\\n  --workload-custom-sql \"select i from hello_world where i between 10 and 20;\"\n```\n\n# Additional notes\n\nOn Linux, if you experience issues with running (locally) `nancy run` inside `screen` or\n`tmux`, double-check that Docker is running and add your user to the `docker`\ngroup, as described below. See also: https://docs.docker.com/install/linux/linux-postinstall/.\n\nUbuntu/Debian:\n```shell\n# Ubuntu/Debian\nsudo usermod -aG docker ${USER}\nnewgrp docker\n```\n\nCentOS/RHEL:\n```shell\nsudo usermod -aG dockerroot ${USER}\nnewgrp dockerroot\n```\n\nOn MacOS, it is recommended to specify `--tmp-path` explicitly, similar to this:\n```\nmkdir ./tmp\nnancy run ... --tmp-path \"$(pwd)/tmp\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostgres-ai%2Fnancy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpostgres-ai%2Fnancy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostgres-ai%2Fnancy/lists"}