github.com/cloudberrydb/gpbackup@v1.0.3-0.20240118031043-5410fd45eed6/README.md (about) 1 # gpbackup for CloudberryDB 2 3 [](https://communityinviter.com/apps/cloudberrydb/welcome) 4 [](https://twitter.com/cloudberrydb) 5 [](https://cloudberrydb.org) 6 [](https://github.com/orgs/cloudberrydb/discussions) 7  8 9 --- 10 11 `gpbackup` and `gprestore` are Go utilities for performing Greenplum database 12 backups, which are originally developed by the Greenplum Database team. This 13 repo is a fork of gpbackup, dedicated to supporting CloduberryDB 1.0+. You 14 will feel no change using gpbackup in CloudberryDB as well as in Greenplum. 15 16 ## Pre-Requisites 17 18 The project requires the Go Programming language version 1.11 or higher. 19 Follow the directions [here](https://golang.org/doc/) for installation, usage 20 and configuration instructions. Make sure to set the [Go PATH environment 21 variable](https://go.dev/doc/install) before starting the following steps. 22 23 ## Download & Build 24 25 1. Downloading the latest version: 26 27 ```bash 28 go install github.com/cloudberrydb/gpbackup@latest 29 ``` 30 31 This will place the code in `$GOPATH/pkg/mod/github.com/cloudberrydb/gpbackup`. 32 33 2. Building and installing binaries 34 35 Make the `gpbackup` directory your current working directory and run: 36 37 ```bash 38 make depend 39 make build 40 ``` 41 42 The `build` target will put the `gpbackup` and `gprestore` binaries in 43 `$HOME/go/bin`. This will also attempt to copy `gpbackup_helper` to the 44 CloudberryDB segments (retrieving hostnames from `gp_segment_configuration`). 45 Pay attention to the output as it will indicate whether this operation was 46 successful. 47 48 `make build_linux` is for cross compiling on macOS, and the target is Linux. 49 50 `make install` will scp the `gpbackup_helper` binary (used with -single-data-file flag) to all hosts 51 52 ## Running the utilities 53 54 The basic command for gpbackup is 55 ```bash 56 gpbackup --dbname <your_db_name> 57 ``` 58 59 The basic command for gprestore is 60 ```bash 61 gprestore --timestamp <YYYYMMDDHHMMSS> 62 ``` 63 64 Run `--help` with either command for a complete list of options. 65 66 ## Validation and code quality 67 68 ### Test setup 69 70 Required for Cloudberry Database 1.0+, several tests require the 71 `dummy_seclabel` Cloudberry Database contrib module. This module exists only 72 to support regression testing of the SECURITY LABEL statement. It is not 73 intended to be used in production. Use the following commands to install the 74 module. 75 76 ```bash 77 pushd $(find ~/workspace/cbdb -name dummy_seclabel) 78 make install 79 gpconfig -c shared_preload_libraries -v dummy_seclabel 80 gpstop -ra 81 gpconfig -s shared_preload_libraries | grep dummy_seclabel 82 popd 83 ``` 84 85 ### Test execution 86 87 **NOTE**: The integration and end_to_end tests require a running Cloudberry 88 Database instance. 89 90 * To run all tests except end-to-end (linters, unit, and integration), use `make test`. 91 * To run only unit tests, use `make unit`. 92 * To run only integration tests (requires a running CloudberryDB instance), use `make integration`. 93 * To run end to end tests (requires a running CloudberryDB instance), use `make end_to_end`. 94 95 We provide the following targets to help developers ensure their code fits 96 Go standard formatting guidelines: 97 98 * To run a linting tool that checks for basic coding errors, use: `make lint`. 99 This target runs [gometalinter](https://github.com/alecthomas/gometalinter). 100 Note: The lint target will fail if code is not formatted properly. 101 102 * To automatically format your code and add/remove imports, use `make format`. 103 This target runs 104 [goimports](https://godoc.org/golang.org/x/tools/cmd/goimports) and 105 [gofmt](https://golang.org/cmd/gofmt/). We will only accept code that has been 106 formatted using this target or an equivalent `gofmt` call. 107 108 ### Cleaning up 109 110 To remove the compiled binaries and other generated files, run `make clean`. 111 112 ## Code Formatting 113 114 We use `goimports` to format go code. See 115 https://godoc.org/golang.org/x/tools/cmd/goimports The following command 116 formats the gpbackup codebase excluding the vendor directory and also lists 117 the files updated. 118 119 ```bash 120 goimports -w -l $(find . -type f -name '*.go' -not -path "./vendor/*") 121 ``` 122 123 ## Troubleshooting 124 125 1. Dummy Security Label module is not installed or configured 126 127 If you see errors in many integration tests (below), review the Validation and 128 code quality [Test setup](##Test setup) section above: 129 130 ``` 131 SECURITY LABEL FOR dummy ON TYPE public.testtype IS 'unclassified'; 132 Expected 133 <pgx.PgError>: { 134 Severity: "ERROR", 135 Code: "22023", 136 Message: "security label provider \"dummy\" is not loaded", 137 ``` 138 139 2. Tablespace already exists 140 141 If you see errors indicating the `test_tablespace` tablespace already exists 142 (below), execute `psql postgres -c 'DROP TABLESPACE test_tablespace'` to 143 cleanup the environment and rerun the tests. 144 145 ``` 146 CREATE TABLESPACE test_tablespace LOCATION '/tmp/test_dir' 147 Expected 148 <pgx.PgError>: { 149 Severity: "ERROR", 150 Code: "42710", 151 Message: "tablespace \"test_tablespace\" already exists", 152 ``` 153 154 ## How to Contribute 155 156 See [CONTRIBUTING.md file](./CONTRIBUTING.md). 157 158 ## License 159 160 Licensed under Apache License Version 2.0. For more details, please refer to 161 the [LICENSE](./LICENSE). 162 163 ## Acknowledgment 164 165 Thanks to all the Greenplum Backup contributors, more details in its [GitHub 166 page](https://github.com/greenplum-db/gpbackup).