Skip to content

Commit

Permalink
Rewrite Readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@asavchkov
asavchkov committed Aug 23, 2023
1 parent 61e5766 commit 4a8cb10
Show file tree
Hide file tree
Showing 2 changed files with 60 additions and 49 deletions.
11 changes: 5 additions & 6 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,8 @@ ifeq ($(MODE), paranoia)
git apply --verbose --3way $(CURDIR)/patches/turn-off-hint-bits.diff
endif

nproc := $(shell nproc)
prefix ?= $(abspath $(top_builddir)/pgsql)
NPROC ?= $(shell nproc)
prefix := $(abspath $(top_builddir)/pgsql)
TEST_MODE ?= normal
# Postgres Makefile skips some targets depending on the MAKELEVEL variable so
# reset it when calling install targets as if they are started directly from the
Expand All @@ -53,8 +53,8 @@ install-postgres:
else \
./configure --prefix=$(prefix) --enable-debug --enable-cassert --enable-depend --enable-tap-tests; \
fi && \
$(MAKE) -sj $(nproc) install MAKELEVEL=0 && \
$(MAKE) -sj $(nproc) -C contrib/ install MAKELEVEL=0
$(MAKE) -sj $(NPROC) install MAKELEVEL=0 && \
$(MAKE) -sj $(NPROC) -C contrib/ install MAKELEVEL=0

# Now when Postgres is built call all remainig targets with USE_PGXS=1

Expand All @@ -71,7 +71,6 @@ pg_probackup_dir ?= $(CURDIR)/../pg_probackup
install-pg-probackup:
$(MAKE) -C $(pg_probackup_dir) install USE_PGXS=$(USE_PGXS) PG_CONFIG=$(PG_CONFIG) top_srcdir=$(top_srcdir)

PYTEST_PROCESSES ?= $(shell nproc)
test-python:
cd $(pg_probackup_dir); \
env="PG_PROBACKUP_PTRACK=ON PG_CONFIG=$(PG_CONFIG)"; \
Expand All @@ -80,7 +79,7 @@ test-python:
elif [ "$(TEST_MODE)" = paranoia ]; then \
env="$$env PG_PROBACKUP_PARANOIA=ON"; \
fi; \
env $$env python3 -m pytest -svv$(if $(shell python3 -m pytest --help | grep '\-n '), -n $(PYTEST_PROCESSES))$(if $(TESTS), -k '$(TESTS)') tests/ptrack_test.py
env $$env python3 -m pytest -svv$(if $(shell python3 -m pytest --help | grep '\-n '), -n $(NPROC))$(if $(TESTS), -k '$(TESTS)') tests/ptrack_test.py

coverage:
gcov *.c *.h
98 changes: 55 additions & 43 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,42 +16,64 @@ This extension is compatible with PostgreSQL [11](patches/REL_11_STABLE-ptrack-c

## Installation

1) Get latest `ptrack` sources:
1) Specify the PostgreSQL branch to work with:

```shell
```Shell
export PG_BRANCH=REL_15_STABLE
```

2) Get the latest PostgreSQL sources:

```Shell
git clone https://github.com/postgres/postgres.git -b $PG_BRANCH
```

3) Get the latest `ptrack` sources:

```Shell
git clone https://github.com/postgrespro/ptrack.git
```

2) Get latest PostgreSQL sources:
4) Change to the `ptrack` directory:

```shell
git clone https://github.com/postgres/postgres.git -b REL_14_STABLE && cd postgres
```Shell
cd ptrack
```

3) Apply PostgreSQL core patch:
5) Apply the PostgreSQL core patch:

```shell
git apply -3 ../ptrack/patches/REL_14_STABLE-ptrack-core.diff
```Shell
make patch top_builddir=../postgres
```

4) Compile and install PostgreSQL
6) Compile and install PostgreSQL:

```Shell
make install-postgres top_builddir=$PWD/../postgres prefix=$HOME/pgsql # or any prefix of your choice
```

5) Set `ptrack.map_size` (in MB)
7) Add the newly created binaries to the PATH:

```shell
echo "shared_preload_libraries = 'ptrack'" >> postgres_data/postgresql.conf
echo "ptrack.map_size = 64" >> postgres_data/postgresql.conf
```Shell
export PATH=$HOME/pgsql/bin:$PATH
```

6) Compile and install `ptrack` extension
8) Compile and install `ptrack`:

```shell
USE_PGXS=1 make -C /path/to/ptrack/ install
```Shell
make install USE_PGXS=1
```

7) Run PostgreSQL and create `ptrack` extension
9) Set `ptrack.map_size` (in MB):

```sql
```Shell
echo "shared_preload_libraries = 'ptrack'" >> <DATA_DIR>/postgresql.conf
echo "ptrack.map_size = 64" >> <DATA_DIR>/postgresql.conf
```

10) Run PostgreSQL and create the `ptrack` extension:

```SQL
postgres=# CREATE EXTENSION ptrack;
```

Expand All @@ -70,7 +92,7 @@ To disable `ptrack` and clean up all remaining service files set `ptrack.map_siz

Usage example:

```sql
```SQL
postgres=# SELECT ptrack_version();
ptrack_version
----------------
Expand Down Expand Up @@ -160,11 +182,11 @@ To gather the whole changeset of modified blocks in `ptrack_get_pagemapset()` we

Feel free to [send pull requests](https://github.com/postgrespro/ptrack/compare), [fill up issues](https://github.com/postgrespro/ptrack/issues/new), or just reach one of us directly (e.g. <[Alexey Kondratov](mailto:[email protected]?subject=[GitHub]%20Ptrack), [@ololobus](https://github.com/ololobus)>) if you are interested in `ptrack`.

### Tests
## Tests

All changes of the source code in this repository are checked by CI - see commit statuses and the project status badge. You can also run tests locally by executing a few Makefile targets.

#### Prerequisites
### Prerequisites

To run Python tests inbstall the following packages:

Expand All @@ -179,50 +201,40 @@ PIP packages:

For example, for Ubuntu:

```sh
```Shell
apt update
apt install python3-pip python3-six python3-pytest python3-pytest-xdist
pip3 install testgres
```

#### Testing

```sh
export PG_BRANCH=REL_15_STABLE
export PREFIX=/path/to/pgsql
export PATH=$PREFIX/bin:$PATH

cd /path/to/ptrack
make patch top_builddir=/path/to/postgres

cd /path/to/postgres
./configure --prefix=$PREFIX --enable-debug --enable-cassert --enable-depend --enable-tap-tests
make -sj `nproc` install
make -C contrib -sj `nproc` install
### Testing

Install PostgreSQL and ptrack as described in [Installation](#installation), then do:
```Shell
export PATH=/path/to/pgsql/bin:$PATH
export USE_PGXS=1

cd /path/to/ptrack
make install
make install-pg-probackup top_srcdir=/path/to/postgres
make install-pg-probackup top_srcdir=/path/to/postgres [pg_probackup_dir=/path/tp/pg_probackup]
make test-tap
make test-python
```

You can use a public Docker image which already has the necessary build environment (but not the testing prerequisites):

```sh
```Shell
docker run -e USER_ID=`id -u` -it -v $PWD:/work --name=ptrack ghcr.io/postgres-dev/ubuntu-22.04:1.0
dev@a033797d2f73:~$
```

You can control how tests are executed by using the following environment (or `make`) variables:
## Environment variables

| Variable | Possible values | Required | Default value | Description |
| - | - | - | - | - |
| Variable | Possible values | Required | Default value | Description |
| - | - | - | - | - |
| NPROC | An integer greater than 0 | No | Output of `nproc` | The number of threads used for building and running tests |
| PG_CONFIG | File path | No | pg_config | The path to the `pg_config` binary. Can be set to specify a custom location of `pg_config`. |
| TESTS | A Pytest filter expression | No | Not set (run all Python tests) | A filter to include only selected tests into the run. See the Pytest `-k` option for more information. This variable is only applicable to `test-python` for the tests located in [tests](https://github.com/postgrespro/pg_probackup/tree/master/tests). |
| TEST_MODE | normal, legacy, paranoia | No | normal | The "legacy" mode runs tests in an environment similar to a 32-bit Windows system. This mode is only applicable to `test-tap`. The "paranoia" mode compares the checksums of each block of the database catalog (PGDATA) contents before making a backup and after the restoration. This mode is only applicable to `test-python`.|
| TEST_MODE | normal, legacy, paranoia | No | normal | The "legacy" mode runs tests in an environment similar to a 32-bit Windows system. This mode is only applicable to `test-tap`. The "paranoia" mode compares the checksums of each block of the database catalog (PGDATA) contents before making a backup and after the restoration. This mode is only applicable to `test-python`.|

### TODO

Expand Down

0 comments on commit 4a8cb10

Please sign in to comment.