From 8841c0b9bbef7dbbcb49bac63360a6723d92ad5e Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Mon, 4 May 2026 17:45:22 +0300 Subject: [PATCH 1/3] Backport for Update Quick Start Guide Percona Postgresql (15) This PR is a backport for #925. --- docs/index.md | 11 ++-- docs/installing.md | 27 +++++----- docs/quick-start.md | 119 ++++++++++++++++++++++++++++++++++++++++++++ mkdocs-base.yml | 3 +- 4 files changed, 139 insertions(+), 21 deletions(-) create mode 100644 docs/quick-start.md diff --git a/docs/index.md b/docs/index.md index fee434034..fa961c1cc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,9 @@ # Percona Distribution for PostgreSQL 15 Documentation - Percona Distribution for PostgreSQL is a suite of open source software, tools and services required to deploy and maintain a reliable production cluster for PostgreSQL. It includes native PostgreSQL server, enhanced with extensions from open source community that are certified and tested to work together for high availability, backups, security, and monitoring that help ensure the cluster's peak performance. + Percona Distribution for PostgreSQL is a suite of open source software, tools and services required to deploy and maintain a reliable production cluster for PostgreSQL. + Percona Distribution for PostgreSQL includes [PostgreSQL server :octicons-link-external-16:](https://www.postgresql.org/docs/15/index.html), packaged with extensions from open source community that are certified and tested to work together for high availability, backups, security, and monitoring that help ensure the cluster's peak performance. + Part of the solution, Percona Operator for PostgreSQL, makes it easy to orchestrate the cluster reliably and repeatably in Kubernetes. [What's included in Percona Distribution for PostgreSQL? :material-arrow-right:](extensions.md){.md-button} @@ -17,11 +19,11 @@
-## :material-progress-download: Installation guides { .title } +## :material-progress-download: Quickstart guide { .title } Get started quickly with the step-by-step installation instructions. -[Quickstart guides :material-arrow-right:](installing.md){ .md-button } +[Quickstart guide :material-arrow-right:](quick-start.md){ .md-button }
@@ -48,6 +50,3 @@ Learn about the releases and changes in the Distribution. [Release notes :material-arrow-right:]({{release}}.md){.md-button}
- - - diff --git a/docs/installing.md b/docs/installing.md index 25340bd2b..c1e0060df 100644 --- a/docs/installing.md +++ b/docs/installing.md @@ -1,21 +1,19 @@ -# Quickstart guide +# Installation overview -Percona Distribution for PostgreSQL is the solution with the collection of tools from PostgreSQL community that are tested to work together and serve to assist you in deploying and managing PostgreSQL. [Read more](index.md). +Percona Distribution for PostgreSQL packages PostgreSQL together with a curated set of open source extensions and tools that are tested to work together reliably. -This document aims to guide database application developers and DevOps engineer in getting started with Percona Distribution for PostgreSQL. Upon completion of this guide, you’ll have Percona Distribution for PostgreSQL installed and operational, and you’ll be able to: +This section explains how to install Percona Distribution for PostgreSQL on supported platforms. -* Connect to PostgreSQL using the `psql` interactive terminal -* Interact with PostgreSQL with basic psql commands -* Manipulate data in PostgreSQL -* Understand the next steps you can take as a database application developer or administrator to expand your knowledge of Percona Distribution for PostgreSQL +Choose the installation method that best fits your environment: -## Install Percona Distribution for PostgreSQL - -You can select from multiple easy-to-follow installation options, however **we strongly recommend using a Package Manager** for a convenient and quick way to try the software first. +- Package manager, **recommended** for most Linux systems +- Docker, for quick evaluations or development +- Kubernetes, for production Kubernetes environments +- Tarballs, manual installation for custom environments (**not recommended** for mission-critical environments) === ":octicons-terminal-16: Package manager" - Percona provides installation packages in `DEB` and `RPM` format for 64-bit Linux distributions. Find the full list of supported platforms and versions on the [Percona Software and Platform Lifecycle page :octicons-link-external-16:](https://www.percona.com/services/policies/percona-software-support-lifecycle#pgsql). + Percona provides installation packages in `DEB` and `RPM` format for 64-bit Linux distributions. See the [Percona Software and Platform Lifecycle page :octicons-link-external-16:](https://www.percona.com/services/policies/percona-software-support-lifecycle#pgsql) for the full list of supported platforms and versions. If you are on Debian or Ubuntu, use `apt` for installation. @@ -26,7 +24,7 @@ You can select from multiple easy-to-follow installation options, however **we s === ":simple-docker: Docker" - Get our image from Docker Hub and spin up a cluster on a Docker container for quick evaluation. + Run Percona Distribution for PostgreSQL in a Docker container for quick evaluation or development. Check below to get access to a detailed step-by-step guide. @@ -34,7 +32,7 @@ You can select from multiple easy-to-follow installation options, however **we s === ":simple-kubernetes: Kubernetes" - **Percona Operator for Kubernetes** is a controller introduced to simplify complex deployments that require meticulous and secure database expertise. + Use the Percona Operator for Kubernetes to deploy and manage PostgreSQL clusters on Kubernetes. Check below to get access to a detailed step-by-step guide. @@ -49,4 +47,5 @@ You can select from multiple easy-to-follow installation options, however **we s !!! note This method is **not recommended** for mission-critical environments. - [Install from tarballs :material-arrow-right:](tarball.md){.md-button} + + [Install from tarballs :material-arrow-right:](tarball.md){.md-button} diff --git a/docs/quick-start.md b/docs/quick-start.md new file mode 100644 index 000000000..e787fbb47 --- /dev/null +++ b/docs/quick-start.md @@ -0,0 +1,119 @@ +# Quickstart guide + +This guide shows how to install and start Percona Distribution for PostgreSQL on Debian- and RHEL-based Linux systems. After completing this guide, you will have: + +- PostgreSQL running locally +- A database named `test` +- A table named `customers` +- One inserted row you can query + +## Fast path (2-minute install) + +```{.bash data-prompt="$"} +wget https://repo.percona.com/apt/percona-release_latest.$(lsb_release -sc)_all.deb +sudo dpkg -i percona-release_latest.$(lsb_release -sc)_all.deb +sudo percona-release setup ppg-{{pgversion}} +sudo apt install percona-postgresql-{{pgversion}} +sudo -i -u postgres psql +``` + +After psql starts, run the following SQL commands: + +```sql +CREATE DATABASE test; +\c test +CREATE TABLE customers (first_name VARCHAR(50), last_name VARCHAR(50), email VARCHAR(100)); +INSERT INTO customers VALUES ('John','Doe','john.doe@example.com'); +SELECT * FROM customers; +\q +``` + +For a step-by-step explanation, continue below. + +## Install on Debian / Ubuntu (APT) {.power-number} + +1. Fetch the `percona-release` package: + + ```{.bash data-prompt="$"} + wget https://repo.percona.com/apt/percona-release_latest.$(lsb_release -sc)_all.deb + sudo dpkg -i percona-release_latest.$(lsb_release -sc)_all.deb + ``` + +2. Enable the repository and install the package: + + ```{.bash data-prompt="$"} + sudo percona-release setup ppg-{{pgversion}} + sudo apt install percona-postgresql-{{pgversion}} + ``` + + The installation process automatically initializes and starts the default database. + + !!! note + On Debian and Ubuntu systems, the `postgresql` service may show as `active (exited)`. This is expected. + +3. Switch to the `postgres` user and open the psql interactive terminal: + + ```{.bash data-prompt="$"} + sudo -i -u postgres + psql + ``` + +4. Create a database and make a table in the database: + + ```sql + CREATE DATABASE test; + \c test + CREATE TABLE customers (first_name VARCHAR(50), last_name VARCHAR(50), email VARCHAR(100)); + ``` + +5. Insert data in the customers table and query the data insertion: + + ```sql + INSERT INTO customers (first_name, last_name, email) VALUES ('John', 'Doe', 'john.doe@example.com'); + SELECT * FROM customers; + \q + ``` + +Congratulations! Percona Distribution for PostgreSQL is now running and you have created your first database. + +For detailed installation steps and further instructions on Debian and Ubuntu, see the [Install Percona Distribution for PostgreSQL on Debian and Ubuntu](apt.md). + +For detailed installation steps and further instructions on Red Hat Enterprise Linux and derivatives, see the [Install Percona Distribution for PostgreSQL on Red Hat Enterprise Linux and derivatives](yum.md). + +## What's next + +Now that your PostgreSQL server is running, you can explore additional capabilities of Percona Distribution for PostgreSQL. + +
+ +### Learn PostgreSQL basics { .title } + +Connect with `psql` and run SQL commands, manage users, roles, and configure authentication. + +[Manipulate data in PostgreSQL :material-arrow-right:](crud.md){ .md-button } + +
+ +### Enable extensions { .title } + +Percona Distribution for PostgreSQL includes tested open source extensions, such as `pg_stat_monitor` for query performance monitoring, `pg_tde` for protecting data at rest and more. + +[See Extensions :material-arrow-right:](extensions.md){ .md-button } + +
+ +### Configure backups { .title } + +For production deployments we recommend configuring backups. + +[See Backup and disaster recovery in Percona :material-arrow-right:](solutions/backup-recovery.md){.md-button} +
+ +### Configure high availability with Patroni { .title } + +Deploy a highly available PostgreSQL cluster using Patroni to prevent service interruptions. + +[See High Availability in PostgreSQL :material-arrow-right:](solutions/high-availability.md){.md-button} + +
+
diff --git a/mkdocs-base.yml b/mkdocs-base.yml index e2e52198f..4b6870a11 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -167,9 +167,10 @@ extra: nav: - 'Home': 'index.md' - get-help.md + - Quickstart guide: quick-start.md - Get started: - - Quickstart guide: installing.md - 1. Install: + - Overview: installing.md - Via apt: apt.md - Via yum: yum.md - From tarballs: tarball.md From 0c3d6669a777cab941a50a06d5c9c3e6daeab53a Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Mon, 4 May 2026 17:56:18 +0300 Subject: [PATCH 2/3] fix migration.md link and remove empty spaces --- docs/index.md | 6 +++--- docs/migration.md | 17 +++++++---------- 2 files changed, 10 insertions(+), 13 deletions(-) diff --git a/docs/index.md b/docs/index.md index fa961c1cc..0fc3fa127 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,7 @@ # Percona Distribution for PostgreSQL 15 Documentation Percona Distribution for PostgreSQL is a suite of open source software, tools and services required to deploy and maintain a reliable production cluster for PostgreSQL. - + Percona Distribution for PostgreSQL includes [PostgreSQL server :octicons-link-external-16:](https://www.postgresql.org/docs/15/index.html), packaged with extensions from open source community that are certified and tested to work together for high availability, backups, security, and monitoring that help ensure the cluster's peak performance. Part of the solution, Percona Operator for PostgreSQL, makes it easy to orchestrate the cluster reliably and repeatably in Kubernetes. @@ -12,10 +12,10 @@ - No vendor lock in - all components of Percona Distribution for PostgreSQL are fully open source - No guesswork on finding the right version of a component – they all undergo thorough testing to ensure compatibility -- Freely available reference architectures for solutions like high-availability, backups and disaster recovery +- Freely available reference architectures for solutions like high-availability, backups and disaster recovery - Spatial data handling support via PostGIS - Monitoring of the database health, performance and infrastructure usage via open source [Percona Management and Monitoring :octicons-link-external-16:](https://www.percona.com/doc/percona-monitoring-and-management/2.x/index.html) with PostgreSQL-specific dashboards -- Run PostgreSQL on Kubernetes using open source [Percona Operator for PostgreSQL:octicons-link-external-16:](https://docs.percona.com/percona-operator-for-postgresql/2.0/index.html). It not only automates deployment and management of PostgreSQL clusters on Kubernetes, but also includes enterprise-ready features for high-availability, backup and restore, replication, logging, and more +- Run PostgreSQL on Kubernetes using open source [Percona Operator for PostgreSQL:octicons-link-external-16:](https://docs.percona.com/percona-operator-for-postgresql/2.0/index.html). It not only automates deployment and management of PostgreSQL clusters on Kubernetes, but also includes enterprise-ready features for high-availability, backup and restore, replication, logging, and more
diff --git a/docs/migration.md b/docs/migration.md index 4f3d22ce5..0aef5c320 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -1,11 +1,10 @@ -# Migrate from PostgreSQL to Percona Distribution for PostgreSQL - +# Migrate from PostgreSQL to Percona Distribution for PostgreSQL Percona Distribution for PostgreSQL includes the PostgreSQL database and additional extensions that have been selected to cover the needs of the enterprise and are guaranteed to work together. Percona Distribution for PostgreSQL is available as a software collection that is easy to deploy. -We encourage users to migrate from their PostgreSQL deployments based on community binaries to Percona Distribution for PostgreSQL. This document provides the migration instructions. +We encourage users to migrate from their PostgreSQL deployments based on community binaries to Percona Distribution for PostgreSQL. This document provides the migration instructions. -Depending on your business requirements, you may migrate to Percona Distribution for PostgreSQL either [on the same server](#migrate-on-the-same-server) or [onto a different server](#migrate-on-a-different-server). +Depending on your business requirements, you may migrate to Percona Distribution for PostgreSQL either [on the same server](#migrate-on-the-same-server) or [onto a different server](#migrate-on-a-different-server). ## Migrate on the same server @@ -49,7 +48,6 @@ Depending on your business requirements, you may migrate to Percona Distribution $ sudo systemctl start postgresql.service ``` - === "On RHEL and derivatives" > To ensure that your data is safe during the migration, we recommend to make a backup of your data and all configuration files (such as `pg_hba.conf`, `postgresql.conf`, `postgresql.auto.conf`) using the tool of your choice. The backup process is out of scope of this document. You can use `pg_dumpall` or other tools of your choice. @@ -84,7 +82,6 @@ Depending on your business requirements, you may migrate to Percona Distribution $ sudo systemctl start postgresql-15 ``` - ## Migrate on a different server In this scenario, we will refer to the server with PostgreSQL Community as the "source" and to the server with Percona Distribution for PostgreSQL as the "target". @@ -109,19 +106,19 @@ To migrate from PostgreSQL Community to Percona Distribution for PostgreSQL on a $ sudo systemctl stop postgresql-15 ``` -3. Optionally, remove PostgreSQL Community packages +3. Optionally, remove PostgreSQL Community packages **On the target server**: {.power-number} -1. [Install percona-release :octicons-link-external-16:](https://docs.percona.com/percona-software-repositories/installing.html) +1. [Install percona-release :octicons-link-external-16:](https://docs.percona.com/percona-software-repositories/installing.html) 2. Enable the repository ```{.bash data-prompt="$"} $ sudo percona-release setup ppg15 ``` -3. [Install Percona Distribution for PostgreSQL packages](installing.md#install-percona-distribution-for-postgresql) on the target server. +3. [Install Percona Distribution for PostgreSQL packages](installing.md) on the target server. 4. Restore the data from the backup 5. Start `postgresql` service @@ -135,4 +132,4 @@ To migrate from PostgreSQL Community to Percona Distribution for PostgreSQL on a ```{.bash data-prompt="$"} $ sudo systemctl start postgresql-15 - ``` \ No newline at end of file + ``` From c3f32dde0607d024ccf449c5050552031c93e467 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Tue, 5 May 2026 11:03:12 +0300 Subject: [PATCH 3/3] remove broken links --- docs/migration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/migration.md b/docs/migration.md index 0aef5c320..4b244796d 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -34,13 +34,13 @@ Depending on your business requirements, you may migrate to Percona Distribution $ sudo percona-release setup ppg15 ``` - 5. [Install Percona Distribution for PostgreSQL packages](installing.md#install-percona-distribution-for-postgresql) + 5. [Install Percona Distribution for PostgreSQL packages](installing.md) 6. (Optional) Restore the data from the backup. 7. Start the `postgresql` service. The installation process starts and initializes the default cluster automatically. You can check its status with: ```{.bash data-prompt="$"} $ sudo systemctl status postgresql - ``` + ``` If `postresql` service is not started, start it manually: @@ -74,7 +74,7 @@ Depending on your business requirements, you may migrate to Percona Distribution $ sudo percona-release setup ppg15 ``` - 5. [Install Percona Distribution for PostgreSQL packages](installing.md#install-percona-distribution-for-postgresql) + 5. [Install Percona Distribution for PostgreSQL packages](installing.md) 6. (Optional) Restore the data from the backup. 7. Start the `postgresql` service