# pgsh > Developer Tools for PostgreSQL Latest version **0.12.1** (published 2022-03-13) · MIT license · 0 weekly downloads ## Install ```sh npm install pgsh pnpm add pgsh yarn add pgsh bun add pgsh ``` Provides the command `pgsh`. ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support; pre 1.0. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 0.12.1 | | Published | 2022-03-13 | | First published | 2019-02-18 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 22 | | Unpacked size | 2.4 MB | | Known vulnerabilities | 0 (+5 in 4 direct dependencies) | | Install scripts | no | | Author | Cameron Gorrie | | Maintainers | sastraxi | ## Links - npm: https://www.npmjs.com/package/pgsh - Repository: https://github.com/sastraxi/pgsh - npm.io page: https://npm.io/package/pgsh ## Dependencies (22) - [pg](https://npm.io/package/pg.md) ^8.5.1 - [tmp](https://npm.io/package/tmp.md) ^0.1.0 - [knex](https://npm.io/package/knex.md) ^0.20.2 - [debug](https://npm.io/package/debug.md) ^4.1.1 - [yargs](https://npm.io/package/yargs.md) ^15.0.2 - [dotenv](https://npm.io/package/dotenv.md) ^8.2.0 - [moment](https://npm.io/package/moment.md) ^2.24.0 - [backoff](https://npm.io/package/backoff.md) ^2.5.0 - [request](https://npm.io/package/request.md) ^2.88.0 - [bluebird](https://npm.io/package/bluebird.md) ^3.7.1 - [enquirer](https://npm.io/package/enquirer.md) ^2.3.2 - [cli-table](https://npm.io/package/cli-table.md) ^0.3.1 - [deep-equal](https://npm.io/package/deep-equal.md) ^1.0.1 - [@folder/xdg](https://npm.io/package/@folder/xdg.md) ^2.1.1 - [ansi-colors](https://npm.io/package/ansi-colors.md) ^4.1.1 - [cli-spinner](https://npm.io/package/cli-spinner.md) ^0.2.10 - [find-config](https://npm.io/package/find-config.md) ^1.0.0 - [lodash.pick](https://npm.io/package/lodash.pick.md) ^4.4.0 - [merge-options](https://npm.io/package/merge-options.md) ^2.0.0 - [lodash.flattendeep](https://npm.io/package/lodash.flattendeep.md) ^4.4.0 - [pg-connection-string](https://npm.io/package/pg-connection-string.md) ^2.1.0 - [request-promise-native](https://npm.io/package/request-promise-native.md) ^1.0.8 ## Recent versions - 0.12.1 (latest) — 2022-03-13 - 0.12.0 — 2021-01-14 - 0.11.5 — 2020-03-18 - 0.11.4 — 2020-03-18 - 0.11.3 — 2019-12-29 - 0.11.2 — 2019-12-01 - 0.11.1 — 2019-12-01 - 0.11.0 — 2019-12-01 - 0.10.7 — 2019-11-28 - 0.10.6 — 2019-11-27 - 0.10.5 — 2019-11-26 - 0.10.4 — 2019-11-26 - 0.10.3 — 2019-11-26 - 0.10.2 — 2019-11-26 - 0.10.1 — 2019-11-26 - … 29 more at https://npm.io/package/pgsh/versions ## README ## **pgsh**: PostgreSQL tools for local development [![npm](https://img.shields.io/npm/v/pgsh.svg)](https://npmjs.com/package/pgsh) ![license](https://img.shields.io/github/license/sastraxi/pgsh.svg) ![circleci](https://img.shields.io/circleci/project/github/sastraxi/pgsh/master.svg) ![downloads](https://img.shields.io/npm/dm/pgsh.svg)

Finding database migrations painful to work with? Switching contexts a chore? [Pull requests](docs/pull-requests.md) piling up? `pgsh` helps by managing a connection string in your `.env` file and allows you to [branch your database](docs/branching.md) just like you branch with git. --- ## Prerequisites There are only a couple requirements: * your project reads its database configuration from the environment * it uses a `.env` file to do so in development. > See [dotenv](https://www.npmjs.com/package/dotenv) for more details, and [The Twelve-Factor App](https://12factor.net) for why this is a best practice. | Language / Framework | `.env` solution | Maturity | | -------------------- | --------------- | -------- | | javascript | [dotenv](https://www.npmjs.com/package/dotenv) | high | pgsh can help even more if you use [knex](https://knexjs.org) for migrations. ## Installation 1. `yarn global add pgsh` to make the `pgsh` command available everywhere 2. `pgsh init` to create a `.pgshrc` config file in your project folder, beside your `.env` file (see `src/pgshrc/default.js` for futher configuration) 3. You can now run `pgsh` anywhere in your project directory (try `pgsh -a`!) 4. It is recommended to check your `.pgshrc` into version control. [Why?](docs/pgshrc.md) ## URL vs split mode There are two different ways pgsh can help you manage your current connection (`mode` in `.pgshrc`): * `url` (default) when one variable in your `.env` has your full database connection string (e.g. `DATABASE_URL=postgres://...`) * `split` when your `.env` has different keys (e.g. `PG_HOST=localhost`, `PG_DATABASE=myapp`, ...) ## Running tests 1. Make sure the postgres client and its associated tools (`psql`, `pg_dump`, etc.) are installed locally 2. `cp .env.example .env` 3. `docker-compose up -d` 4. Run the test suite using `yarn test`. Note that this test suite will destroy all databases on the connected postgres server, so it will force you to send a certain environment variable to confirm this is ok. --- ## Command reference * `pgsh init` generates a `.pgshrc` file for your project. * `pgsh url` prints your connection string. * `pgsh psql -- ` connects to the current (or *name*d) database with psql * `pgsh current` prints the name of the database that your connection string refers to right now. * `pgsh` or `pgsh list ` prints all databases, filtered by an optional filter. Output is similar to `git branch`. By adding the `-a` option you can see migration status too! ## Database branching Read up on the recommended [branching model](docs/branching.md) for more details. * `pgsh clone ` clones your current (or the `from`) database as *name*, then (optionally) runs `switch `. * `pgsh create ` creates an empty database, then runs `switch ` and optionally migrates it to the latest version. * `pgsh switch ` makes *name* your current database, changing the connection string. * `pgsh destroy ` destroys the given database. *This cannot be undone.* You can maintain a blacklist of databases to protect from this command in `.pgshrc` ## Dump and restore * `pgsh dump ` dumps the current database (or the *name*d one if given) to stdout * `pgsh restore ` restores a previously-dumped database as *name* from stdin ## Migration management (via knex) pgsh provides a slightly-more-user-friendly interface to knex's [migration system](https://knexjs.org/#Migrations). * `pgsh up` migrates the current database to the latest version found in your migration directory. * `pgsh down ` down-migrates the current database to *version*. Requires your migrations to have `down` edges! * `pgsh force-up` re-writes the `knex_migrations` table *entirely* based on your migration directory. In effect, running this command is saying to knex "trust me, the database has the structure you expect". * `pgsh force-down ` re-writes the `knex_migrations` table to not include the record of any migration past the given *version*. Use this command when you manually un-migrated some migations (e.g. a bad migration or when you are trying to undo a migration with missing "down sql"). * `pgsh validate` compares the `knex_migrations` table to the configured migrations directory and reports any inconsistencies between the two. --- _Source: https://npm.io/package/pgsh · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._