{
    "info": {
        "author": "William Bruschi",
        "author_email": "william.bruschi@gmail.com",
        "bugtrack_url": null,
        "classifiers": [
            "Operating System :: OS Independent",
            "Programming Language :: Python :: 3"
        ],
        "description": "pghops is a command line PostgreSQL schema migration utility written\nin Python. It aims to be the simplest database migration utility for\nPostgreSQL.\n\n1. [Features](#features)\n2. [Demo](#demo)\n3. [Usage Overview](#usage-overview)\n4. [Installation](#installation)\n5. [Best Practices](#best-practices)\n6. [Options](#options)\n7. [Managing Indexes](#managing-indexes)\n8. [Unit Testing](#unit-testing)\n9. [FAQ](#faq)\n10. [Miscellaneous](#miscellaneous)\n11. [License](#license)\n\n## Features\n\n* **Simple version file syntax:** pghops version files are yaml files\n  with keys representing directories and values of one or more sql\n  file names.\n* **Executes scripts with psql:** pghops uses psql to execute all sql,\n  leveraging the extensive functionality of the PostgreSQL client. Use\n  any psql command in your scripts.\n* **Unit testing framework:** pghops comes equipped with its own unit\n  testing framework. No more excuses for skipping sql unit tests!\n* **All or nothing migrations:** Wrap your entire migration in a\n  single transaction or each migration script in its own transaction.\n* **All sql commands saved to version table** pghops saves all sql\n  executed during migrations to its version table. Make the auditors\n  happy!\n\n## Demo\n\nThe below terminal session shows how to create a database named `mydb`\nthat contains two tables: `account` and `account_email`. We will\ncreate a simple test to ensure you cannot insert null emails into the\n`account_email` table. Then we will create a database function for\ncreating accounts, along with another unit test.\n\n```\n[mycluster]$ # Create a directory named after the database, along with a script to create the database.\n[mycluster]$ mkdir mydb\n[mycluster]$ echo \"create database mydb;\" > mydb/create_database.sql\n[mycluster]$ # Create a directory to hold our table definitions.\n[mycluster]$ mkdir -p mydb/schemas/public/tables\n[mycluster]$ # Create SQL files containing our table definitions.\n[mycluster]$ cat - > mydb/schemas/public/tables/account.sql <<EOF\n> create table if not exists public.account (\n>   account_id bigserial primary key\n> );\n> EOF\n[mycluster]$ cat - > mydb/schemas/public/tables/account_email.sql <<EOF\n> create table if not exists public.account_email (\n>   account_email_id bigserial primary key\n>   , account_id bigint not null references account\n>   , email text not null\n> );\n> EOF\n[mycluster]$ # Create our first migration file\n[mycluster]$ mkdir mydb/versions\n[mycluster]$ cat - > mydb/versions/0001.0001.0001.init.yml <<EOF\n> public/tables:\n>   - account\n>   - account_email\n> EOF\n[mycluster]$ # Create our first unit test to ensure we cannot insert NULLs into account_email.email\n[mycluster]$ mkdir mydb/tests\n[mycluster]$ cat - > mydb/tests/01_account_email_test.sql <<EOF\n> insert into account values (default);\n> insert into account_email (account_id, email) values ((select max(account_id) from account), null);\n> EOF\n[mycluster]$ # Generated the 'expected' file and review it.\n[mycluster]$ pghops_test generate\n2019-02-23 14:18:42.452426: Looping through tests in /tmp/mycluster/mydb/tests\n2019-02-23 14:18:42.458661: Stopping Postgres pghops-postgresql.\n2019-02-23 14:18:42.476721: Starting Postgres pghops-postgresql postgres.\n2019-02-23 14:18:45.632209: Done starting postgres pghops-postgresql.\n2019-02-23 14:18:45.673046: Migrating cluster /tmp/mycluster.\n2019-02-23 14:18:45.673440: Migrating database mydb\n2019-02-23 14:18:45.674398: Database mydb does not exist. Creating it with /tmp/mycluster/mydb/create_database.sql.\ncreate database mydb;\nCREATE DATABASE\n\n...\n<output elided>\n...\n\n2019-02-23 14:18:46.106990: Done migrating database mydb\n2019-02-23 14:18:46.107123: Done all migrations.\n2019-02-23 14:18:46.132066: Generated 01_account_email_test.sql expected file.\n2019-02-23 14:18:46.132145: Stopping Postgres pghops-postgresql.\n2019-02-23 14:18:48.449079: Done generating expected files!\n[mycluster]$ # Review the expected file.\n[mycluster]$ cat mydb/tests/01_account_email_expected.txt\ninsert into account values (default);\nINSERT 0 1\ninsert into account_email (account_id, email) values ((select max(account_id) from account), null);\nERROR:  null value in column \"email\" violates not-null constraint\nDETAIL:  Failing row contains (1, 1, null).\n[mycluster]$ # Looks good! We received the error as expected. As a sanity check, run the tests and they should succeeded\n[mycluster]$ pghops_test run\n\n...\n<output elided>\n...\n\n2019-02-23 14:22:31.269604: All tests passed!\n[mycluster]$ # Lets run our first migration against a real db!\n[mycluster]$ pghops\n2019-02-23 14:23:47.225273: Migrating cluster /tmp/mycluster.\n2019-02-23 14:23:47.225539: Migrating database mydb\n2019-02-23 14:23:47.226114: Database mydb does not exist. Creating it with /tmp/mycluster/mydb/create_database.sql.\nCREATE DATABASE\n\n\nBEGIN\nCREATE SCHEMA\nCREATE TABLE\nCREATE TABLE\nCREATE INDEX\nINSERT 0 1\nCREATE TABLE\nCREATE TABLE\nINSERT 0 1\nCOMMIT\n\n\n2019-02-23 14:23:47.827395: Done migrating database mydb\n2019-02-23 14:23:47.827536: Done all migrations.\n[mycluster]$ # Check the version table if you wish\n[mycluster]$ psql --dbname=mydb --command=\"select major, minor, patch, label, file_name from pghops.version;\"\n major | minor | patch |    label    |            file_name\n-------+-------+-------+-------------+---------------------------------\n 0000  | 0000  | 0000  | pghops-init | 0000.0000.0000.pghops-init.yaml\n 0001  | 0001  | 0001  | init        | 0001.0001.0001.init.yml\n(2 rows)\n\n[mycluster]$ # Create a function that creates accounts.\n[mycluster]$ mkdir mydb/schemas/public/functions\n[mycluster]$ cat - > mydb/schemas/public/functions/create_account.sql <<EOF\ncreate or replace function public.create_account\n> (\n>   p_email text\n> )\n> returns bigint\n> language plpgsql\n> as \\$\\$\n> declare l_account_id bigint;\n> begin\n>\n>   insert into account (account_id) values (default) returning account_id into l_account_id;\n>\n>   insert into account_email (account_id, email) values (l_account_id, p_email);\n>\n>   return l_account_id;\n>\n> end\\$\\$;\n> EOF\n[mycluster]$ # Next create our second migration file.\n[mycluster]$ cat - > mydb/versions/0001.0002.0001.create_account.yml <<EOF\n> public/functions: create_account\n> EOF\n[mycluster]$ # Create our second test\n[mycluster]$ echo \"select create_account('x@example.com');\" > mydb/tests/02_create_account_test.sql\n[mycluster]$ pghops_test generate\n2019-02-23 14:35:44.742060: Looping through tests in /tmp/mycluster/mydb/tests\n2019-02-23 14:35:44.748353: Stopping Postgres pghops-postgresql.\n2019-02-23 14:35:44.764216: Starting Postgres pghops-postgresql postgres.\n2019-02-23 14:35:47.726734: Done starting postgres pghops-postgresql.\n2019-02-23 14:35:47.767687: Migrating cluster /tmp/mycluster.\n2019-02-23 14:35:47.768116: Migrating database mydb\n2019-02-23 14:35:47.769223: Database mydb does not exist. Creating it with /tmp/mycluster/mydb/create_database.sql.\n...\n<output elided>\n...\n\n2019-02-23 14:35:48.230893: Done migrating database mydb\n2019-02-23 14:35:48.230981: Done all migrations.\n2019-02-23 14:35:48.251236: Generated 01_account_email_test.sql expected file.\n2019-02-23 14:35:48.269521: Generated 02_create_account_test.sql expected file.\n2019-02-23 14:35:48.269596: Stopping Postgres pghops-postgresql.\n2019-02-23 14:35:50.672626: Done generating expected files!\n[mycluster]$ cat mydb/tests/02_create_account_expected.txt\nselect create_account('x@example.com');\n create_account\n----------------\n              2\n(1 row)\n[mycluster]$ # Our new db function works! Lets run a migartion to update our db\n[mycluster]$ pghops\n2019-02-23 14:37:13.523780: Migrating cluster /tmp/mycluster.\n2019-02-23 14:37:13.524050: Migrating database mydb\nBEGIN\nCREATE FUNCTION\nINSERT 0 1\nCOMMIT\n\n\n2019-02-23 14:37:13.572099: Done migrating database mydb\n2019-02-23 14:37:13.572224: Done all migrations.\n[mycluster]$ psql --dbname=mydb --command=\"select major, minor, patch, label, file_name from pghops.version;\"\n major | minor | patch |     label      |             file_name\n-------+-------+-------+----------------+-----------------------------------\n 0000  | 0000  | 0000  | pghops-init    | 0000.0000.0000.pghops-init.yaml\n 0001  | 0001  | 0001  | init           | 0001.0001.0001.init.yml\n 0001  | 0002  | 0001  | create_account | 0001.0002.0001.create_account.yml\n(3 rows)\n\n[mycluster]$\n\n\n```\n\n## Usage Overview\n\nWhen you install PostgreSQL you initialize a storage area on disk\ncalled a [database\ncluster](https://www.postgresql.org/docs/current/creating-cluster.html),\nwhich is a collection of databases managed by a single instance of\nPostgreSQL. pghops expects you to place all files associated to\nbuilding and defining your cluster in a single directory, referred to\nhenceforth as the `cluster_directory`. Each sub-directory in\n`cluster_directory` should be the name of a database within your\ncluster (if not, you can add a file named `databases` that contains\nthe list of database directories).\n\nFor example, say your `cluster_directory` is /tmp/pghops/main and you\nhave two databases - dba and dbb. Your directory structure would look\nlike:\n```\n\u2514\u2500\u2500 main\n    \u251c\u2500\u2500 dba\n    \u2514\u2500\u2500 dbb\n```\n\npghops requires each database directory to have a sub-directory named\n`versions` which contain, you guessed it, all of you database\nmigration files. Each migration file must follow the following\nversioning convention:\n\n`<major>.<minor>.<patch>.<label>.yml`\n\nThis allows you to follow [Semantic Versioning](https://semver.org/)\nif you choose. pghops parses these file names and saves them to the\n`pghops.version` table.\n\nIf pghops detects the database does not exist on the cluster, pghops\nwill create it if the database directory has a file named\n`create_database.sql` containing the database creation\ncommands. pghops records all migrations in a table named `version` in\nthe schema `pghops`. If this table does not exist, pghops will run the\nincluded `0000.0000.0000.pghops-init.yaml` script first to create it.\n\nEach version file must be in yaml format and have a yaml or yml\nsuffix. The file can only contain comments and key / value pairs, with\nkeys representing directories and values of either a single file or a\nlist of files to execute. Directories can be absolute or relative to\neither the database directory or a directory named `schemas` within\nthe database directory. We recommend laying out your directory\nstructure the same as pgAdmin's. For example, if your\n`cluster_directory` looks like:\n```\n\u251c\u2500\u2500 cluster_a\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 databases\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 db_a1\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 create_database.sql\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 schemas\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 public\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0     \u251c\u2500\u2500 functions\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0     \u251c\u2500\u2500 tables\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0     \u2502\u00a0\u00a0 \u2514\u2500\u2500 visits.sql\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0     \u2514\u2500\u2500 views\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0         \u251c\u2500\u2500 vistor_view.sql\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0         \u2514\u2500\u2500 location_view.sql\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 versions\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0     \u251c\u2500\u2500 0000.0011.0001.change-a.yml\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0     \u251c\u2500\u2500 0000.0021.0002.change-b.yml\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0     \u2514\u2500\u2500 0000.0032.0000.change-c.yml\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 db_a2\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 create_database.sql\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 data\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 init-data.sql\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 schemas\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 public\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0     \u251c\u2500\u2500 functions\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0     \u251c\u2500\u2500 tables\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0     \u2502\u00a0\u00a0 \u2514\u2500\u2500 user.sql\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0     \u2514\u2500\u2500 views\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0         \u251c\u2500\u2500 user_view.sql\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0         \u2514\u2500\u2500 accounts_view.sql\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 versions\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0     \u251c\u2500\u2500 0000.0001.0001.feature-a.yml\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0     \u251c\u2500\u2500 0000.0001.0002.feature-b.yml\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0     \u2514\u2500\u2500 0000.0002.0000.feature-c.yml\n```\n\nand you want to use pghops to create new views defined in visitor_view\nand location_view, create a new migration script in db_a1/versions\nsuch as `0000.0033.0000.new-views.yml` and add the lines:\n\n```\nschemas/public/views:\n  - visitor_view.sql\n  - location_view.sql\n```\n\nYou can optionally omit the sql suffix. Again, `schemas` is optional\nas well.\n\nRun pghops by cd'ing into cluster_directory and running\n\n```\npghops\n```\n\nSee below for command line parameters. You can also pass the path of\n`cluster_directory` as the first argument.\n\nWhen you run pghops, it will concatenate the contents of\nvisitor_view.sql and location_view.sql into a single file and then\nexecute it via psql in a single transaction. If successful, a new\nrecord is added to pghops.version and your migration is complete! For\nmore examples see the [test\nclusters](src/tests/test_clusters/cluster_a).\n\n## Installation\n\n`pghops` requires python 3.7 and the psql client. `pghops_test`\nrequires docker. Install `pghops` with pip:\n\n```\npip3 install pghops\n```\n\nThis should add the executeables `pghops`, `pghops_test`, and\n`pghops_create_indexes` to your path.\n\n## Best Practices\n\n### Directory layout for your sql code\nI recommend following the same layout as pgAdmin. For example, if you\nhave a database named dba, one possibility is:\n```\n\u251c\u2500\u2500 dba\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 data\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 schemas\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 myschema\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 functions\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 tables\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 views\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 public\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0     \u251c\u2500\u2500 functions\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0     \u251c\u2500\u2500 tables\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0     \u2514\u2500\u2500 views\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 versions\n```\nThe `data` directory can contain scripts to load data during your\nmigrations.\n\n### Versioning\npghops is liberal when determining which migration files to\nexecute. It ignores the major, minor, and patch fields in the\npghops.version table and only looks at file_names.\n\nAs such, you can use whichever versioning scheme you like. [Semantic\nVersioning](https://semver.org/) is definitely a solid option. Another\nscheme, which requires slightly more effort for tracking but works\nwell when dealing with multiple people working with many branches, is\nto use an auto-incrementing number for `major` that increases on every\nmerge into your master/production branch. For `minor`, use something\nthat refers to either a feature branch or something that links back to\na ticketing system. For `patch`, use an incrementing number for\neach migration file you create for the feature. Use `label` to\ndifferentiate between two people creating migration scripts for the\nsame feature at the same time. This also helps to prevent merge\nconflicts.\n\n### Idempotency\nEssentially this means if you execute the same sql twice all changes\nwill only take affect once. So use \"if not exists\" when writing DDL\nstatements and check for the presence of your records first when\nexecuting update statements (or use the `on conflict do nothing`\nclause).\n\n### Keep old migration files up to date\nThe pghops.version table and Git (or another VCS) should be all you\nneed for auditing and history purposes. If you make changes that would\nbreak older migration scripts when run on a new database, best to go\nback and update the older scripts. Then you can use pghops to create a\nnew database from scratch for failover, setting up new environments,\nor testing purposes.\n\n### Passwords and psql\n\nNormally you want to avoid having to enter your password for every\npsql call. A couple options:\n\n1. Setup the user that runs pghops with password-less authentication,\n   such as [trust or\n   peer](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html). Best\n   then to run pghops on the same box as PostgreSQL.\n2. Use a [password\n   file](https://www.postgresql.org/docs/current/libpq-pgpass.html).\n\n## Options\n\npghops has many configuration options, which you can set via the\ncommand line, environment variables or various property files. Options\nare loaded in the following order, from highest to lowest priority:\n\n1. Command line arguments\n2. Properties in the file specified by the `--options-file` command line\n   argument.\n3. Environment variables.\n4. Properties in `<cluster-dir>/<db>/pghops.properties`\n5. Properties in `<cluster-dir>/pghops.properties`\n6. Properties in `pghops/conf/default.properties`\n\nProperty files should be in yaml format and contain key/value pairs.\n\npghops treats options in property files that only differ in case or\nusage of underscore versus hyphen the same. For example:\n\n```\nwrap-all-in-transaction\nwrap_all_in_transaction\nWrap_All_In_Transaction\n```\n\nall refer to the same option. Environment variables should use\nunderscores instead of hyphens, be in all caps, and have a prefix of\nPGHOPS_. For example, the environment varaible for the\nwrap-all-in-transaction property above is\nPGHOPS_WRAP_ALL_IN_TRANSACTION.\n\npsql's environment variables are also in effect.\n\npghops options are as follows:\n\n**cluster_directory** - The first argument to pghops. Defaults to the\ncurrent working directory. The base directory containing your database\nsql.\n\n**dbname** - By default pghops will migrate all dbs in the cluster\ndirectory. Use this option to only update the specified db.\n\n**cluster_map** - Path to a yaml file containing a map of cluster names to\ndirectories. The cluster name can then be supplied as the\ncluster_directory argument instead of a directory.\n\n**dry_run** - Do not execute the migration, only print the files that\nwould have executed.\n\n**verbosity** - Verbosity level. One of default, verbose, or terse.\n\"terse\" only prints errors. \"verbose\" echos all executed sql.\n\n**psql_base_args** - \"Base\" arguments to psql. Defaults to \"--set\nON_ERROR_STOP=1 --no-psqlrc\". Use this in combination with\npsql_arguments.\n\n**psql_arguments** - A list of arguments to provide to psql, such as\n--host, --port, etc.\n\n**db_conninfo** - Alternative way to specify the connection parameters to\npsql.\n\n**wrap_all_in_transaction** - When true, the default, pghops will wrap the\nentire migration in a single transaction.\n\n**wrap_each_version_in_transaction** - When true, each version script will\nrun in its own transaction, not the entire migration.\n\n**fail_if_unable_to_connect** - When true, the default, pghops will raise\nan error if it cannot connect to the database server.\n\n**fail_if_standby** - When true, the default, pghops will raise an error\nif it can connect to the database server but the database server is in\nstandby mode.\n\n**save_sql_to_version_table** - When true, the default, pghops will save\nall executed sql to the pghops.version table. Consider setting to\nfalse for large migrations or migrations that contain sensitive info.\n\n**save_indexes** - When true, the default, pghops scans you sql code for\ncreate index statements and saves them to the pghops.index table. See\nbelow for more details.\n\n**migration_file** - Use this option to only execute the supplied file\ninstead of all files in the versions directory.\n\n**script_suffixes** - A case-insensitive comma separated list of\nsuffixes that migration file names must match in order to be\nexecuted. Defaults to yml and yaml.\n\n**option_file** - When supplied, also load options contained within\nthis properties file.\n\n## Managing Indexes\n\nAs your schema evolves, you may find the need to create new indexes on\nlarge, existing tables. If creating indexes during the migration is\nunacceptable, you can have pghops manage indexes for you so you can\ncreate them asynchronously at a later time.\n\nBy setting the option `save-indexes` to true (the default), pghops\nwill scan your sql code for create index statements and save any to\n`pghops.index`. For pghops to track an index, ensure the following:\n\n1. The index statement resides in a file with a '.sql' suffix.\n2. The entire index statement resides on a single line.\n3. The index statement begins on the first column of the line. pghops\n   ignores any indexes statements preceded by white space. Useful if,\n   for example, you have a function that creates a temp table and\n   defines indexes on said temp table, you do not want pghops to\n   manage this index.\n4. Use fully qualified table names in you index definitions\n   (schema.table_name). The create indexes script first checks for the\n   existence of the table before executing the index statement, and\n   when pghops saves an index it does not analyze any preceding set\n   path statements. If you do not use a fully qualified table name\n   pghops will not save the index.\n5. The statement uses `if not exists` so it can be run multiple times\n   without causing an error.\n6. The scanning for indexes is not perfect. If you use unconventional\n   names for your index or table which requires quoting the name,\n   pghops cannot parse the statement correctly.\n\nBy scanning your code for indexes, you can define indexes in the same\nfiles as their table and pghops will add them to pghops.index\nautomatically during the next migration.\n\nFor every record in `pghops.index`, `pghops_create_indexes` will first\ncheck to see if the table_name is a valid table. It then checks the\n`enabled` flag and, if set, executes the sql in `definition`. The\nscript runs in parallel based on the number of cpu cores, although\nthis advantage is mitigated in more recent PostgreSQLs that can create\na single index in parallel automatically.\n\n## Unit Testing\n\nUsing the `pghops_test` command, you can create and run simple SQL\nunit tests. You will need docker installed as the tests are run in a\nPostgreSQL docker container. Here's how it works:\n\n1. Create a directory named `tests` within your database directory.\n2. In the `tests` directory, create sql files ending in\n   `_test.sql`. Usually you will want the file names to contain a\n   number for ordering purposes, such as `01_base_test.sql`.\n3. Run `pghops_test generate`. This will launch a PostgreSQL docker\n   container, run the migration, then generate companion files for\n   each sql test file. For example, for the test file\n   `01_base_test.sql` it will generate `01_base_expected.txt`.\n4. Review the generated expected file. Ensure there is no host or\n   environment specific output, such as host names or timestamps.\n5. As your schema evolves, you can run `pghops_test run` to run your\n   unit test. It will launch a new PostgreSQL docker container, run\n   the migration, execute the unit test sql files and compare the\n   output to the contents of the expected files.\n\nIf you create many tests, you can organize them into suites by create\nsub-directories within the `tests` directory. Each suite is run within\nits own docker container.\n\n### Test Options\n\nOptions for `pghops_test` are loaded in the same way as `pghops`\nexcept it looks for property files named `pghops-test.properties` in\nthe test and test-suite directories. Test specific properties only\napply when running the tests, not when running the initial migration\nin the docker container.\n\n**command** - The only required option. Either `run` or `generate`.\n\n**test** - When provided, only runs the specific test. You can specify\na suite name, specific file, or specific file within a suite such as\nmy-suite/my-file_test.sql.\n\n**docker_name** - The name of the docker image to use. Defaults to\npostgresql.\n\n**docker_tag** - Optional docker tag. If omitted, uses latest.\n\n**docker_name** - The name of the docker container to create. Defaults\nto pghops-postgresql.\n\n**skip_docker_shutdown** - Do not kill the docker container after\nrunning the tests.\n\n**ignore_whitespace** - Whether or not to ignore whitespace when\ncomparing output against the expected files.\n\n**psql_base_migrations_args** - Similar to psql_base_args but only\napplies when running the migration.\n\n`pghops_test` also accepts the following arguments that are identical\nto the `pghops` arguments:\n\n**cluster_directory**, **dbname**, **psql_base_args**,\n**psql_arguments**, **db_conninfo**, **verbosity**, **option_file**\n\n## FAQ\n\n### What does pghops stand for?\n\nEither PostGresql Highly OPinionated migrationS. Or maybe you can use\npghops to \"hop\" to your next database version. Take your pick.\n\n### Why make pghops PostgresSQL specific? Why not make it database agnosistic by using drivers for the Python Database API?\n\nBy using psql you can leverage all of its power - your sql can contain\nany psql meta command which is not possible to do with adapters such\nas Psycopg.\n\n### Is there support for rolling back migrations?\n\nNo built in support. In a perfect world each database migration script\nwould be accompanied by a rollback script. But if something goes wrong\non production and you need to roll back, do you really feel\ncomfortable executing the rollback script? Have you tested all\npossible state that the rollback script can encounter?\n\nIn my experience the need to roll back is infrequent and when it is\nnecessary, careful examination of the database must happen before any\nchanges can take place. However, if you insist on having rollback\nscripts, you can initially create rollback files in the same versions\ndirectory and name them with a non-yaml suffix, such as\n.rollback. Then when you need to rollback, run pghops with the\n`--migration-file` option to run the rollback script. If you wish to\nerase the records from the pghops.version table, you will have to do\nthat manually.\n\n### I have dependencies between my databases and I need pghops to execute migrations in a particular order.\n\nIn your `cluster_directory`, create a file named `databases` and list\nthe databases in the required order.\n\n### What happens if I need to execute sql that cannot be in a transaction?\n\nProbably best to include a `commit` statement immediately preceding\nthe sql that cannot run inside a transaction, followed by a `begin`\nstatement to start a new transaction. You could also omit transactions\nfor this pghops run by setting the options wrap-all-in-transaction and\nwrap-each-version-in-transaction to false.\n\n### When working on a unit test, I don't want to re-run the entire migration when checking my changes.\n\nSet skip_docker_shutdown to True and supply a test name in your command. Example:\n\n`pghops_test --skip-docker-shutdown t generate 01_base_test.sql`\n\nThen next time you re-run the above command it will immediately\nexecute 01_base_test.sql against the docker container without having\nto re-launch.\n\n## Miscellaneous\n\npghops was developed and tested on GNU/Linux. Feel free to report bugs\nand contribute patches.\n\n## License\n\nGPLv3. See [COPYING](COPYING).\n\n\n",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/brewski82/pghops",
        "keywords": "PostgreSQL database migrations",
        "license": "GPLv3",
        "maintainer": "",
        "maintainer_email": "",
        "name": "pghops",
        "package_url": "https://pypi.org/project/pghops/",
        "platform": "",
        "project_url": "https://pypi.org/project/pghops/",
        "project_urls": {
            "Homepage": "https://github.com/brewski82/pghops"
        },
        "release_url": "https://pypi.org/project/pghops/2.0.1/",
        "requires_dist": [
            "PyYAML"
        ],
        "requires_python": ">=3.7",
        "summary": "A highly opionated Postgresql migration tool",
        "version": "2.0.1"
    },
    "last_serial": 5201314,
    "releases": {
        "1.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "5507c412f4cf3a3a60a24ee308a44917",
                    "sha256": "a24fe9608746a65c204d47bd17bc431d5e51a83fe46247ecd42475c701391e6d"
                },
                "downloads": -1,
                "filename": "pghops-1.0.0-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "5507c412f4cf3a3a60a24ee308a44917",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3.7",
                "size": 43789,
                "upload_time": "2019-01-01T13:01:45",
                "url": "https://files.pythonhosted.org/packages/a1/a8/023b82c7e703e3a6f46850018669a9d6703f750fccc84a39339d07d94d70/pghops-1.0.0-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "0c22a505001b61f3f3643d7907eee23e",
                    "sha256": "271cfdcc69518d7f22930f2d9a733fa7dea64602c2533384fe8458db3748be5d"
                },
                "downloads": -1,
                "filename": "pghops-1.0.0.tar.gz",
                "has_sig": false,
                "md5_digest": "0c22a505001b61f3f3643d7907eee23e",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.7",
                "size": 28585,
                "upload_time": "2019-01-01T13:01:47",
                "url": "https://files.pythonhosted.org/packages/54/ca/dde9adac23cba62d14efdb0b61c6b2e8cebcbf27fae3fbbac4a68c72d828/pghops-1.0.0.tar.gz"
            }
        ],
        "1.0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "9ec77e9a7604b0221bb8d2b59baf6860",
                    "sha256": "34575a9d643d8a1175121f0eee10cc6f35d90a7b879f64339be8c7b933266a8f"
                },
                "downloads": -1,
                "filename": "pghops-1.0.1-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "9ec77e9a7604b0221bb8d2b59baf6860",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3.7",
                "size": 43757,
                "upload_time": "2019-01-01T18:40:14",
                "url": "https://files.pythonhosted.org/packages/d4/b1/a0f28ed8701fd78faee6c184497c2d19412081718312f6f7b1b6fb288838/pghops-1.0.1-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "cbb99b3d7d9c2d28de10b1677a317b83",
                    "sha256": "b849baeb5e5ebda4b0267392ff55721a46b58f7cb60d0dbc381dcb1e0cb6b630"
                },
                "downloads": -1,
                "filename": "pghops-1.0.1.tar.gz",
                "has_sig": false,
                "md5_digest": "cbb99b3d7d9c2d28de10b1677a317b83",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.7",
                "size": 28510,
                "upload_time": "2019-01-01T18:40:16",
                "url": "https://files.pythonhosted.org/packages/dd/1c/d255222c70dee086d8889943534ff79dc79e0a83070a44a4ce907d9f1134/pghops-1.0.1.tar.gz"
            }
        ],
        "1.0.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "ff5c1ad41861059d0f8bd0b36317726a",
                    "sha256": "bd9d1196ba4f76af422527e83a8ea8c61ef66d692203a87554175f8210a5a8df"
                },
                "downloads": -1,
                "filename": "pghops-1.0.2-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "ff5c1ad41861059d0f8bd0b36317726a",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3.7",
                "size": 43778,
                "upload_time": "2019-01-03T15:14:19",
                "url": "https://files.pythonhosted.org/packages/dc/24/7ab212d63c0c5fb903142e98760782b6d3d724bdc2a22eefc1766cc54d22/pghops-1.0.2-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "f9ffbfab2e27fd75cc01ae5a0047b242",
                    "sha256": "0777d3223bbb130b3a65d0febd861da6e302072b0e0e07d9f1246690ddd4ed54"
                },
                "downloads": -1,
                "filename": "pghops-1.0.2.tar.gz",
                "has_sig": false,
                "md5_digest": "f9ffbfab2e27fd75cc01ae5a0047b242",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.7",
                "size": 28551,
                "upload_time": "2019-01-03T15:14:21",
                "url": "https://files.pythonhosted.org/packages/f8/c6/7c25307ffa394de1b585b98c6cf543ac62ed8360620b228b74d366f79394/pghops-1.0.2.tar.gz"
            }
        ],
        "2.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "3b65fc29f6dc85a98c9b39701745a55e",
                    "sha256": "51ccf29e78dbfe0bc88cf384e18dd085c39ae7c8b777381fe5a49ee7d344f395"
                },
                "downloads": -1,
                "filename": "pghops-2.0.0-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "3b65fc29f6dc85a98c9b39701745a55e",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3.7",
                "size": 52526,
                "upload_time": "2019-02-24T03:15:08",
                "url": "https://files.pythonhosted.org/packages/00/23/e48d6475e1e41eb3de14e7c61aa67dc47ea9fbb54e4d9a1d397ca5ee2374/pghops-2.0.0-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "1b4b774e67dfbf7fa496dc6df99576d3",
                    "sha256": "89c73145b9915615070c910e547662ba98a83fb6bdd14d145bf488a0636722d5"
                },
                "downloads": -1,
                "filename": "pghops-2.0.0.tar.gz",
                "has_sig": false,
                "md5_digest": "1b4b774e67dfbf7fa496dc6df99576d3",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.7",
                "size": 39210,
                "upload_time": "2019-02-24T03:15:10",
                "url": "https://files.pythonhosted.org/packages/3f/66/fd042a3f34235fd0e8f3306ea6d07f58a026912ca94b3fcab90a66c01f2a/pghops-2.0.0.tar.gz"
            }
        ],
        "2.0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "8e712167c4500cbd9bb49cfc1cbcfdab",
                    "sha256": "5dae751714e1a29c4fe1fb200ecde144ca57c8aea7c956d860bd80ae48eb4bf2"
                },
                "downloads": -1,
                "filename": "pghops-2.0.1-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "8e712167c4500cbd9bb49cfc1cbcfdab",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3.7",
                "size": 52524,
                "upload_time": "2019-04-29T01:50:32",
                "url": "https://files.pythonhosted.org/packages/3e/7f/fee0d10af93a6ceed2f63deddafadc2c57aa6351004ecb1f9506c517267d/pghops-2.0.1-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "ce76adc7915a26eee65165d3cb2af72e",
                    "sha256": "aeb9a40eeeb8673ae8fda9d739a02a8f439f6f5f3c94f230369a04e7f302fa68"
                },
                "downloads": -1,
                "filename": "pghops-2.0.1.tar.gz",
                "has_sig": false,
                "md5_digest": "ce76adc7915a26eee65165d3cb2af72e",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.7",
                "size": 39221,
                "upload_time": "2019-04-29T01:50:35",
                "url": "https://files.pythonhosted.org/packages/bd/cb/072ae26d8a0a47a6ed02af296225042f42fbe5c759379e19758227734889/pghops-2.0.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "8e712167c4500cbd9bb49cfc1cbcfdab",
                "sha256": "5dae751714e1a29c4fe1fb200ecde144ca57c8aea7c956d860bd80ae48eb4bf2"
            },
            "downloads": -1,
            "filename": "pghops-2.0.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "8e712167c4500cbd9bb49cfc1cbcfdab",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 52524,
            "upload_time": "2019-04-29T01:50:32",
            "url": "https://files.pythonhosted.org/packages/3e/7f/fee0d10af93a6ceed2f63deddafadc2c57aa6351004ecb1f9506c517267d/pghops-2.0.1-py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "ce76adc7915a26eee65165d3cb2af72e",
                "sha256": "aeb9a40eeeb8673ae8fda9d739a02a8f439f6f5f3c94f230369a04e7f302fa68"
            },
            "downloads": -1,
            "filename": "pghops-2.0.1.tar.gz",
            "has_sig": false,
            "md5_digest": "ce76adc7915a26eee65165d3cb2af72e",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 39221,
            "upload_time": "2019-04-29T01:50:35",
            "url": "https://files.pythonhosted.org/packages/bd/cb/072ae26d8a0a47a6ed02af296225042f42fbe5c759379e19758227734889/pghops-2.0.1.tar.gz"
        }
    ]
}