diff --git a/.github/asan.supp b/.github/asan.supp deleted file mode 100644 index 86447896..00000000 --- a/.github/asan.supp +++ /dev/null @@ -1,6 +0,0 @@ -# Suppress all leaks from PostgreSQL source code (not our responsibility) -# This matches any frame containing "postgres/src" in the path -leak:postgres/src - -# Suppress leaks from PostgreSQL libraries -leak:libpq diff --git a/.github/tsan.supp b/.github/tsan.supp deleted file mode 100644 index f05f396d..00000000 --- a/.github/tsan.supp +++ /dev/null @@ -1,19 +0,0 @@ -# ThreadSanitizer suppression file for pg_probackup -# These are known data races that are benign on x86/x64 but should be -# fixed properly using atomic operations in a separate PR. - -# Race on thread_interrupted flag (bool) used to signal streaming thread to stop. -# Main thread writes false, worker thread reads to check if should stop. -# Benign: worst case is one extra loop iteration before stopping. -race:thread_interrupted - -# Race on stop_backup_lsn (uint64) used to signal WAL streaming stop point. -# Main thread sets LSN, worker thread reads to check if reached. -# Benign on x86/x64 where aligned 8-byte operations are atomic. -race:stop_backup_lsn - -# Race on prev_time (time_t) static variable in backup_files function. -# All threads write the same value (current.start_time) at initialization. -# Only thread 1 uses it afterward for periodic control file updates. -# Benign: all writes are identical value. -race:prev_time diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..a9c7866c --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,59 @@ +name: Deploy Documentation + +on: + push: + branches: + - master + paths: + - 'doc/**' + - '.github/workflows/docs.yml' + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Install dependencies + run: | + sudo apt-get update + sudo apt-get install -y xsltproc docbook-xsl + + - name: Generate HTML documentation + run: | + cd doc + xsltproc stylesheet.xsl probackup.xml > index.html + + - name: Prepare pages directory + run: | + mkdir -p _site + cp doc/index.html _site/ + cp doc/stylesheet.css _site/ + cp doc/404.html _site/ 2>/dev/null || true + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/README.md b/README.md index da62364f..b0144053 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ -[![GitHub release](https://img.shields.io/github/v/release/postgrespro/pg_probackup?include_prereleases)](https://github.com/postgrespro/pg_probackup/releases/latest) -[![Build Status](https://travis-ci.com/postgrespro/pg_probackup.svg?branch=master)](https://travis-ci.com/postgrespro/pg_probackup) +[![GitHub release](https://img.shields.io/github/v/release/vbp1/pg_probackup?include_prereleases)](https://github.com/vbp1/pg_probackup/releases/latest) +[![Build Status](https://github.com/vbp1/pg_probackup/actions/workflows/build-and-test.yml/badge.svg?branch=master)](https://github.com/vbp1/pg_probackup/actions/workflows/build-and-test.yml) # pg_probackup @@ -25,48 +25,36 @@ As compared to other backup solutions, `pg_probackup` offers the following benef * Archive catalog: getting the list of all WAL timelines and the corresponding meta information in plain text or JSON formats * Partial Restore: restore only the specified databases or exclude the specified databases from restore. -To manage backup data, `pg_probackup` creates a backup catalog. This directory stores all backup files with additional meta information, as well as WAL archives required for [point-in-time recovery](https://postgrespro.com/docs/postgresql/current/continuous-archiving.html). You can store backups for different instances in separate subdirectories of a single backup catalog. +To manage backup data, `pg_probackup` creates a backup catalog. This directory stores all backup files with additional meta information, as well as WAL archives required for [point-in-time recovery](https://www.postgresql.org/docs/current/continuous-archiving.html). You can store backups for different instances in separate subdirectories of a single backup catalog. Using `pg_probackup`, you can take full or incremental backups: * `Full` backups contain all the data files required to restore the database cluster from scratch. * `Incremental` backups only store the data that has changed since the previous backup. It allows to decrease the backup size and speed up backup operations. `pg_probackup` supports the following modes of incremental backups: * `PAGE` backup. In this mode, `pg_probackup` scans all WAL files in the archive from the moment the previous full or incremental backup was taken. Newly created backups contain only the pages that were mentioned in WAL records. This requires all the WAL files since the previous backup to be present in the WAL archive. If the size of these files is comparable to the total size of the database cluster files, speedup is smaller, but the backup still takes less space. * `DELTA` backup. In this mode, `pg_probackup` read all data files in PGDATA directory and only those pages, that where changed since previous backup, are copied. Continuous archiving is not necessary for it to operate. Also this mode could impose read-only I/O pressure equal to `Full` backup. - * `PTRACK` backup. In this mode, PostgreSQL tracks page changes on the fly. Continuous archiving is not necessary for it to operate. Each time a relation page is updated, this page is marked in a special `PTRACK` bitmap for this relation. As one page requires just one bit in the `PTRACK` fork, such bitmaps are quite small. Tracking implies some minor overhead on the database server operation, but speeds up incremental backups significantly. + * `PTRACK` backup with [ptrack extension](https://github.com/postgrespro/ptrack). In this mode, PostgreSQL tracks page changes on the fly. Continuous archiving is not necessary for it to operate. Each time a relation page is updated, this page is marked in a special `PTRACK` bitmap for this relation. As one page requires just one bit in the `PTRACK` fork, such bitmaps are quite small. Tracking implies some minor overhead on the database server operation, but speeds up incremental backups significantly. Regardless of the chosen backup type, all backups taken with `pg_probackup` support the following strategies of WAL delivery: * `Autonomous backups` streams via replication protocol all the WAL files required to restore the cluster to a consistent state at the time the backup was taken. Even if continuous archiving is not set up, the required WAL segments are included into the backup. * `Archive backups` rely on continuous archiving. -## ptrack support - -`PTRACK` backup support provided via following options: -* vanilla PostgreSQL 13, 14, 15, 16, 17 with [ptrack extension](https://github.com/postgrespro/ptrack) -* Postgres Pro Standard 13, 14, 15, 16, 17 -* Postgres Pro Enterprise 13, 14, 15, 16, 17 - ## Limitations `pg_probackup` currently has the following limitations: -* The server from which the backup was taken and the restored server must be compatible by the [block_size](https://postgrespro.com/docs/postgresql/current/runtime-config-preset#GUC-BLOCK-SIZE) and [wal_block_size](https://postgrespro.com/docs/postgresql/current/runtime-config-preset#GUC-WAL-BLOCK-SIZE) parameters and have the same major release number. +* The server from which the backup was taken and the restored server must be compatible by the [block_size](https://www.postgresql.org/docs/current/runtime-config-preset.html#GUC-BLOCK-SIZE) and [wal_block_size](https://www.postgresql.org/docs/current/runtime-config-preset.html#GUC-WAL-BLOCK-SIZE) parameters and have the same major release number. * Remote backup via ssh on Windows currently is not supported. * When running remote operations via ssh, remote and local pg_probackup versions must be the same. ## Documentation -Documentation can be found at [github](https://postgrespro.github.io/pg_probackup) and [Postgres Professional documentation](https://postgrespro.com/docs/postgrespro/current/app-pgprobackup) +Documentation can be found at [github](https://postgrespro.github.io/pg_probackup) ## Development * Stable version state can be found under the respective [release tag](https://github.com/postgrespro/pg_probackup/releases). * `master` branch contains minor fixes that are planned to the nearest minor release. -* Upcoming major release is developed in a release branch i.e. `release_2_6`. - -For detailed release plans check [Milestones](https://github.com/postgrespro/pg_probackup/milestones) ## Installation and Setup -### Windows Installation -Installers are available in release **assets**. [Latests](https://github.com/postgrespro/pg_probackup/releases/latest). ### Linux Installation @@ -74,7 +62,6 @@ See the [Installation](https://postgrespro.github.io/pg_probackup/#pbk-install) Once you have `pg_probackup` installed, complete [the setup](https://postgrespro.github.io/pg_probackup/#pbk-setup). -For users of Postgres Pro products, commercial editions of pg_probackup are available for installation from the corresponding Postgres Pro product repository. ## Building from source ### Linux @@ -93,26 +80,13 @@ cd && git clone https://github.com/postgrespro/ For version 18 you have to apply PostgreSQL core patch (patches/REL_18_STABLE_pg_probackup.patch) first and recompile and reinstall PostgreSQL -### Windows - -Currently pg_probackup can be build using only MSVC 2013. -Build PostgreSQL using [pgwininstall](https://github.com/postgrespro/pgwininstall) or [PostgreSQL instruction](https://www.postgresql.org/docs/current/install-windows-full.html) with MSVC 2013. -If zlib support is needed, src/tools/msvc/config.pl must contain path to directory with compiled zlib. [Example](https://gist.githubusercontent.com/gsmol/80989f976ce9584824ae3b1bfb00bd87/raw/240032950d4ac4801a79625dd00c8f5d4ed1180c/gistfile1.txt) - -```shell -CALL "C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall" amd64 -SET PATH=%PATH%;C:\Perl64\bin -SET PATH=%PATH%;C:\msys64\usr\bin -gen_probackup_project.pl C:\path_to_postgresql_source_tree -``` - ## License This module available under the [license](LICENSE) similar to [PostgreSQL](https://www.postgresql.org/about/license/). ## Feedback -Do not hesitate to post your issues, questions and new ideas at the [issues](https://github.com/postgrespro/pg_probackup/issues) page. +Do not hesitate to post your issues, questions and new ideas at the [issues](https://github.com/vbp1/pg_probackup/issues) page. ## Authors @@ -134,4 +108,4 @@ Description of how to add new translation languages. 6. Adding to nls.mk in folder pg_probackup required language in AVAIL_LANGUAGES. For more information, follow the link below: -https://postgrespro.ru/docs/postgresql/12/nls-translator +https://www.postgresql.org/docs/current/nls-translator.html diff --git a/doc/404.html b/doc/404.html new file mode 100644 index 00000000..d5f136ea --- /dev/null +++ b/doc/404.html @@ -0,0 +1,72 @@ + + + + + + Page Not Found - pg_probackup Documentation + + + + +
+

404

+

Page Not Found

+

+ The page you are looking for might have been removed, + had its name changed, or is temporarily unavailable. +

+ Go to Documentation +
+ + diff --git a/doc/Readme.md b/doc/Readme.md index 0e1d6459..495f37df 100644 --- a/doc/Readme.md +++ b/doc/Readme.md @@ -1,8 +1,43 @@ -# Generating documentation -``` +# pg_probackup Documentation + +This directory contains the source files for pg_probackup documentation in DocBook XML format. + +## Online Documentation + +The documentation is automatically published to GitHub Pages: +https://vbp1.github.io/pg_probackup + +## Generating Documentation Locally + +```bash +# Validate XML (optional) xmllint --noout --valid probackup.xml -xsltproc stylesheet.xsl probackup.xml >pg-probackup.html + +# Generate HTML +xsltproc stylesheet.xsl probackup.xml > index.html ``` + > [!NOTE] ->Install ```docbook-xsl``` if you got ->``` "xsl:import : unable to load http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"``` \ No newline at end of file +> Install `docbook-xsl` if you get: +> ``` +> "xsl:import : unable to load http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" +> ``` +> +> On Debian/Ubuntu: `sudo apt-get install docbook-xsl` +> On RHEL/CentOS: `sudo yum install docbook-style-xsl` + +## Files + +- `probackup.xml` - Main DocBook document +- `pgprobackup.xml` - Detailed documentation content +- `stylesheet.xsl` - XSLT stylesheet for HTML generation +- `stylesheet.css` - CSS styles for HTML output +- `404.html` - Custom 404 error page for GitHub Pages + +## Automatic Deployment + +Documentation is automatically deployed to GitHub Pages when changes are pushed to the `master` branch. The deployment is handled by the `.github/workflows/docs.yml` workflow. + +The workflow: +1. Generates HTML from DocBook XML using `xsltproc` +2. Deploys to GitHub Pages using the modern `actions/deploy-pages` action diff --git a/doc/stylesheet.css b/doc/stylesheet.css index 31464154..8e24fc00 100644 --- a/doc/stylesheet.css +++ b/doc/stylesheet.css @@ -221,7 +221,8 @@ body { border-color: #DBDBCC; background-color: #EEEEDD; padding: 14px; - width: 572px; + max-width: 572px; + width: auto; /* font-size: 12px; */ } @@ -419,3 +420,128 @@ table.CAUTION, border: 1px solid #ccc; border-radius: 4px; } + +/* Responsive styles */ +html { + box-sizing: border-box; +} + +*, *:before, *:after { + box-sizing: inherit; +} + +.book { + max-width: 960px; + margin: 0 auto; + padding: 0 20px; +} + +.book pre, +.book .SCREEN, +.book .SYNOPSIS, +.book .PROGRAMLISTING { + overflow-x: auto; + word-wrap: normal; + white-space: pre; +} + +.book table { + max-width: 100%; + overflow-x: auto; + display: block; +} + +.book .cmdsynopsis { + overflow-x: auto; +} + +/* Mobile styles */ +@media screen and (max-width: 768px) { + body { + font-size: 16px; + } + + .book { + font-size: 14px; + padding: 0 15px; + } + + .book h1 { + font-size: 1.3em; + } + + .book h2 { + font-size: 1.15em; + } + + .book h3 { + font-size: 1.1em; + } + + .book pre, + .book .SCREEN, + .book .SYNOPSIS, + .book .PROGRAMLISTING, + .book .REFSYNOPSISDIV p { + padding: 1.5ex; + margin: 1.5ex 0; + font-size: 12px; + } + + .book blockquote.NOTE, + .book blockquote.TIP, + .book div.note, + .book div.tip { + max-width: 100%; + padding: 10px; + margin: 2ex 0; + } + + table.CAUTION, + .book table.WARNING { + max-width: 100%; + } + + .book div.SECT3 { + margin-left: 1.5ex; + } + + .book table { + margin-left: 0; + } + + .book dd { + margin-left: 20px; + } + + .book .toc { + padding-left: 0; + } + + .book .toc dl { + margin-left: 0; + } + + .book .toc dd { + margin-left: 15px; + } +} + +/* Small mobile styles */ +@media screen and (max-width: 480px) { + body { + font-size: 15px; + } + + .book { + font-size: 13px; + padding: 0 10px; + } + + .book pre, + .book .SCREEN, + .book .SYNOPSIS, + .book .PROGRAMLISTING { + font-size: 11px; + } +} diff --git a/tests/Readme.md b/tests/Readme.md index 80db6b7b..f13e0d05 100644 --- a/tests/Readme.md +++ b/tests/Readme.md @@ -1,7 +1,5 @@ # pg_probackup Tests -[See wiki](https://confluence.postgrespro.ru/display/DEV/pg_probackup) - ## Requirements - Python 3.8+