8 unstable releases (3 breaking)
0.5.0 | Aug 27, 2024 |
---|---|
0.4.3 | Jul 23, 2024 |
0.4.2 | Apr 8, 2024 |
0.4.1 | Dec 6, 2023 |
0.2.0 | Oct 9, 2023 |
#1088 in Database interfaces
230KB
4.5K
SLoC
⚠️ ALPHA QUALITY ⚠️
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.
pgdo-cli
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.
Getting started
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
clone Perform a one-off clone/backup of an existing cluster
backup Point-in-time backup for an existing cluster
restore Point-in-time restore/recovery from a backup made previously with the `backup` command
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: 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
10.22 /opt/homebrew/Cellar/postgresql@10/10.22_6/bin
11.21 /opt/homebrew/Cellar/postgresql@11/11.21/bin
12.16 /opt/homebrew/Cellar/postgresql@12/12.16/bin
13.12 /opt/homebrew/Cellar/postgresql@13/13.12/bin
14.9 /opt/homebrew/Cellar/postgresql@14/14.9/bin
15.4 /opt/homebrew/Cellar/postgresql@15/15.4/bin
=> 16.0 /opt/homebrew/bin
$ pgdo shell
postgres=# select …
$ pgdo exec pg_dump
--
-- PostgreSQL database dump
--
…
Contributing
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
.
Running the tests
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.
Making a release
See pgdo-lib for notes on how to make a release.
License
This package is licensed under the Apache 2.0 License.
Dependencies
~35–49MB
~704K SLoC