This project is in the early stages of development. It is far from feature complete. It likely contains many bugs and inconsistencies. Documentation is limited or non-existent. It will change in ways that break backwards compatibility. It is not ready for production use.
That said, if you want to try it out, please do! But bear in mind that it is being updated frequently, at least at the time I'm writing this, and you should expect to update it frequently too. Please check out known issues and file new ones here.
Thanks! Gavin.
A Rust command-line tool for creating standalone PostgreSQL clusters and databases with a focus on convenience and rapid prototyping – such as one sees using SQLite. Scaling down the developer experience to meet individuals working to build something new, build something rapidly, is a key goal of this project.
This is the front-end to pgdo-lib; in that package there's more information about the project as a whole.
After installing Cargo, cargo install pgdo-cli will install a
pgdo binary in ~/.cargo/bin, which the Cargo installation process will
probably have added to your PATH.
Note that this tool does not (yet) come with any PostgreSQL runtimes. You
must install these yourself. The pgdo command has some platform-specific
smarts and might be able to find those installed runtimes without further
configuration. To check, use the runtimes subcommand. If the runtime you want
to use doesn't show up, add its bin directory to PATH.
$ pgdo -h
The convenience of SQLite – but with PostgreSQL
Usage: pgdo [OPTIONS] [COMMAND]
Commands:
shell Start a psql shell, creating and starting the cluster as necessary (DEFAULT)
exec Execute an arbitrary command, creating and starting the cluster as necessary
runtimes List discovered PostgreSQL runtimes
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help (see more with '--help')
-V, --version Print version
Options for shell:
-D, --datadir <PGDATA> The directory in which the cluster lives [env: PGDATA=] [default: pgdo.cluster]
-d, --database <PGDATABASE> The database to connect to [env: PGDATABASE=] [default: postgres]
--mode <MODE> Run the cluster in a "safer" or "faster" mode [possible values: slower-but-safer, faster-but-less-safe]
--runtime-default <CONSTRAINT> Select the default runtime, used when creating new clusters
--destroy Destroy the cluster after use. WARNING: This will DELETE THE DATA DIRECTORY. The default is to NOT destroy the cluster
$ pgdo runtimes
15.19 /opt/homebrew/Cellar/postgresql@15/15.19/bin
16.15 /opt/homebrew/Cellar/postgresql@16/16.15/bin
17.11 /opt/homebrew/Cellar/postgresql@17/17.11/bin
=> 18.6 /opt/homebrew/Cellar/postgresql@18/18.6/bin
$ pgdo shell
postgres=# select …
$ pgdo exec pg_dump
--
-- PostgreSQL database dump
--
…By default, pgdo creates and uses a cluster in a directory named
pgdo.cluster in the current directory; use --datadir or PGDATA to choose
another. This is
PostgreSQL's data directory. pgdo also keeps a few files of its own in there,
all named pgdo.*, e.g. pgdo.lock, which coordinates pgdo processes using
the cluster. pgdo will use an existing cluster, but will only create a new one
in an empty directory.
Many pgdo processes can use the same cluster at once. The cluster is started
by the first, and stopped by the last.
Do not share a data directory between a host and a container, or between containers, e.g. via a bind mount. Processes on different kernels, e.g. macOS and a Linux VM, cannot coordinate, and could corrupt the cluster.
If you feel the urge to hack on this code, here's how to get started:
- Install Cargo,
- Clone this repository,
- Build it:
cargo build.
Right now, the pgdo package doesn't have many/any automated tests. That will surely change, but for now, please test your changes manually with as many PostgreSQL runtimes as you can. See pgdo-lib for platform-specific notes on installing runtimes.
See pgdo-lib for notes on how to make a release.
This package is licensed under the Apache 2.0 License.