README

pg_backup_ctl-plus is a rewrite of the old sophisticated pg_backup_ctl script.

THIS SOFTWARE IS UNDER HEAVY DEVELOPMENT AND NOT PRODUCTION READY. USE WITH CARE!

Compiling:
==========

Checkout the repository:

github:

$ git@github.com:psoo/pg_backup_ctl-plus.git

$ cd pg_backup_ctl-plus
$ mkdir build

pg_backup_ctl++ currently depends on the following packages:

- boost-system
- boost-filesystem
- boost-regex
- boost-date_time
- boost-iostreams

(yes, you don't have a nightmare, its true, we rely on boost). The
easiest way is to install the boost-devel package (at least on Fedora).

- libpopt
- libreadline
- zlib
- postgresql-devel

pg_backup_ctl++ links against PostgreSQL 9.6, though
the newest upstream version 12 is recommended. Version below
9.6 might work, but aren't officially supported.

If everything is present, type

    $ cd build
    $ cmake ..
    $ make

Preparation steps:
==================

You need a sqlite3 database for the pg_backup_ctl++ catalog. If you don't
want to use --catalog everytime, you can rely on a compiled-in default.
Currently this is hardwired to ~/.pg_backup_ctl.sqlite. To override this default,
just pass your favorite path to cmake like this:

    $ cmake -DPG_BACKUP_CTL_SQLITE:FILEPATH=/Users/bernd/.pg_backup_ctl.sqlite ..
    $ make

Then prepare the database files:

    $ sqlite3 /your/sqlite/database < src/sql/catalog.sql

Theres a command reference available, though building requires
python-sphinx. On Fedora 27, where python3-sphinx is available, you
can build the command reference as shown below:

    $ cd <pg_backup_ctl++ source dir>/resources/reference
    $ make SPHINXBUILD=sphinx-build-3 html

The documentation can then be found in the build/ subdirectory.

Source Code Documentation
-------------------------

There's code and API documentation available via doxygen. The documentation
can be build with

    $ make doc

After successful execution the documentation should be available in
doc/html/index.html in the project directory.

CentOS/RHEL 7
-------------

CentOS/RHEL 7 requires a relatively new boost version to build. The shipped
boost library version 1.53 is too old to support the whole functionality (especially
the boost-log infrastructure), so building this on this platform requires inclusions of
EPEL. EPEL provides boost version 1.69, which fits our requirements.
Another requirement is cmake version >= 3.

      $ cd build
      $ BOOST_LIBRARYDIR=/usr/lib64/boost169 BOOST_INCLUDEDIR=/usr/include/boost169 CXX="ccache g++" CXXFLAGS="-D__DEBUG__ -D__DEBUG_XLOG__" cmake3 ..

      or without DEBUG output

      $ CXX="ccache g++" CXXFLAGS="-D__DEBUG__ -D__DEBUG_XLOG__" cmake3 ..
      $ BOOST_LIBRARYDIR=/usr/lib64/boost169 BOOST_INCLUDEDIR=/usr/include/boost169 CXX="ccache g++" cmake3 ..

Unit Tests
----------

The unit test framework has just started its implementation, currently
some tests in the backup catalog API and parser are present.
To enable unit tests, you have to build pg_backup_ctl++ with the
BUILD_UNIT_TEST macro, e.g.

      $ CXX="ccache g++" CXXFLAGS="-D__DEBUG__ -D__DEBUG_XLOG__" cmake3 -DBUILD_UNIT_TESTS ..

This will build test test_* binaries and can be executed with

      $ make test

Special compile macros
----------------------

Some macros can be used to enable some additional binary features:

__DEBUG__ : Enables debug output at compile time
            These are additional log message usually only
            necessary for development builds.

__DEBUG_XLOG__ : Enables debug additional log messages
                 in WAL related code (e.g. walstreamer)

PG_BACKUP_CTL_SQLITE: Path to sqlite backup catalog database.  Default
                      is ~/.pg_backup_ctl.sqlite

SYSTEMD_SERVICE_FILE: Installs systemd service files if requested.

BUILD_UNIT_TESTS: Build with unit tests.