README.md (view raw)
1# dbee
2
3`dbee` helps you to backup and restore your PostreSQL database trough S3 compatible servers (like Minio).
4Quickly save a dump from a server and init a new database on another server with a few commands.
5
6## Install
7
8### With NPM
9
10```shell
11npm i -g git+https://github.com/5ika/dbee.git
12```
13
14Command `dbee` will be globally available on your system.
15
16## Use
17
18### Quick-start
19
20#### 1. Add an S3 server
21
22```shell
23dbee s3 add mys3 minio.example.org --accessKey myaccesskey --secretKey mysecretkey
24```
25
26_mys3_ will be the reference name for this S3 server
27
28#### 2. Add a PostgreSQL server
29
30```shell
31dbee psql add mypsql psql.example.org --username myuser --password mypassword
32```
33
34_mypsql_ will be the reference name for this PSQL server.
35
36> If no password is provided at this step, it will be asked when needed.
37
38#### 3. Create a database dump
39
40```shell
41dbee bckp mypsql/mydbname
42```
43
44A dump of _mydbname_ database will be uploaded to _mys3_ S3 server.
45
46#### 4. Init a new database from dump
47
48```shell
49dbee ls # List available dumps on S3 server
50dbee init mydbname-2021-07-29T15:10:19.748Z.bak myotherpsql/mynewdb
51```
52
53### Commands
54
55```
56dbee s3 add <s3Name> <host> Add S3 server
57dbee s3 rm <s3Name> Remove S3 server from config
58dbee s3 ls List S3 servers
59dbee psql add <psqlName> <host> Add Postgres servers
60dbee psql ls List Postgress servers
61dbee psql rm <psqlName> Remove Postgres server from config
62dbee ls [s3Name] List databases available on S3 server
63dbee rm [s3Name/]<fileName> Remove database dump from S3 server
64dbee bckp [psqlName/]<dbName> [s3Name] Backup database to S3
65dbee init [s3Name/]<fileName> [psqlName/]<dbName> Restore database from S3
66```
67
68### Advanced use
69
70#### Options for S3 server
71
72It is possible to provide some additional options for the S3 connection:
73
74- `--port` or `-p`: Specify another port than the default one (443)
75- `--useSSL` or `-s`: Use an SSL connection to the server
76- `--bucket` or `-b`: Specify another bucket name than the default one (dbee)
77
78#### Multiple S3 servers
79
80When only one S3 server is configured, it's not necessary to specify it:
81
82```shell
83dbee ls
84```
85
86But when there is more than one, it is necessary:
87
88```shell
89dbee ls myminio
90```
91
92#### Options for PostgreSQL server
93
94It is possible to provide some additional options for the PostgreSQL connection:
95
96- `--port` or `-p`: Specify another port than the default one (5432)
97- `--useSSL` or `-s`: Use an SSL connection to the server
98- `--timescale` or `-t`: Specify that the server uses TimescaleDB extension (useful for database creation)
99
100#### PostgreSQL server on localhost
101
102When no _psqlName_ is provided, dbee take a default configuration for PostgreSQL server as following:
103
104```json
105{
106 "host": "localhost",
107 "username": "postgres",
108 "password": null,
109 "useSSL": false,
110 "port": 5432
111}
112```
113
114It permits commands like:
115
116```shell
117dbee bckp mydbname
118dbee init mydbname-2021-07-29T15:10:19.748Z.bak mynewdb
119```
120
121## Build
122
123A standalone executable binary can be built with [pkg](https://github.com/vercel/pkg):
124
125```shell
126yarn build
127```
128
129Executable is then available in the `dist/` directory.