c30d3e439b
Bug Fixes: * Remove the distinction between maps where super block size is equal to block size and maps where they are not. In practice, maps with equal blocks are now rare and most of the optimizations can be applied directly to super blocks where the blocks are equal. This fixes a bug where a map that was created with equal size blocks and then converted to differing block sizes would generate an invalid map. * Free reads during restore to avoid running out of file handles. Improvements: * Store super block sizes in the block map. This allows the final block size to be removed from the block list and provides a more optimal restore and better potential for analysis. * Always round the super block size up to the next block size. This makes the number of blocks per super block more predictable. * Allow super block sizes to be changed at will in the map. The first case for this is to store the reduced super block size required when the last super block is short but it could be used to dynamically change the super block size to optimize compression. * Store a block count rather than a list of blocks in a super block. Blocks must always be sequential, though there may be an offset to the first block in a super block. This saves 11-14% on space for checksum sizes 6-7. * In the case that all the blocks for a super block are present, and there is no offset, the block size is omitted.
pgBackRest
Building Documentation
General Builds
The pgBackRest documentation can output a variety of formats and target several platforms and PostgreSQL versions.
This will build all documentation with defaults:
./doc.pl
The user guide can be built for rhel and debian. This will build the HTML user guide for RHEL:
./doc.pl --out=html --include=user-guide --var=os-type=rhel
Documentation generation will build a cache of all executed statements and use the cache to build the documentation quickly if no executed statements have changed. This makes proofing text-only edits very fast, but sometimes it is useful to do a full build without using the cache:
./doc.pl --out=html --include=user-guide --var=os-type=rhel --no-cache
Each os-type has a default container image that will be used as a base for creating hosts but it may be useful to change the image.
./doc.pl --out=html --include=user-guide --var=os-type=debian --var=os-image=debian:9
./doc.pl --out=html --include=user-guide --var=os-type=rhel --var=os-image=centos:7
The following is a sample RHEL 7 configuration that can be used for building the documentation.
# Install docker
sudo yum install -y yum-utils device-mapper-persistent-data lvm2
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y docker-ce
sudo systemctl start docker
# Install tools
sudo yum install -y git wget
# Install latex (for building PDF)
sudo yum install -y texlive texlive-titlesec texlive-sectsty texlive-framed texlive-epstopdf ghostscript
# Install Perl modules via CPAN that do not have packages
sudo yum install -y yum cpanminus
sudo yum groupinstall -y "Development Tools" "Development Libraries"
sudo cpanm install --force XML::Checker::Parser
# Add documentation test user
sudo groupadd test
sudo adduser -gtest -n testdoc
sudo usermod -aG docker testdoc
Building with Packages
A user-specified package can be used when building the documentation. Since the documentation exercises most pgBackRest functionality this is a great way to smoke-test packages.
The package must be located within the pgBackRest repo and the specified path should be relative to the repository base. test/package is a good default path to use.
Ubuntu 16.04:
./doc.pl --out=html --include=user-guide --no-cache --var=os-type=debian --var=os-image=ubuntu:16.04 --var=package=test/package/pgbackrest_2.08-0_amd64.deb
RHEL 7:
./doc.pl --out=html --include=user-guide --no-cache --var=os-type=rhel --var=os-image=centos:7 --var=package=test/package/pgbackrest-2.08-1.el7.x86_64.rpm
RHEL 8:
./doc.pl --out=html --include=user-guide --no-cache --var=os-type=rhel --var=os-image=centos:8 --var=package=test/package/pgbackrest-2.08-1.el8.x86_64.rpm
Packages can be built with test.pl using the following configuration on top of the configuration given for building the documentation.
# Install recent git
sudo yum remove -y git
sudo yum install -y https://centos7.iuscommunity.org/ius-release.rpm
sudo yum install -y git2u-all
# Install Perl modules
sudo yum install -y perl-ExtUtils-ParseXS perl-ExtUtils-Embed perl-ExtUtils-MakeMaker perl-YAML-LibYAML
# Install dev libraries
sudo yum install -y libxml2-devel openssl-devel
# Add test user with sudo privileges
sudo adduser -gtest -n test
sudo usermod -aG docker test
sudo chmod 750 /home/test
sudo echo 'test ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/pgbackrest
# Add pgbackrest user required by tests
sudo adduser -gtest -n pgbackrest