{"id":13724460,"url":"https://github.com/sastraxi/pgsh","last_synced_at":"2025-04-13T05:06:12.428Z","repository":{"id":38430623,"uuid":"170973361","full_name":"sastraxi/pgsh","owner":"sastraxi","description":"Branch your PostgreSQL Database like Git","archived":false,"fork":false,"pushed_at":"2023-01-11T02:40:07.000Z","size":3309,"stargazers_count":582,"open_issues_count":34,"forks_count":19,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-04T12:05:14.765Z","etag":null,"topics":["dotenv","git","knex","postgresql","psql"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/pgsh","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sastraxi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-02-16T06:59:55.000Z","updated_at":"2025-04-03T19:21:20.000Z","dependencies_parsed_at":"2023-02-08T23:31:58.139Z","dependency_job_id":null,"html_url":"https://github.com/sastraxi/pgsh","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sastraxi%2Fpgsh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sastraxi%2Fpgsh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sastraxi%2Fpgsh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sastraxi%2Fpgsh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sastraxi","download_url":"https://codeload.github.com/sastraxi/pgsh/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248665748,"owners_count":21142123,"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":["dotenv","git","knex","postgresql","psql"],"created_at":"2024-08-03T01:01:57.547Z","updated_at":"2025-04-13T05:06:12.390Z","avatar_url":"https://github.com/sastraxi.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Compiled list","CLI"],"sub_categories":["plv8:"],"readme":"## **pgsh**: PostgreSQL tools for local development\n\n[![npm](https://img.shields.io/npm/v/pgsh.svg)](https://npmjs.com/package/pgsh)\n![license](https://img.shields.io/github/license/sastraxi/pgsh.svg)\n![circleci](https://img.shields.io/circleci/project/github/sastraxi/pgsh/master.svg)\n![downloads](https://img.shields.io/npm/dm/pgsh.svg)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/pgsh-intro-620.gif\"\u003e\n\u003c/p\u003e\n\nFinding 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.\n\n---\n\n## Prerequisites\nThere are only a couple requirements:\n\n* your project reads its database configuration from the environment\n* it uses a `.env` file to do so in development.\n\n\u003e 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.\n\n| Language / Framework | `.env` solution | Maturity |\n| -------------------- | --------------- | -------- |\n| javascript | [dotenv](https://www.npmjs.com/package/dotenv) | high |\n\npgsh can help even more if you use [knex](https://knexjs.org) for migrations.\n\n## Installation\n\n1. `yarn global add pgsh` to make the `pgsh` command available everywhere\n2. `pgsh init` to create a `.pgshrc` config file in your project folder, beside your `.env` file (see `src/pgshrc/default.js` for futher configuration)\n3. You can now run `pgsh` anywhere in your project directory (try `pgsh -a`!)\n4. It is recommended to check your `.pgshrc` into version control. [Why?](docs/pgshrc.md)\n\n## URL vs split mode\nThere are two different ways pgsh can help you manage your current connection (`mode` in `.pgshrc`):\n* `url` (default) when one variable in your `.env` has your full database connection string (e.g. `DATABASE_URL=postgres://...`)\n* `split` when your `.env` has different keys (e.g. `PG_HOST=localhost`, `PG_DATABASE=myapp`, ...)\n\n## Running tests\n\n1. Make sure the postgres client and its associated tools (`psql`, `pg_dump`, etc.) are installed locally\n2. `cp .env.example .env`\n3. `docker-compose up -d`\n4. Run the test suite using `yarn test`. Note that this test suite will destroy all\n   databases on the connected postgres server, so it will force you to send a certain\n   environment variable to confirm this is ok.\n\n---\n\n## Command reference\n\n* `pgsh init` generates a `.pgshrc` file for your project.\n* `pgsh url` prints your connection string.\n* `pgsh psql \u003cname?\u003e -- \u003cpsql-options...?\u003e` connects to the current (or *name*d) database with psql\n* `pgsh current` prints the name of the database that your connection string refers to right now.\n* `pgsh` or `pgsh list \u003cfilter?\u003e` 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!\n\n## Database branching\n\nRead up on the recommended [branching model](docs/branching.md) for more details.\n\n* `pgsh clone \u003cfrom?\u003e \u003cname\u003e` clones your current (or the `from`) database as *name*, then (optionally) runs `switch \u003cname\u003e`.\n* `pgsh create \u003cname\u003e` creates an empty database, then runs `switch \u003cname\u003e` and optionally migrates it to the latest version.\n* `pgsh switch \u003cname\u003e` makes *name* your current database, changing the connection string.\n* `pgsh destroy \u003cname\u003e` destroys the given database. *This cannot be undone.* You can maintain a blacklist of databases to protect from this command in `.pgshrc`\n\n## Dump and restore\n\n* `pgsh dump \u003cname?\u003e` dumps the current database (or the *name*d one if given) to stdout\n* `pgsh restore \u003cname\u003e` restores a previously-dumped database as *name* from stdin\n\n## Migration management (via knex)\n\npgsh provides a slightly-more-user-friendly interface to knex's [migration system](https://knexjs.org/#Migrations).\n\n* `pgsh up` migrates the current database to the latest version found in your migration directory.\n\n* `pgsh down \u003cversion\u003e` down-migrates the current database to *version*. Requires your migrations to have `down` edges!\n\n* `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\".\n\n* `pgsh force-down \u003cversion\u003e` 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\").\n\n* `pgsh validate` compares the `knex_migrations` table to the configured migrations directory and reports any inconsistencies between the two.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsastraxi%2Fpgsh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsastraxi%2Fpgsh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsastraxi%2Fpgsh/lists"}