{"id":16333906,"url":"https://github.com/nmattia/pg-shell","last_synced_at":"2026-05-07T18:05:50.531Z","repository":{"id":94701016,"uuid":"125123951","full_name":"nmattia/pg-shell","owner":"nmattia","description":"PostgreSQL, in a shell.","archived":false,"fork":false,"pushed_at":"2018-03-17T22:38:03.000Z","size":415,"stargazers_count":2,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-26T16:42:05.297Z","etag":null,"topics":["bash","postgresql"],"latest_commit_sha":null,"homepage":null,"language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nmattia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-03-13T22:42:53.000Z","updated_at":"2021-11-16T04:52:57.000Z","dependencies_parsed_at":"2023-05-26T17:30:47.478Z","dependency_job_id":null,"html_url":"https://github.com/nmattia/pg-shell","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmattia%2Fpg-shell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmattia%2Fpg-shell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmattia%2Fpg-shell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmattia%2Fpg-shell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nmattia","download_url":"https://codeload.github.com/nmattia/pg-shell/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239321399,"owners_count":19619697,"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":["bash","postgresql"],"created_at":"2024-10-10T23:36:53.897Z","updated_at":"2025-11-01T20:30:19.361Z","avatar_url":"https://github.com/nmattia.png","language":"Nix","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pg-shell: PostgreSQL in a shell\n\nThe `pg-shell` environment allows you to run PostgreSQL instances with _no\nstrings attached_. The associated processes and data disappear when you exit\nyour shell.\n\n\u003cimg src=\"pgshell.png\" alt=\"pg-shell\" style=\"width: 400px;\"/\u003e\n\n# Usage\n\n_The examples assume that the [`pg-shell`](./pg-shell) script was loaded. For\ninstallation instructions, see the [Install](#install) section below._\n\nBy loading the [`pg-shell`](./pg-shell) script you import three functions into\nyour environment: `start_pg`, `list_pg` and `stop_pg`. You can use those to\nrespectively start a new PostgreSQL instance, list the currently running\n(`pg-shell`) PostgreSQL instances and stop a particular PostgreSQL instance.\n\nStarting a local PostgreSQL instance is very easy:\n\n``` shell\n$ start_pg\nCreating /home/nicolas/projects/nmattia/pg-shell/.pg/gentle-british-time directory\nStarting postgres...\n...\nNow starting postgres...\nPostgres started\nLogs are written to /home/nicolas/projects/nmattia/pg-shell/.pg/gentle-british-time/pglog.\n\n   name:  gentle-british-time\n   pid:   24901\n   port:  5432\n```\n\nThe `start_pg` function will start a PostgreSQL instance running in the\nbackground. By default the instance is started on port `5432` and the data is\nlocated in `\u003cROOT\u003e/.pg/\u003cNAME\u003e`, where `ROOT` is the directory from which you\n_evaluated_ the [`pg-shell`](./pg-shell) script and `NAME` is a randomly\ngenerated name. In the example above, the `ROOT` is\n`/home/nicolas/projects/nmattia/pg-shell/` and the randomly generated name\n`NAME` is `gentle-british-time`. You can stop the instance by exiting the\nshell:\n\n``` shell\n$ exit\nstopping gentle-british-time\nkilling 24901\nremoving /home/nicolas/projects/nmattia/pg-shell/.pg/gentle-british-time\n```\n\nWhen calling `start_pg` you may specify the name and port of the PostgreSQL\ninstance (note that the \"name\" of the instance is a `pg-shell` concept and has\nnothing to do with database names). Specifying the port is necessary if you\nneed several instances running at the same time:\n\n``` shell\n$ start_pg\nCreating /home/nicolas/projects/nmattia/pg-shell/.pg/brave-italian-way directory\nStarting postgres...\n...\nNow starting postgres...\nPostgres started\nLogs are written to /home/nicolas/projects/nmattia/pg-shell/.pg/brave-italian-way/pglog.\n\n   name:  brave-italian-way\n   pid:   25743\n   port:  5432\n\n$ start_pg --name some-name --port 5555\nname read from input: some-name\nport read from input: 5555\nCreating /home/nicolas/projects/nmattia/pg-shell/.pg/some-name directory\nStarting postgres...\n...\nNow starting postgres...\nPostgres started\nLogs are written to /home/nicolas/projects/nmattia/pg-shell/.pg/some-name/pglog.\n\n   name:  some-name\n   pid:   25768\n   port:  5555\n```\n\nYou can list the names of your running instances:\n\n``` shell\n$ list_pg\nbrave-italian-way\nsome-name\n```\n\nAll instances will be destroyed upon shell exit:\n\n``` shell\n$ exit\nstopping some-name\nkilling 25768\nremoving /home/nicolas/projects/nmattia/pg-shell/.pg/some-name\nstopping brave-italian-way\nkilling 25743\nremoving /home/nicolas/projects/nmattia/pg-shell/.pg/brave-italian-way\n```\n\n## Install\n\nThe `pg-shell` script needs access to two PostgreSQL executables, namely:\n\n* `initdb` for initializing the databases, and\n* `postgres` for starting the databases,\n\nwhich you can either install from your system's package manager (e.g. `sudo apt\ninstall postgresql`) or through a nix-shell with the following command:\n\n``` shell\n$ nix-shell -p postgresql\n```\n\nOnce PostgreSQL is available, the simplest usage is to source the release:\n\n``` shell\n$ eval \"$(curl https://nmattia.github.io/pg-shell/v0-0-1)\"\n```\n\nAlternatively, you can clone the repository (or simply get a copy of\n[`pg-shell`](./pg-shell)) and source it:\n\n``` shell\n$ . path/to/nmattia-pg-shell/pg-shell\n```\n\nBoth of the above commands will load `start_pg()`, `list_pg()` and `stop_pg()`\nin your environment.\n\n# Release checklist\n\n1. Make sure you're on (the latest) master and that all files have been\n   committed.\n\n1. Review the previous releases with `git tag -l`.\n\n1. Decide on the new version: `MAJOR-MINOR-PATCH`.\n\n    \u003e Given a version number MAJOR.MINOR.PATCH, increment the:\n    \u003e\n    \u003e MAJOR version when you make incompatible API changes,\n    \u003e MINOR version when you add functionality in a backwards-compatible\n    \u003e manner, and\n    \u003e PATCH version when you make backwards-compatible bug fixes.\n\n1. Check out the Github Pages branch:\n\n    ``` shell\n    $ git worktree add gh-pages gh-pages\n    ```\n\n1. Copy the latest pg-shell to the Github Pages branch:\n\n    ``` shell\n    $ cp pg-shell gh-pages/vMAJOR-MINOR-PATCH\n    $ git -C gh-pages/ add -A\n    $ git -C gh-pages/ commit -m \"Release vMAJOR-MINOR-PATCH\"\n    $ git -C gh-pages/ push\n    ```\n\n1. Tag the commit with `git tag vMAJOR-MINOR-PATCH`.\n1. Push with `git push --follow-tags`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnmattia%2Fpg-shell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnmattia%2Fpg-shell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnmattia%2Fpg-shell/lists"}