diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 000000000..eb98bbf51 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,5 @@ +{ + "cSpell.words": [ + "Quickstart" + ] +} \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e90a877db..516ada5c4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,6 +32,8 @@ Each version has a branch in the repository named accordingly: - 12 - 13 - 14 +- 15 +- 16 The source .md files are in the ``docs`` directory. @@ -75,6 +77,7 @@ git remote add git@github.com:/postgresql-docs.git git fetch origin git merge origin/ ``` + Make sure that your local branch and the branch you merge changes from are the same. So if you are on ``11`` branch, merge changes from ``origin/11``. 5. Create a separate branch for your changes @@ -102,7 +105,7 @@ Learn more about the documentation structure in the [Repository structure](#repo 2. We use [this Docker image](https://github.com/Percona-Lab/percona-doc-docker) to build documentation. Run the following command: ```sh -docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md -f mkdocs-netlify.yml +docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md mkdocs build ``` If Docker can't find the image locally, it first downloads the image, and then runs it to build the documentation. @@ -110,7 +113,7 @@ docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md -f mkdocs-netlify.yml 4. To view your changes as you make them, run the following command: ``` sh -docker run --rm -p 8000:8000 -v $(pwd):/docs perconalab/pmm-doc-md mkdocs serve -f mkdocs-netlify.yml -a 0.0.0.0:8000 +docker run --rm -p 8000:8000 -v $(pwd):/docs perconalab/pmm-doc-md mkdocs serve -a 0.0.0.0:8000 ``` 5. To create a PDF version of the documentation, run the following command: @@ -128,13 +131,13 @@ The PDF document is in the ``site/pdf`` folder. 3. While in the root directory of the doc project, run the following command to build the documentation: ```sh -mkdocs build -f mkdocs-netlify.yml +mkdocs build ``` 4. Go to the ``site`` directory and open the ``index.html`` file in your web browser to see the documentation. 5. To automatically rebuild the documentation and reload the browser as you make changes, run the following command: ```sh -mkdocs serve -f mkdocs-netlify.yml +mkdocs serve ``` 6. To build the PDF documentation, do the following: @@ -153,7 +156,6 @@ The repository includes the following directories and files: - `mkdocs-base.yml` - the base configuration file. It includes general settings and documentation structure. - `mkdocs.yml` - configuration file. Contains the settings for building the docs on Percona website -- `mkdocs-netlify.yml` - configuration file. Contains the settings for building the docs with Material theme. - `mkdocs-pdf.yml` - configuration file. Contains the settings for building the PDF docs. - `docs`: - `*.md` - Source markdown files. diff --git a/README.md b/README.md index fd3fbd7b9..9a31a1752 100644 --- a/README.md +++ b/README.md @@ -6,14 +6,14 @@ Welcome to Percona Distribution for PostgreSQL documentation! Percona Distribution for PostgreSQL is a collection of tools to assist you in managing your PostgreSQL database system. It includes the upstream version of PostgreSQL and a selection of extensions that enable solving essential practical tasks efficiently. -This repository contains the source files for [Percona Distribution for PostgreSQL documentation](https://www.percona.com/doc/postgresql/13/index.html). The documentation is written in [reStructured text markup language](https://docutils.sourceforge.io/rst.html) and is created using [Sphinx Python Documentation Generator](https://www.sphinx-doc.org/en/master/). +This repository contains the source files for [Percona Distribution for PostgreSQL documentation](https://www.percona.com/doc/postgresql/15/index.html). The documentation is written in [Markdown](https://www.markdownguide.org/) markup langiage and is created using [MkDocs Documentation Generator](https://www.mkdocs.org/). ## Contributing -We welcome all contributions and are always looking for new members that are as dedicated to serving the community as we are. You can reach out to us using our [forums](https://forums.percona.com/c/postgresql/25) and [Jira issue tracker](https://jira.percona.com/projects/DISTPG/issues/DISTPG-16?filter=allopenissues). +We welcome all contributions and are always looking for new members that are as dedicated to serving the community as we are. You can reach out to us using our [forums ](https://forums.percona.com/c/postgresql/25) and [Jira issue tracker ](https://jira.percona.com/projects/DISTPG/issues/DISTPG-16?filter=allopenissues). -For how to contribute to documentation, read the [Contributing guide](https://github.com/percona/postgresql-docs/blob/13/CONTRIBUTING.md). +For how to contribute to documentation, read the [Contributing guide ](https://github.com/percona/postgresql-docs/blob/16/CONTRIBUTING.md). ## License -Percona Distribution for PostgreSQL documentation is licensed under the [PostgreSQL license](https://opensource.org/licenses/postgresql). \ No newline at end of file +Percona Distribution for PostgreSQL documentation is licensed under the [PostgreSQL license ](https://opensource.org/licenses/postgresql). diff --git a/docs/apt.md b/docs/apt.md index b24e287a2..0a1c630c7 100644 --- a/docs/apt.md +++ b/docs/apt.md @@ -1,6 +1,6 @@ # Install Percona Distribution for PostgreSQL on Debian and Ubuntu -This document describes how to install Percona Server for PostgreSQL from Percona repositories on DEB-based distributions such as Debian and Ubuntu. [Read more about Percona repositories :material-arrow-top-right:](repo-overview.md). +This document describes how to install Percona Server for PostgreSQL from Percona repositories on DEB-based distributions such as Debian and Ubuntu. [Read more about Percona repositories](repo-overview.md). ## Preconditions @@ -11,7 +11,7 @@ This document describes how to install Percona Server for PostgreSQL from Percon Run all the commands in the following sections as root or using the `sudo` command: -### Configure Percona repository +### Configure Percona repository {.power-number} 1. Install the `percona-release` repository management tool to subscribe to Percona repositories: @@ -53,6 +53,9 @@ Run all the commands in the following sections as root or using the `sudo` comma === "Install packages individually" + Run the following commands: + {.power-number} + 1. Install the PostgreSQL server package: ```{.bash data-prompt="$"} @@ -147,34 +150,10 @@ The installation process automatically initializes and starts the default databa $ sudo systemctl status postgresql.service ``` -### Connect to the PostgreSQL server - -By default, `postgres` user and `postgres` database are created in PostgreSQL upon its installation and initialization. This allows you to connect to the database as the `postgres` user. - -```{.bash data-prompt="$"} -$ sudo su postgres -``` - -Open the PostgreSQL interactive terminal: - -```{.bash data-prompt="$"} -$ psql -``` - -!!! hint - - You can connect to `psql` as the `postgres` user in one go: - - ```{.bash data-prompt="$"} - $ sudo su - postgres -c psql - ``` - -To exit the `psql` terminal, use the following command: - -```{.bash data-prompt="$"} -$ \q -``` +Congratulations! Your Percona Distribution for PostgreSQL is up and running. +## Next steps +[Enable extensions :material-arrow-right:](enable-extensions.md){.md-button} -[^1]: Are included in repositories for Debian 12 operating system \ No newline at end of file +[Connect to PostgreSQL :material-arrow-right:](connect.md){.md-button} diff --git a/docs/connect.md b/docs/connect.md new file mode 100644 index 000000000..18a1cb9b9 --- /dev/null +++ b/docs/connect.md @@ -0,0 +1,73 @@ +# Connect to the PostgreSQL server + +With PostgreSQL server up and running, let's connect to it. + +By default, the `postgres` user and the `postgres` database are created in PostgreSQL upon its installation and initialization. This allows you to connect to the database as the `postgres` user. +{.power-number} + +1. Switch to the `postgres` user. + + ```{.bash data-prompt="$"} + $ sudo su postgres + ``` + +2. Open the PostgreSQL interactive terminal `psql`: + + ```{.bash data-prompt="$"} + $ psql + ``` + + :material-information: Hint: You can connect to `psql` as the `postgres` user in one go: + + ```{.bash data-prompt="$"} + $ sudo su - postgres -c psql + ``` + + +## Basic `psql` commands + +While connected to PostgreSQL, let's practice some basic `psql` commands to interact with the database: + +1. List databases: + + ```{.bash data-prompt="$"} + $ \l + ``` + +2. Display tables in the current database: + + ```{.bash data-prompt="$"} + $ \dt + ``` + +3. Display columns in a table + + ```{.bash data-prompt="$"} + $ \d + ``` + +4. Switch databases + + ```{.bash data-prompt="$"} + $ \c + ``` + +5. Display users and roles + + ```{.bash data-prompt="$"} + $ \du + ``` + +6. Exit the `psql` terminal: + + ```{.bash data-prompt="$"} + $ \q + ``` + +To learn more about using `psql`, see [`psql` :octicons-link-external-16:](https://www.postgresql.org/docs/current/app-psql.html) documentation. + +Congratulations! You have connected to PostgreSQL and learned some essential `psql` commands. + +## Next steps + +[Manipulate data in PostgreSQL :material-arrow-right:](crud.md){.md-button} \ No newline at end of file diff --git a/docs/crud.md b/docs/crud.md new file mode 100644 index 000000000..75d43d710 --- /dev/null +++ b/docs/crud.md @@ -0,0 +1,112 @@ +# Manipulate data in PostgreSQL + +On the previous step, you have [connected to PostgreSQL](connect.md) as the superuser `postgres`. Now, let's insert some sample data and operate with it in PostgreSQL. + +## Create a database + +Let's create the database `test`. Use the CREATE DATABASE command: + +```sql +CREATE DATABASE test; +``` + +## Create a table + +Let's create a sample table `Customers` in the `test` database using the following command: + +```sql +CREATE TABLE customers ( + id SERIAL PRIMARY KEY, -- 'id' is an auto-incrementing integer + first_name VARCHAR(50), -- 'first_name' is a string with a maximum length of 50 characters + last_name VARCHAR(50), -- 'last_name' is a string with a maximum length of 50 characters + email VARCHAR(100) -- 'email' is a string with a maximum length of 100 characters +); +``` + +:material-information: Hint:Having issues with table creation? Check our [Troubleshooting guide](troubleshooting.md) + +## Insert the data + +Populate the table with the sample data as follows: + +```sql +INSERT INTO customers (first_name, last_name, email) +VALUES + ('John', 'Doe', 'john.doe@example.com'), -- Insert a new row + ('Jane', 'Doe', 'jane.doe@example.com'); + ('Alice', 'Smith', 'alice.smith@example.com'); +``` + +## Query data + +Let's verify the data insertion by querying it: + +```sql +SELECT * FROM customers; +``` + +??? example "Expected output" + + ```{.sql .no-copy} + id | first_name | last_name | email + ----+------------+-----------+------------------------- + 1 | John | Doe | john.doe@example.com + 2 | Jane | Doe | jane.doe@example.com + 3 | Alice | Smith | alice.smith@example.com + (3 rows) + ``` + +## Update data + +Let's update John Doe's record with a new email address. + +1. Use the UPDATE command for that: + + ```sql + UPDATE customers + SET email = 'john.doe@myemail.com' + WHERE first_name = 'John' AND last_name = 'Doe'; + ``` + +2. Query the table to verify the updated data: + + ```sql + SELECT * FROM customers WHERE first_name = 'John' AND last_name = 'Doe'; + ``` + + ??? example "Expected output" + + ```{.sql .no-copy} + id | first_name | last_name | email + ----+------------+-----------+------------------------- + 2 | Jane | Doe | jane.doe@example.com + 3 | Alice | Smith | alice.smith@example.com + 1 | John | Doe | john.doe@myemail.com + (3 rows) + ``` + +## Delete data + +Use the DELETE command to delete rows. For example, delete the record of Alice Smith: + +```sql +DELETE FROM Customers WHERE first_name = 'Alice' AND last_name = 'Smith'; +``` + +If you wish to delete the whole table, use the `DROP TABLE` command instead as follows: + +```sql +DROP TABLE customers; +``` + +To delete the whole database, use the DROP DATABASE command: + +```sql +DROP DATABASE test; +``` + +Congratulations! You have used basic create, read, update and delete (CRUD) operations to manipulate data in Percona Distribution for PostgreSQL. To deepen your knowledge, see the [data manipulation :octicons-link-external-16:](https://www.postgresql.org/docs/{{pgversion}}/dml.html) section in PostgreSQL documentation. + +## Next steps + +[What's next?](whats-next.md)(.md-button) \ No newline at end of file diff --git a/docs/docker.md b/docs/docker.md index 8c58d3ec4..274d44840 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -1,12 +1,12 @@ # Run Percona Distribution for PostgreSQL in a Docker container -Docker images of Percona Distribution for PostgreSQL are hosted publicly on [Docker Hub](https://hub.docker.com/r/percona/percona-distribution-postgresql/). +Docker images of Percona Distribution for PostgreSQL are hosted publicly on [Docker Hub :octicons-link-external-16:](https://hub.docker.com/r/percona/percona-distribution-postgresql/). -For more information about using Docker, see the [Docker Docs](https://docs.docker.com/). +For more information about using Docker, see the [Docker Docs :octicons-link-external-16:](https://docs.docker.com/). !!! note "" - Make sure that you are using the latest version of Docker. The ones provided via `apt` and `yum` may be outdated and cause errors. + Make sure that you are using [the latest version of Docker :octicons-link-external-16:](https://docs.docker.com/get-docker/). The ones provided via `apt` and `yum` may be outdated and cause errors. By default, Docker pulls the image from Docker Hub if it is not available locally. @@ -28,7 +28,7 @@ For more information about using Docker, see the [Docker Docs](https://docs.dock | `percona-pg_repack{{pgversion}}`| rebuilds PostgreSQL database objects.| | `percona-wal2json{{pgversion}}` | a PostgreSQL logical decoding JSON output plugin.| -## Start the container +## Start the container {.power-number} 1. Start a Percona Distribution for PostgreSQL container as follows: @@ -40,7 +40,7 @@ For more information about using Docker, see the [Docker Docs](https://docs.dock * `container-name` is the name you assign to your container * `POSTGRES_PASSWORD` is the superuser password - `tag-multi` is the tag specifying the version you need. For example, `{{dockertag}}-multi`. The `multi` part of the tag serves to identify the architecture (x86_64 or ARM64) and pull the respective image. See the [full list of tags](https://hub.docker.com/r/percona/percona-distribution-postgresql/tags/). + * `tag-multi` is the tag specifying the version you need. For example, `{{dockertag}}-multi`. The `multi` part of the tag serves to identify the architecture (x86_64 or ARM64) and pull the respective image. See the [full list of tags :octicons-link-external-16:](https://hub.docker.com/r/percona/percona-distribution-postgresql/tags/). !!! tip diff --git a/docs/enable-extensions.md b/docs/enable-extensions.md index a7f49777d..861507651 100644 --- a/docs/enable-extensions.md +++ b/docs/enable-extensions.md @@ -10,20 +10,20 @@ While setting up a high availability PostgreSQL cluster with Patroni, you will n - Patroni installed on every ``postresql`` node. -- Distributed Configuration Store (DCS). Patroni supports such DCSs as ETCD, zookeeper, Kubernetes though [ETCD](https://etcd.io/) is the most popular one. It is available within Percona Distribution for PostgreSQL for all supported operating systems. +- Distributed Configuration Store (DCS). Patroni supports such DCSs as etcd, zookeeper, Kubernetes though [etcd](https://etcd.io/) is the most popular one. It is available within Percona Distribution for PostgreSQL for all supported operating systems. -- [HAProxy](http://www.haproxy.org/). +- [HAProxy :octicons-link-external-16:](http://www.haproxy.org/). See the configuration guidelines for [Debian and Ubuntu](solutions/ha-setup-apt.md) and [RHEL and CentOS](solutions/ha-setup-yum.md). !!! admonition "See also" - - [Patroni documentation](https://patroni.readthedocs.io/en/latest/SETTINGS.html#settings) + - [Patroni documentation :octicons-link-external-16:](https://patroni.readthedocs.io/en/latest/SETTINGS.html#settings) - Percona Blog: - - [PostgreSQL HA with Patroni: Your Turn to Test Failure Scenarios](https://www.percona.com/blog/2021/06/11/postgresql-ha-with-patroni-your-turn-to-test-failure-scenarios/) + - [PostgreSQL HA with Patroni: Your Turn to Test Failure Scenarios :octicons-link-external-16:](https://www.percona.com/blog/2021/06/11/postgresql-ha-with-patroni-your-turn-to-test-failure-scenarios/) **pgBadger** @@ -41,11 +41,11 @@ log_autovacuum_min_duration = 0 log_error_verbosity = default ``` -For details about each option, see [pdBadger documentation](https://github.com/darold/pgbadger/#POSTGRESQL-CONFIGURATION). +For details about each option, see [pdBadger documentation :octicons-link-external-16:](https://github.com/darold/pgbadger/#POSTGRESQL-CONFIGURATION). **pgAudit set-user** -Add the `set-user` to `shared_preload_libraries` in `postgresql.conf`. The recommended way is to use the [ALTER SYSTEM](https://www.postgresql.org/docs/14/sql-altersystem.html) command. [Connect to psql](#connect-to-the-postgresql-server) and use the following command: +Add the `set-user` to `shared_preload_libraries` in `postgresql.conf`. The recommended way is to use the [ALTER SYSTEM :octicons-link-external-16:](https://www.postgresql.org/docs/15/sql-altersystem.html) command. [Connect to psql](#connect-to-the-postgresql-server) and use the following command: ```sql ALTER SYSTEM SET shared_preload_libraries = 'set-user'; @@ -53,7 +53,7 @@ ALTER SYSTEM SET shared_preload_libraries = 'set-user'; Start / restart the server to apply the configuration. -You can fine-tune user behavior with the [custom parameters](https://github.com/pgaudit/set_user#configuration-options) supplied with the extension. +You can fine-tune user behavior with the [custom parameters :octicons-link-external-16:](https://github.com/pgaudit/set_user#configuration-options) supplied with the extension. **wal2json** @@ -62,3 +62,7 @@ After the installation, enable the following option in `postgresql.conf` configu ``` wal_level = logical ``` + +## Next steps + +[Connect to PostgreSQL :material-arrow-right:](connect.md){.md-button} \ No newline at end of file diff --git a/docs/extensions.md b/docs/extensions.md index 1b2ca9e00..731214407 100644 --- a/docs/extensions.md +++ b/docs/extensions.md @@ -5,17 +5,21 @@ Percona Distribution for PostgreSQL includes a set of extensions that have been The set of extensions includes the following: * [PostgreSQL contrib modules and utilities](contrib.md) -* [Third-party components](third-party.md) * Extensions authored by Percona: * [`pg_stat_monitor`](pg-stat-monitor.md) - * [`pg_tde`](#) +* [Third-party components](third-party.md) * Extra modules, not included in Percona Distribution for PostgreSQL but tested to work with it and supported by Percona. +* Other [PostgreSQL software covered by Percona Support](https://www.percona.com/services/support/support-tiers-postgresql). + + +Percona also supports [extra modules](https://repo.percona.com/ppg-16-extras/), not included in Percona Distribution for PostgreSQL but tested to work with it. + +Additionally, see the list of [PostgreSQL software](https://www.percona.com/services/support/support-tiers-postgresql) covered by Percona Support. ## Install an extension To use an extension, install it. Run the [`CREATE EXTENSION`](https://www.postgresql.org/docs/current/static/sql-createextension.html) command on the PostgreSQL node where you want the extension to be available. The user should be a superuser or have the `CREATE` privilege on the current database to be able to run the [`CREATE EXTENSION`](https://www.postgresql.org/docs/current/static/sql-createextension.html) command. Some extensions may require additional privileges depending on their functionality. To learn more, check the documentation for the desired extension. - diff --git a/docs/how-to.md b/docs/how-to.md index e68fa0548..1d73b4957 100644 --- a/docs/how-to.md +++ b/docs/how-to.md @@ -1,14 +1,14 @@ # How to -## How to configure ETCD nodes simultaneously +## How to configure `etcd` nodes simultaneously !!! note - We assume you have a deeper knowledge of how ETCD works. Otherwise, refer to the configuration where you add ETCD nodes one by one. + We assume you have a deeper knowledge of how etcd works. Otherwise, refer to the configuration where you add etcd nodes one by one. Instead of adding `etcd` nodes one by one, you can configure and start all nodes in parallel. -1. Create ETCD configuration file on every node. You can edit the sample configuration file `/etc/etcd/etcd.conf.yaml` or create your own one. Replace the node names and IP addresses with the actual names and IP addresses of your nodes: +1. Create etcd configuration file on every node. You can edit the sample configuration file `/etc/etcd/etcd.conf.yaml` or create your own one. Replace the node names and IP addresses with the actual names and IP addresses of your nodes: === "node1" @@ -58,7 +58,7 @@ Instead of adding `etcd` nodes one by one, you can configure and start all nodes $ sudo systemctl enable --now etcd ``` - During the node start, ETCD searches for other cluster nodes defined in the configuration. If the other nodes are not yet running, the start may fail by a quorum timeout. This is expected behavior. Try starting all nodes again at the same time for the ETCD cluster to be created. + During the node start, etcd searches for other cluster nodes defined in the configuration. If the other nodes are not yet running, the start may fail by a quorum timeout. This is expected behavior. Try starting all nodes again at the same time for the etcd cluster to be created. 3. Check the etcd cluster members. Connect to one of the nodes and run the following command: diff --git a/docs/index.md b/docs/index.md index c70b35851..f8615b0ae 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,28 +1,53 @@ # Percona Distribution for PostgreSQL 15 Documentation -Percona Distribution for PostgreSQL is a collection of tools to assist you in managing your PostgreSQL -database system: it installs PostgreSQL and complements it by a selection of -extensions that enable solving essential practical tasks efficiently. + 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. + + Part of the solution, Percona Operator for PostgreSQL, makes it easy to orchestrate the cluster reliably and repeatably in Kubernetes. -[What's included in the Distribution](extensions.md){.md-button} +[What's included in Percona Distribution for PostgreSQL? :material-arrow-right:](extensions.md){.md-button} -[Get started](installing.md){ .md-button } -[What's new]({{release}}.md){ .md-button } +## What’s in it for you? -!!! admonition "See also" +- 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 +- 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 - Percona Blog: +
- - [pgBackRest - A Great Backup Solution and a Wonderful Year of - Growth](https://www.percona.com/blog/2019/05/10/pgbackrest-a-great-backup-solution-and-a-wonderful-year-of-growth/) - - [Securing PostgreSQL as an Enterprise-Grade - Environment](https://www.percona.com/blog/2018/09/21/securing-postgresql-as-an-enterprise-grade-environment/) +## :material-progress-download: Installation guides { .title } +Get started quickly with the step-by-step installation instructions. + +[Quickstart guides :material-arrow-right:](installing.md){ .md-button } + +
+ +### :fontawesome-solid-gears: Solutions { .title } + +Check our solutions to build the database infrastructure that meets the requirements of your organization - be it high-availability, disaster recovery or spatial data handling. + +[Solutions :material-arrow-right:](solutions/index.md){ .md-button } + +
+ +### :material-frequently-asked-questions: Troubleshooting and FAQ { .title } + +Our comprehensive resources will help you overcome challenges, from everyday issues to specific doubts. + +[Troubleshooting :material-arrow-right:](troubleshooting.md){.md-button} + +
+ +### :loudspeaker: What's new? { .title } + +Learn about the releases and changes in the Distribution. + +[Release notes :material-arrow-right:](release-notes.md){.md-button} +
+
-Percona Distribution for PostgreSQL is also shipped with the -[libpq](https://www.postgresql.org/docs/15/libpq.html) library. It -contains "a set of library functions that allow client programs to pass -queries to the PostgreSQL backend server and to receive the results of -these queries." diff --git a/docs/installing.md b/docs/installing.md index 5e762e46d..ca33e4b09 100644 --- a/docs/installing.md +++ b/docs/installing.md @@ -1,36 +1,55 @@ -# Install Percona Distribution for PostgreSQL +# Quickstart guide -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 :material-arrow-top-right: ](index.md). +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). + +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: + +* 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 + +## Install Percona Distribution for PostgreSQL You can select from multiple easy-to-follow installation options, but **we recommend using a Package Manager** for a convenient and quick way to try the software first. -=== "Package manager" +=== ":simple-windowsterminal: 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](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. 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). If you are on Debian or Ubuntu, use `apt` for installation. If you are on Red Hat Enterprise Linux or compatible derivatives, use `yum`. - Choose your package manager below to get access to a detailed step-by-step guide. - [Install via apt :material-arrow-right:](apt.md){.md-button} [Install via yum :material-arrow-right:](yum.md){.md-button} -=== "Docker" + +=== ":simple-docker: Docker" Get our image from Docker Hub and spin up a cluster on a Docker container for quick evaluation. Check below to get access to a detailed step-by-step guide. - [Run in Docker](docker.md){.md-button} + [Run in Docker :material-arrow-right:](docker.md){.md-button} -=== "Kubernetes" +=== ":simple-kubernetes: Kubernetes" **Percona Operator for Kubernetes** is a controller introduced to simplify complex deployments that require meticulous and secure database expertise. Check below to get access to a detailed step-by-step guide. - [Get started with Percona Operator](https://docs.percona.com/percona-operator-for-postgresql/2.0/quickstart.html){.md-button} + [Get started with Percona Operator :octicons-link-external-16:](https://docs.percona.com/percona-operator-for-postgresql/2.0/quickstart.html){.md-button} + +=== ":octicons-download-16: Manual download" + + If you need to install Percona Distribution for PostgreSQL offline or as a non-superuser, check out the link below for a step-by-step guide and get access to the downloads directory. + + Note that for this scenario you must make sure that all dependencies are satisfied. + + [Install from tarballs :material-arrow-right:](tarball.md){.md-button} + + + diff --git a/docs/ldap.md b/docs/ldap.md index 4aa2961f4..45e24eba1 100644 --- a/docs/ldap.md +++ b/docs/ldap.md @@ -2,6 +2,6 @@ When a client application or a user that runs the client application connects to the database, it must identify themselves. The process of validating the client's identity and determining whether this client is permitted to access the database it has requested is called **authentication**. -Percona Distribution for PortgreSQL supports several [authentication methods](https://www.postgresql.org/docs/15/auth-methods.html), including the [LDAP authentication](https://www.postgresql.org/docs/14/auth-ldap.html). The use of LDAP is to provide a central place for authentication - meaning the LDAP server stores usernames and passwords and their resource permissions. +Percona Distribution for PortgreSQL supports several [authentication methods :octicons-link-external-16:](https://www.postgresql.org/docs/15/auth-methods.html), including the [LDAP authentication :octicons-link-external-16:](https://www.postgresql.org/docs/14/auth-ldap.html). The use of LDAP is to provide a central place for authentication - meaning the LDAP server stores usernames and passwords and their resource permissions. The LDAP authentication in Percona Distribution for PortgreSQL is implemented the same way as in upstream PostgreSQL. \ No newline at end of file diff --git a/docs/licensing.md b/docs/licensing.md index 0d5deb93b..7a9b3b62c 100644 --- a/docs/licensing.md +++ b/docs/licensing.md @@ -1,7 +1,7 @@ # Copyright and licensing information -Percona Distribution for PostgreSQL is licensed under the [PostgreSQL license](https://opensource.org/licenses/postgresql) and licenses of all components included in the Distribution. +Percona Distribution for PostgreSQL is licensed under the [PostgreSQL license :octicons-link-external-16:](https://opensource.org/licenses/postgresql) and licenses of all components included in the Distribution. ## Documentation licensing -Percona Distribution for PostgreSQL documentation is (C)2009-2023 Percona LLC and/or its affiliates and is distributed under the [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/). +Percona Distribution for PostgreSQL documentation is (C)2009-2023 Percona LLC and/or its affiliates and is distributed under the [Creative Commons Attribution 4.0 International License :octicons-link-external-16:](https://creativecommons.org/licenses/by/4.0/). diff --git a/docs/major-upgrade.md b/docs/major-upgrade.md index 0820f4193..e132d5655 100644 --- a/docs/major-upgrade.md +++ b/docs/major-upgrade.md @@ -54,15 +54,13 @@ The exact steps may differ depending on the package manager of your operating sy ## On Debian and Ubuntu using `apt` -!!! important - - Run **all** commands as root or via **sudo**. - +Run **all** commands as root or via **sudo**: +{.power-number} 1. Install Percona Distribution for PostgreSQL 15 packages. - * [Install percona-release](https://docs.percona.com/percona-software-repositories/installing.html) + * [Install percona-release :octicons-link-external-16:](https://docs.percona.com/percona-software-repositories/installing.html) * Enable Percona repository: @@ -215,15 +213,13 @@ The exact steps may differ depending on the package manager of your operating sy ## On Red Hat Enterprise Linux and CentOS using `yum` -!!! important - - Run **all** commands as root or via **sudo**. - +Run **all** commands as root or via **sudo**: +{.power-number} 1. Install Percona Distribution for PostgreSQL 15 packages - * [Install percona-release](https://docs.percona.com/percona-software-repositories/installing.html) + * [Install percona-release :octicons-link-external-16:](https://docs.percona.com/percona-software-repositories/installing.html) * Enable Percona repository: diff --git a/docs/migration.md b/docs/migration.md index 53ac698b4..c08d2ba0e 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -11,7 +11,10 @@ Depending on your business requirements, you may migrate to Percona Distribution === "On Debian and Ubuntu Linux" - >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. + >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. For more information, see the blog post [PostgreSQL Upgrade Using pg_dumpall](https://www.percona.com/blog/postgresql-upgrade-using-pg_dumpall/) by _Avinash Vallarapu_, _Fernando Laudares Camargos_, _Jobin Augustine_ and _Nickolay Ihalainen_. + + Run **all** commands as root or via **sudo**: + {.power-number} 1. Stop the `postgresql` server @@ -25,7 +28,7 @@ Depending on your business requirements, you may migrate to Percona Distribution $ sudo apt-get --purge remove postgresql ``` - 3. [Install percona-release](https://docs.percona.com/percona-software-repositories/installing.html) + 3. [Install percona-release :octicons-link-external-16:](https://docs.percona.com/percona-software-repositories/installing.html) 4. Enable the repository ```{.bash data-prompt="$"} @@ -51,7 +54,10 @@ Depending on your business requirements, you may migrate to Percona Distribution > 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. - 1. Stop the `postgresql` server + Run **all** commands as root or via **sudo**: + {.power-number} + + 1. Stop the `postgresql` server ```{.bash data-prompt="$"} $ sudo systemctl stop postgresql-15 @@ -63,7 +69,7 @@ Depending on your business requirements, you may migrate to Percona Distribution $ sudo yum remove postgresql ``` - 3. [Install percona-release](https://docs.percona.com/percona-software-repositories/installing.html) + 3. [Install percona-release :octicons-link-external-16:](https://docs.percona.com/percona-software-repositories/installing.html) 4. Enable the repository ```{.bash data-prompt="$"} @@ -86,6 +92,7 @@ In this scenario, we will refer to the server with PostgreSQL Community as the " To migrate from PostgreSQL Community to Percona Distribution for PostgreSQL on a different server, do the following: **On the source server**: +{.power-number} 1. Back up your data and all configuration files (such as `pg_hba.conf`, `postgresql.conf`, `postgresql.auto.conf`) using the tool of your choice. 2. Stop the `postgresql` service @@ -105,8 +112,9 @@ To migrate from PostgreSQL Community to Percona Distribution for PostgreSQL on a 3. Optionally, remove PostgreSQL Community packages **On the target server**: +{.power-number} -1. [Install percona-release](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="$"} diff --git a/docs/minor-upgrade.md b/docs/minor-upgrade.md index deea29ccf..17004e218 100644 --- a/docs/minor-upgrade.md +++ b/docs/minor-upgrade.md @@ -23,12 +23,10 @@ Minor upgrade of Percona Distribution for PostgreSQL includes the following step For more information about Percona repositories, refer to [Installing Percona Distribution for PostgreSQL](installing.md). - Before the upgrade, update the **percona-release** utility to the latest version. This is required to install the new version packages of Percona Distribution for PostgreSQL. Refer to [Percona Software Repositories Documentation](https://www.percona.com/doc/percona-repo-config/percona-release.html#updating-percona-release-to-the-latest-version) for update instructions. - -!!! important - - Run all commands as root or via **sudo**. + Before the upgrade, [update the `percona-release` :octicons-link-external-16:](https://www.percona.com/doc/percona-repo-config/percona-release.html#updating-percona-release-to-the-latest-version) utility to the latest version. This is required to install the new version packages of Percona Distribution for PostgreSQL. +Run **all** commands as root or via **sudo**: +{.power-number} 1. Stop the `postgresql` service. diff --git a/docs/pg-stat-monitor.md b/docs/pg-stat-monitor.md index 2d4c6ac28..e5aaf1087 100644 --- a/docs/pg-stat-monitor.md +++ b/docs/pg-stat-monitor.md @@ -29,7 +29,7 @@ When a bucket lifetime expires, `pg_stat_monitor` resets all statistics and writ #### pg_stat_monitor view -The `pg_stat_monitor` view contains all the statistics collected and aggregated by the extension. This view contains one row for each distinct combination of metrics and whether it is a top-level statement or not (up to the maximum number of distinct statements that the module can track). For details about available metrics, refer to the [`pg_stat_monitor` view reference](https://docs.percona.com/pg-stat-monitor/reference.html). +The `pg_stat_monitor` view contains all the statistics collected and aggregated by the extension. This view contains one row for each distinct combination of metrics and whether it is a top-level statement or not (up to the maximum number of distinct statements that the module can track). For details about available metrics, refer to the [`pg_stat_monitor` view reference :octicons-link-external-16:](https://docs.percona.com/pg-stat-monitor/reference.html). The following are the primary keys for pg_stat_monitor: @@ -73,11 +73,11 @@ To learn more, see the [Changing the configuration](#changing-the-configuration) ## Installation -This section describes how to install `pg_stat_monitor` from Percona repositories. To learn about other installation methods, see the [Installation](https://docs.percona.com/pg-stat-monitor/install.html) section in the `pg_stat_monitor` documentation. +This section describes how to install `pg_stat_monitor` from Percona repositories. To learn about other installation methods, see the [Installation :octicons-link-external-16:](https://docs.percona.com/pg-stat-monitor/install.html) section in the `pg_stat_monitor` documentation. **Preconditions**: -To install `pg_stat_monitor` from Percona repositories, you need to subscribe to them. To do this, you must have the [`percona-release` repository management tool](https://www.percona.com/doc/percona-repo-config/installing.html) up and running. +To install `pg_stat_monitor` from Percona repositories, you need to subscribe to them. To do this, you must have the [`percona-release` repository management tool :octicons-link-external-16:](https://www.percona.com/doc/percona-repo-config/installing.html) up and running. To install `pg_stat_monitor`, run the following commands: @@ -116,7 +116,7 @@ To install `pg_stat_monitor`, run the following commands: 1. Add `pg_stat_monitor` in the `shared_preload_libraries` configuration parameter. - The recommended way to modify PostgreSQL configuration file is using the [ALTER SYSTEM](https://www.postgresql.org/docs/15/sql-altersystem.html) command. [Connect to psql](installing.md#connect-to-the-server) and use the following command: + The recommended way to modify PostgreSQL configuration file is using the [ALTER SYSTEM :octicons-link-external-16:](https://www.postgresql.org/docs/15/sql-altersystem.html) command. [Connect to psql](installing.md#connect-to-the-server) and use the following command: ```sql ALTER SYSTEM SET shared_preload_libraries = 'pg_stat_monitor'; @@ -197,7 +197,7 @@ Output: ``` -Find more usage examples in the [`pg_stat_monitor` user guide](https://docs.percona.com/pg-stat-monitor/user_guide.html). +Find more usage examples in the [`pg_stat_monitor` user guide :octicons-link-external-16:](https://docs.percona.com/pg-stat-monitor/user_guide.html). ## Changing the configuration @@ -231,7 +231,7 @@ SELECT name, short_desc FROM pg_settings WHERE name LIKE '%pg_stat_monitor%'; pg_stat_monitor.pgsm_track_utility | Selects whether utility commands are tracked. ``` -You can change a parameter by setting a new value in the configuration file. Some parameters require server restart to apply a new value. For others, configuration reload is enough. Refer to the [configuration parameters](https://docs.percona.com/pg-stat-monitor/configuration.html) of the `pg_stat_monitor` documentation for the parameters’ description, how you can change their values and if the server restart is required to apply them. +You can change a parameter by setting a new value in the configuration file. Some parameters require server restart to apply a new value. For others, configuration reload is enough. Refer to the [configuration parameters :octicons-link-external-16:](https://docs.percona.com/pg-stat-monitor/configuration.html) of the `pg_stat_monitor` documentation for the parameters’ description, how you can change their values and if the server restart is required to apply them. As an example, let’s set the bucket lifetime from default 60 seconds to 40 seconds. Use the **ALTER SYSTEM** command: @@ -268,10 +268,10 @@ WHERE name = 'pg_stat_monitor.pgsm_bucket_time'; !!! admonition "See also" - [`pg_stat_monitor` Documentation](https://docs.percona.com/pg-stat-monitor/index.html) + [`pg_stat_monitor` Documentation :octicons-link-external-16:](https://docs.percona.com/pg-stat-monitor/index.html) Percona Blog: - * [pg_stat_monitor: A New Way Of Looking At PostgreSQL Metrics](https://www.percona.com/blog/2021/01/19/pg_stat_monitor-a-new-way-of-looking-at-postgresql-metrics/) - * [Improve PostgreSQL Query Performance Insights with pg_stat_monitor](https://www.percona.com/blog/improve-postgresql-query-performance-insights-with-pg_stat_monitor/) + * [pg_stat_monitor: A New Way Of Looking At PostgreSQL Metrics :octicons-link-external-16:](https://www.percona.com/blog/2021/01/19/pg_stat_monitor-a-new-way-of-looking-at-postgresql-metrics/) + * [Improve PostgreSQL Query Performance Insights with pg_stat_monitor :octicons-link-external-16:](https://www.percona.com/blog/improve-postgresql-query-performance-insights-with-pg_stat_monitor/) diff --git a/docs/release-notes-v15.0.md b/docs/release-notes-v15.0.md index 34de0e6d9..84185e7b5 100644 --- a/docs/release-notes-v15.0.md +++ b/docs/release-notes-v15.0.md @@ -65,12 +65,12 @@ The following is the list of extensions available in Percona Distribution for Po Percona Distribution for PostgreSQL also includes the following packages: * `llvm` 12.0.1 packages for Red Hat Enterprise Linux 8 / CentOS 8. This fixes compatibility issues with LLVM from upstream. -* supplemental `ETCD` packages which can be used for setting up Patroni clusters. These packages are available for the following operating systems: +* supplemental `etcd` packages which can be used for setting up Patroni clusters. These packages are available for the following operating systems: | Operating System | Package | Version | Description | | ------------------- | ---------------------| --------| ------------------ | | CentOS 8 | `etcd` | 3.3.11 | A consistent, distributed key-value store| -| | `python3-python-etcd`| 0.4.3 | A Python client for ETCD | +| | `python3-python-etcd`| 0.4.3 | A Python client for etcd | diff --git a/docs/release-notes-v15.1.md b/docs/release-notes-v15.1.md index 4e15934fb..2a1fc8419 100644 --- a/docs/release-notes-v15.1.md +++ b/docs/release-notes-v15.1.md @@ -34,12 +34,12 @@ The following is the list of extensions available in Percona Distribution for Po Percona Distribution for PostgreSQL also includes the following packages: * `llvm` 12.0.1 packages for Red Hat Enterprise Linux 8 / CentOS 8. This fixes compatibility issues with LLVM from upstream. -* supplemental `ETCD` packages which can be used for setting up Patroni clusters. These packages are available for the following operating systems: +* supplemental `etcd` packages which can be used for setting up Patroni clusters. These packages are available for the following operating systems: | Operating System | Package | Version | Description | | ------------------- | ---------------------| --------| ------------------ | | CentOS 8 | `etcd` | 3.3.11 | A consistent, distributed key-value store| -| | `python3-python-etcd`| 0.4.3 | A Python client for ETCD | +| | `python3-python-etcd`| 0.4.3 | A Python client for etcd | diff --git a/docs/release-notes-v15.2.md b/docs/release-notes-v15.2.md index 51e5a258a..43ebf7f89 100644 --- a/docs/release-notes-v15.2.md +++ b/docs/release-notes-v15.2.md @@ -38,12 +38,12 @@ The following is the list of extensions available in Percona Distribution for Po Percona Distribution for PostgreSQL also includes the following packages: * `llvm` 12.0.1 packages for Red Hat Enterprise Linux 8 / CentOS 8. This fixes compatibility issues with LLVM from upstream. -* supplemental `ETCD` packages which can be used for setting up Patroni clusters. These packages are available for the following operating systems: +* supplemental `etcd` packages which can be used for setting up Patroni clusters. These packages are available for the following operating systems: | Operating System | Package | Version | Description | | ------------------- | ---------------------| --------| ------------------ | | CentOS 8 | `etcd` | 3.3.11 | A consistent, distributed key-value store| -| | `python3-python-etcd`| 0.4.3 | A Python client for ETCD | +| | `python3-python-etcd`| 0.4.3 | A Python client for etcd | diff --git a/docs/release-notes-v15.3.md b/docs/release-notes-v15.3.md index 9566d1938..76e438ca1 100644 --- a/docs/release-notes-v15.3.md +++ b/docs/release-notes-v15.3.md @@ -38,12 +38,12 @@ The following is the list of extensions available in Percona Distribution for Po Percona Distribution for PostgreSQL also includes the following packages: * `llvm` 12.0.1 packages for Red Hat Enterprise Linux 8 / CentOS 8. This fixes compatibility issues with LLVM from upstream. -* supplemental `ETCD` packages which can be used for setting up Patroni clusters. These packages are available for the following operating systems: +* supplemental `etcd` packages which can be used for setting up Patroni clusters. These packages are available for the following operating systems: | Operating System | Package | Version | Description | | ------------------- | ---------------------| --------| ------------------ | | CentOS 8 | `etcd` | 3.3.11 | A consistent, distributed key-value store| -| | `python3-python-etcd`| 0.4.3 | A Python client for ETCD | +| | `python3-python-etcd`| 0.4.3 | A Python client for etcd | Percona Distribution for PostgreSQL is also shipped with the [libpq](https://www.postgresql.org/docs/15/libpq.html) library. It contains "a set of diff --git a/docs/release-notes-v15.4.md b/docs/release-notes-v15.4.md index 6353c2d30..385de41a5 100644 --- a/docs/release-notes-v15.4.md +++ b/docs/release-notes-v15.4.md @@ -41,12 +41,12 @@ The following is the list of extensions available in Percona Distribution for Po Percona Distribution for PostgreSQL also includes the following packages: * `llvm` 12.0.1 packages for Red Hat Enterprise Linux 8 / CentOS 8. This fixes compatibility issues with LLVM from upstream. -* supplemental `ETCD` packages which can be used for setting up Patroni clusters. These packages are available for the following operating systems: +* supplemental `etcd` packages which can be used for setting up Patroni clusters. These packages are available for the following operating systems: | Operating System | Package | Version | Description | | ------------------- | ---------------------| --------| ------------------ | | CentOS 8 | `etcd` | 3.3.11 | A consistent, distributed key-value store| -| | `python3-python-etcd`| 0.4.5 | A Python client for ETCD | +| | `python3-python-etcd`| 0.4.5 | A Python client for etcd | Percona Distribution for PostgreSQL is also shipped with the [libpq](https://www.postgresql.org/docs/15/libpq.html) library. It contains "a set of diff --git a/docs/release-notes-v15.5.md b/docs/release-notes-v15.5.md index 252d7bf93..98006859d 100644 --- a/docs/release-notes-v15.5.md +++ b/docs/release-notes-v15.5.md @@ -37,12 +37,12 @@ The following is the list of extensions available in Percona Distribution for Po Percona Distribution for PostgreSQL also includes the following packages: * `llvm` 12.0.1 packages for Red Hat Enterprise Linux 8 and compatible derivatives. This fixes compatibility issues with LLVM from upstream. -* supplemental `ETCD` packages which can be used for setting up Patroni clusters. These packages are available for the following operating systems: +* supplemental `etcd` packages which can be used for setting up Patroni clusters. These packages are available for the following operating systems: | Operating System | Package | Version | Description | | ------------------- | ---------------------| --------| ------------------ | | RHEL 8 | `etcd` | 3.3.11 | A consistent, distributed key-value store| -| | `python3-python-etcd`| 0.4.5 | A Python client for ETCD | +| | `python3-python-etcd`| 0.4.5 | A Python client for etcd | Percona Distribution for PostgreSQL is also shipped with the [libpq](https://www.postgresql.org/docs/15/libpq.html) library. It contains "a set of diff --git a/docs/release-notes-v15.6.md b/docs/release-notes-v15.6.md index 252ee21c7..7c77f7f5f 100644 --- a/docs/release-notes-v15.6.md +++ b/docs/release-notes-v15.6.md @@ -35,12 +35,12 @@ The following is the list of extensions available in Percona Distribution for Po Percona Distribution for PostgreSQL also includes the following packages: * `llvm` 12.0.1 packages for Red Hat Enterprise Linux 8 and compatible derivatives. This fixes compatibility issues with LLVM from upstream. -* supplemental `ETCD` packages which can be used for setting up Patroni clusters. These packages are available for the following operating systems: +* supplemental `etcd` packages which can be used for setting up Patroni clusters. These packages are available for the following operating systems: | Operating System | Package | Version | Description | | ------------------- | ---------------------| --------| ------------------ | | RHEL 8 | `etcd` | 3.5.12 | A consistent, distributed key-value store| -| | `python3-python-etcd`| 0.4.5 | A Python client for ETCD | +| | `python3-python-etcd`| 0.4.5 | A Python client for etcd | Percona Distribution for PostgreSQL is also shipped with the [libpq](https://www.postgresql.org/docs/15/libpq.html) library. It contains "a set of diff --git a/docs/release-notes-v15.7.md b/docs/release-notes-v15.7.md index 6fa2ba3be..cf5b60e9d 100644 --- a/docs/release-notes-v15.7.md +++ b/docs/release-notes-v15.7.md @@ -8,7 +8,7 @@ This release of Percona Distribution for PostgreSQL is based on [PostgreSQL 15.7 ## Release Highlights -* Percona Distribution for PostgreSQL now includes the ETCD distributed configuration store version 3.5.x for all supported operating systems. This enhancement simplifies deploying high-availability solutions because you can install all necessary components from a single source, ensuring their seamless compatibility. +* Percona Distribution for PostgreSQL now includes the etcd distributed configuration store version 3.5.x for all supported operating systems. This enhancement simplifies deploying high-availability solutions because you can install all necessary components from a single source, ensuring their seamless compatibility. * Percona Distribution for PostgreSQL is now available on Ubuntu 24.04 LTS Noble Numbat. * Percona Distribution for PostgreSQL on Red Hat Enterprise Linux 8 and compatible derivatives is now fully compatible with upstream `llvm` packages and includes the latest version 16.0.6 of them. @@ -20,7 +20,7 @@ The following is the list of extensions available in Percona Distribution for Po | Extension | Version | Description | | ------------------- | -------------- | ---------------------------- | -| [ETCD](https://etcd.io/)| 3.5.13 | A distributed, reliable key-value store for setting up high available Patroni clusters | +| [etcd](https://etcd.io/)| 3.5.13 | A distributed, reliable key-value store for setting up high available Patroni clusters | | [HAProxy](http://www.haproxy.org/) | 2.8.9 | a high-availability and load-balancing solution | | [Patroni](https://patroni.readthedocs.io/en/latest/) | 3.3.0 | a HA (High Availability) solution for PostgreSQL | | [pgaudit](https://www.pgaudit.org/) | 1.7.0 | provides detailed session or object audit logging via the standard logging facility provided by PostgreSQL | diff --git a/docs/repo-overview.md b/docs/repo-overview.md index 37f1ad02a..2cf7186e5 100644 --- a/docs/repo-overview.md +++ b/docs/repo-overview.md @@ -52,10 +52,4 @@ The `percona-ppg-server-ha` meta-package installs high-availability components t | `percona-patroni`| A high-availability solution for PostgreSQL. | | `percona-haproxy`| A high-availability and load-balancing solution | | `etcd` | A consistent, distributed key-value store | -| `python3-python-etcd` | A Python client for ETCD.[^1] | -| `etcd-client`, `etcd-server` | The client/server of the distributed key-value store. [^2]| - - - -[^1]: Is included in repositories for RHEL 8 / CentOS 8 operating systems -[^2]: Are included in repositories for Debian 12 operating system +| `python3-python-etcd` | A Python client for etcd. | diff --git a/docs/solutions.md b/docs/solutions.md new file mode 100644 index 000000000..dcaa787df --- /dev/null +++ b/docs/solutions.md @@ -0,0 +1,30 @@ +# Percona Distribution for PostgreSQL solutions + +Find the right solution to help you achieve your organization's goals. + +
+ +### :material-clock-check-outline: High availability + +Check out how you can ensure continuous access to your database. + +[High availability :material-arrow-right:](solutions/high-availability.md){.md-button} + +
+ +### :octicons-globe-24: Spatial data handling + +Dealing with spatial data? Learn how you can store and manipulate it. + +[Spatial data handling :material-arrow-right:](solutions/postgis.md){.md-button} + +
+ +### :material-backup-restore: Backup and disaster recovery + +Protect your database against accidental or malicious data loss or data corruption. + +[Backup and disaster recovery :material-arrow-right:](solutions/backup-recovery.md){.md-button} + +
+
\ No newline at end of file diff --git a/docs/solutions/backup-recovery.md b/docs/solutions/backup-recovery.md index 867d25551..92f417c36 100644 --- a/docs/solutions/backup-recovery.md +++ b/docs/solutions/backup-recovery.md @@ -21,9 +21,9 @@ A Disaster Recovery (DR) solution ensures that a system can be quickly restored
PostgreSQL offers multiple options for setting up database disaster recovery. - - **[pg_dump](https://www.postgresql.org/docs/15/app-pgdump.html) or the [pg_dumpall](https://www.postgresql.org/docs/15/app-pg-dumpall.html) utilities** + - **[pg_dump :octicons-link-external-16:](https://www.postgresql.org/docs/15/app-pgdump.html) or the [pg_dumpall :octicons-link-external-16:](https://www.postgresql.org/docs/15/app-pg-dumpall.html) utilities** - This is the basic backup approach. These tools can generate the backup of one or more PostgreSQL databases (either just the structure, or both the structure and data), then restore them through the [pg_restore](https://www.postgresql.org/docs/15/app-pgrestore.html) command. + This is the basic backup approach. These tools can generate the backup of one or more PostgreSQL databases (either just the structure, or both the structure and data), then restore them through the [pg_restore :octicons-link-external-16:](https://www.postgresql.org/docs/15/app-pgrestore.html) command. | Advantages | Disadvantages | | ------------ | --------------- | @@ -37,7 +37,7 @@ A Disaster Recovery (DR) solution ensures that a system can be quickly restored | ------------ | --------------- | | Consistent snapshot of the data directory or the whole data disk volume | 1. Requires stopping PostgreSQL in order to copy the files. This is not practical for most production setups.
2. No backup of individual databases or tables.| - - **PostgreSQL [pg_basebackup](https://www.postgresql.org/docs/15/app-pgbasebackup.html)** + - **PostgreSQL [pg_basebackup :octicons-link-external-16:](https://www.postgresql.org/docs/15/app-pgbasebackup.html)** This backup tool is provided by PostgreSQL. It is used to back up data when the database instance is running. `pgasebackup` makes a binary copy of the database cluster files, while making sure the system is put in and out of backup mode automatically. @@ -52,7 +52,7 @@ This document focuses on the Disaster recovery solution in Percona Distribution ### pgBackRest -[pgBackRest](https://pgbackrest.org/) is an easy-to-use, open-source solution that can reliably back up even the largest of PostgreSQL databases. `pgBackRest` supports the following backup types: +[pgBackRest :octicons-link-external-16:](https://pgbackrest.org/) is an easy-to-use, open-source solution that can reliably back up even the largest of PostgreSQL databases. `pgBackRest` supports the following backup types: * full backup - a complete copy of your entire data set. * differential backup - includes all data that has changed since the last full backup. While this means the backup time is slightly higher, it enables a faster restore. @@ -76,7 +76,7 @@ As the configuration example, we will use a three server architecture where `pgB !!! important - Passwordless SSH may not be an ideal solution for your environment. In this case, consider using other methods, for example, [TLS with client certificates](https://pgbackrest.org/user-guide-rhel.html#repo-host/config). + Passwordless SSH may not be an ideal solution for your environment. In this case, consider using other methods, for example, [TLS with client certificates :octicons-link-external-16:](https://pgbackrest.org/user-guide-rhel.html#repo-host/config). The following diagram illustrates the architecture layout: diff --git a/docs/solutions/dr-pgbackrest-setup.md b/docs/solutions/dr-pgbackrest-setup.md index ce0c619ac..e2aafc0fb 100644 --- a/docs/solutions/dr-pgbackrest-setup.md +++ b/docs/solutions/dr-pgbackrest-setup.md @@ -137,7 +137,7 @@ Before setting up passwordless SSH, ensure that the _postgres_ user in all three Install Percona Distribution for PostgreSQL in the primary and the secondary nodes from Percona repository. -1. [Install `percona-release`](https://www.percona.com/doc/percona-repo-config/installing.html). +1. [Install `percona-release` :octicons-link-external-16:](https://www.percona.com/doc/percona-repo-config/installing.html). 2. Enable the repository: ```{.bash data-promp="$"} diff --git a/docs/solutions/ha-setup-apt.md b/docs/solutions/ha-setup-apt.md index ada695b11..9c0454ff7 100644 --- a/docs/solutions/ha-setup-apt.md +++ b/docs/solutions/ha-setup-apt.md @@ -4,23 +4,23 @@ This guide provides instructions on how to set up a highly available PostgreSQL ## Considerations -1. This is an example deployment where ETCD runs on the same host machines as the Patroni and PostgreSQL and there is a single dedicated HAProxy host. Alternatively ETCD can run on different set of nodes. +1. This is an example deployment where etcd runs on the same host machines as the Patroni and PostgreSQL and there is a single dedicated HAProxy host. Alternatively etcd can run on different set of nodes. - If ETCD is deployed on the same host machine as Patroni and PostgreSQL, separate disk system for ETCD and PostgreSQL is recommended due to performance reasons. + If etcd is deployed on the same host machine as Patroni and PostgreSQL, separate disk system for etcd and PostgreSQL is recommended due to performance reasons. 2. For this setup, we will use the nodes running on Ubuntu 22.04 as the base operating system:: | Node name | Application | IP address |---------------|-------------------|-------------------- - | node1 | Patroni, PostgreSQL, ETCD | 10.104.0.1 - | node2 | Patroni, PostgreSQL, ETCD | 10.104.0.2 - | node3 | Patroni, PostgreSQL, ETCD | 10.104.0.3 + | node1 | Patroni, PostgreSQL, etcd | 10.104.0.1 + | node2 | Patroni, PostgreSQL, etcd | 10.104.0.2 + | node3 | Patroni, PostgreSQL, etcd | 10.104.0.3 | HAProxy-demo | HAProxy | 10.104.0.6 !!! note - We recommend not to expose the hosts/nodes where Patroni / ETCD / PostgreSQL are running to public networks due to security risks. Use Firewalls, Virtual networks, subnets or the like to protect the database hosts from any kind of attack. + We recommend not to expose the hosts/nodes where Patroni / etcd / PostgreSQL are running to public networks due to security risks. Use Firewalls, Virtual networks, subnets or the like to protect the database hosts from any kind of attack. ## Initial setup @@ -82,7 +82,7 @@ Run the following commands on node1`, `node2` and `node3`: 1. Install Percona Distribution for PostgreSQL - * [Install `percona-release`](https://www.percona.com/doc/percona-repo-config/installing.html). + * [Install `percona-release` :octicons-link-external-16:](https://www.percona.com/doc/percona-repo-config/installing.html). * Enable the repository: @@ -91,14 +91,14 @@ Run the following commands on node1`, `node2` and `node3`: ``` * [Install Percona Distribution for PostgreSQL packages](../apt.md). -2. Install some Python and auxiliary packages to help with Patroni and ETCD +2. Install some Python and auxiliary packages to help with Patroni and etcd ``` {.bash data-prompt="$"} $ sudo apt install python3-pip python3-dev binutils ``` -3. Install ETCD, Patroni, pgBackRest packages: +3. Install etcd, Patroni, pgBackRest packages: ```{.bash data-prompt="$"} $ sudo apt install percona-patroni \ @@ -119,22 +119,22 @@ Run the following commands on node1`, `node2` and `node3`: $ sudo rm -rf /var/lib/postgresql/15/main ``` -## Configure ETCD distributed store +## Configure etcd distributed store -The distributed configuration store provides a reliable way to store data that needs to be accessed by large scale distributed systems. The most popular implementation of the distributed configuration store is ETCD. ETCD is deployed as a cluster for fault-tolerance and requires an odd number of members (n/2+1) to agree on updates to the cluster state. An ETCD cluster helps establish a consensus among nodes during a failover and manages the configuration for the three PostgreSQL instances. +The distributed configuration store provides a reliable way to store data that needs to be accessed by large scale distributed systems. The most popular implementation of the distributed configuration store is etcd. etcd is deployed as a cluster for fault-tolerance and requires an odd number of members (n/2+1) to agree on updates to the cluster state. An etcd cluster helps establish a consensus among nodes during a failover and manages the configuration for the three PostgreSQL instances. -This document provides configuration for ETCD version 3.5.x. For how to configure ETCD cluster with earlier versions of ETCD, read the blog post by _Fernando Laudares Camargos_ and _Jobin Augustine_ [PostgreSQL HA with Patroni: Your Turn to Test Failure Scenarios](https://www.percona.com/blog/postgresql-ha-with-patroni-your-turn-to-test-failure-scenarios/) +This document provides configuration for etcd version 3.5.x. For how to configure etcd cluster with earlier versions of etcd, read the blog post by _Fernando Laudares Camargos_ and _Jobin Augustine_ [PostgreSQL HA with Patroni: Your Turn to Test Failure Scenarios](https://www.percona.com/blog/postgresql-ha-with-patroni-your-turn-to-test-failure-scenarios/) The `etcd` cluster is first started in one node and then the subsequent nodes are added to the first node using the `add `command. !!! note - Users with deeper understanding of how ETCD works can configure and start all ETCD nodes at a time and bootstrap the cluster using one of the following methods: + Users with deeper understanding of how etcd works can configure and start all etcd nodes at a time and bootstrap the cluster using one of the following methods: * Static in the case when the IP addresses of the cluster nodes are known * Discovery service - for cases when the IP addresses of the cluster are not known ahead of time. - See the [How to configure ETCD nodes simultaneously](../how-to.md#how-to-configure-etcd-nodes-simultaneously) section for details. + See the [How to configure etcd nodes simultaneously](../how-to.md#how-to-configure-etcd-nodes-simultaneously) section for details. ### Configure `node1` @@ -182,9 +182,9 @@ The `etcd` cluster is first started in one node and then the subsequent nodes ar ```{.text .no-copy} Added member named node2 with ID 10042578c504d052 to cluster - ETCD_NAME="node2" - ETCD_INITIAL_CLUSTER="node2=http://10.104.0.2:2380,node1=http://10.104.0.1:2380" - ETCD_INITIAL_CLUSTER_STATE="existing" + etcd_NAME="node2" + etcd_INITIAL_CLUSTER="node2=http://10.104.0.2:2380,node1=http://10.104.0.1:2380" + etcd_INITIAL_CLUSTER_STATE="existing" ``` ### Configure `node2` diff --git a/docs/solutions/ha-setup-yum.md b/docs/solutions/ha-setup-yum.md index 203a440e4..1d96ee636 100644 --- a/docs/solutions/ha-setup-yum.md +++ b/docs/solutions/ha-setup-yum.md @@ -5,23 +5,23 @@ This guide provides instructions on how to set up a highly available PostgreSQL ## Considerations -1. This is an example deployment where ETCD runs on the same host machines as the Patroni and PostgreSQL and there is a single dedicated HAProxy host. Alternatively ETCD can run on different set of nodes. +1. This is an example deployment where etcd runs on the same host machines as the Patroni and PostgreSQL and there is a single dedicated HAProxy host. Alternatively etcd can run on different set of nodes. - If ETCD is deployed on the same host machine as Patroni and PostgreSQL, separate disk system for ETCD and PostgreSQL is recommended due to performance reasons. + If etcd is deployed on the same host machine as Patroni and PostgreSQL, separate disk system for etcd and PostgreSQL is recommended due to performance reasons. 2. For this setup, we use the nodes running on Red Hat Enterprise Linux 8 as the base operating system: | Node name | Application | IP address |---------------|-------------------|-------------------- - | node1 | Patroni, PostgreSQL, ETCD | 10.104.0.1 - | node2 | Patroni, PostgreSQL, ETCD | 10.104.0.2 - | node3 | Patroni, PostgreSQL, ETCD | 10.104.0.3 + | node1 | Patroni, PostgreSQL, etcd | 10.104.0.1 + | node2 | Patroni, PostgreSQL, etcd | 10.104.0.2 + | node3 | Patroni, PostgreSQL, etcd | 10.104.0.3 | HAProxy-demo | HAProxy | 10.104.0.6 !!! note - We recommend not to expose the hosts/nodes where Patroni / ETCD / PostgreSQL are running to public networks due to security risks. Use Firewalls, Virtual networks, subnets or the like to protect the database hosts from any kind of attack. + We recommend not to expose the hosts/nodes where Patroni / etcd / PostgreSQL are running to public networks due to security risks. Use Firewalls, Virtual networks, subnets or the like to protect the database hosts from any kind of attack. ## Initial setup @@ -80,7 +80,7 @@ It's not necessary to have name resolution, but it makes the whole setup more re 1. Install Percona Distribution for PostgreSQL on `node1`, `node2` and `node3` from Percona repository: - * [Install `percona-release`](https://www.percona.com/doc/percona-repo-config/installing.html). + * [Install `percona-release` :octicons-link-external-16:](https://www.percona.com/doc/percona-repo-config/installing.html). * Enable the repository: ```{.bash data-prompt="$"} @@ -93,13 +93,13 @@ It's not necessary to have name resolution, but it makes the whole setup more re **Don't** initialize the cluster and start the `postgresql` service. The cluster initialization and setup are handled by Patroni during the bootsrapping stage. -2. Install some Python and auxiliary packages to help with Patroni and ETCD +2. Install some Python and auxiliary packages to help with Patroni and etcd ```{.bash data-prompt="$"} $ sudo yum install python3-pip python3-devel binutils ``` -3. Install ETCD, Patroni, pgBackRest packages. Check [platform specific notes for Patroni](../yum.md#for-percona-patroni-package): +3. Install etcd, Patroni, pgBackRest packages. Check [platform specific notes for Patroni](../yum.md#for-percona-patroni-package): ```{.bash data-prompt="$"} $ sudo yum install percona-patroni \ @@ -114,22 +114,22 @@ It's not necessary to have name resolution, but it makes the whole setup more re $ systemctl disable {etcd,patroni,postgresql} ``` -## Configure ETCD distributed store +## Configure etcd distributed store -The distributed configuration store provides a reliable way to store data that needs to be accessed by large scale distributed systems. The most popular implementation of the distributed configuration store is ETCD. ETCD is deployed as a cluster for fault-tolerance and requires an odd number of members (n/2+1) to agree on updates to the cluster state. An ETCD cluster helps establish a consensus among nodes during a failover and manages the configuration for the three PostgreSQL instances. +The distributed configuration store provides a reliable way to store data that needs to be accessed by large scale distributed systems. The most popular implementation of the distributed configuration store is etcd. etcd is deployed as a cluster for fault-tolerance and requires an odd number of members (n/2+1) to agree on updates to the cluster state. An etcd cluster helps establish a consensus among nodes during a failover and manages the configuration for the three PostgreSQL instances. -This document provides configuration for ETCD version 3.5.x. For how to configure ETCD cluster with earlier versions of ETCD, read the blog post by _Fernando Laudares Camargos_ and _Jobin Augustine_ [PostgreSQL HA with Patroni: Your Turn to Test Failure Scenarios](https://www.percona.com/blog/postgresql-ha-with-patroni-your-turn-to-test-failure-scenarios/) +This document provides configuration for etcd version 3.5.x. For how to configure etcd cluster with earlier versions of etcd, read the blog post by _Fernando Laudares Camargos_ and _Jobin Augustine_ [PostgreSQL HA with Patroni: Your Turn to Test Failure Scenarios](https://www.percona.com/blog/postgresql-ha-with-patroni-your-turn-to-test-failure-scenarios/) The `etcd` cluster is first started in one node and then the subsequent nodes are added to the first node using the `add `command. !!! note - Users with deeper understanding of how ETCD works can configure and start all ETCD nodes at a time and bootstrap the cluster using one of the following methods: + Users with deeper understanding of how etcd works can configure and start all etcd nodes at a time and bootstrap the cluster using one of the following methods: * Static in the case when the IP addresses of the cluster nodes are known * Discovery service - for cases when the IP addresses of the cluster are not known ahead of time. - See the [How to configure ETCD nodes simultaneously](../how-to.md#how-to-configure-etcd-nodes-simultaneously) section for details. + See the [How to configure etcd nodes simultaneously](../how-to.md#how-to-configure-etcd-nodes-simultaneously) section for details. ### Configure `node1` @@ -177,9 +177,9 @@ The `etcd` cluster is first started in one node and then the subsequent nodes ar ```{.text .no-copy} Added member named node2 with ID 10042578c504d052 to cluster - ETCD_NAME="node2" - ETCD_INITIAL_CLUSTER="node2=http://10.104.0.2:2380,node1=http://10.104.0.1:2380" - ETCD_INITIAL_CLUSTER_STATE="existing" + etcd_NAME="node2" + etcd_INITIAL_CLUSTER="node2=http://10.104.0.2:2380,node1=http://10.104.0.1:2380" + etcd_INITIAL_CLUSTER_STATE="existing" ``` ### Configure `node2` diff --git a/docs/solutions/high-availability.md b/docs/solutions/high-availability.md index 1510e8f30..e9bdfeddf 100644 --- a/docs/solutions/high-availability.md +++ b/docs/solutions/high-availability.md @@ -1,6 +1,6 @@ # High Availability in PostgreSQL with Patroni -PostgreSQL has been widely adopted as a modern, high-performance transactional database. A highly available PostgreSQL cluster can withstand failures caused by network outages, resource saturation, hardware failures, operating system crashes or unexpected reboots. Such cluster is often a critical component of the enterprise application landscape, where [four nines of availability](https://en.wikipedia.org/wiki/High_availability#Percentage_calculation) is a minimum requirement. +PostgreSQL has been widely adopted as a modern, high-performance transactional database. A highly available PostgreSQL cluster can withstand failures caused by network outages, resource saturation, hardware failures, operating system crashes or unexpected reboots. Such cluster is often a critical component of the enterprise application landscape, where [four nines of availability :octicons-link-external-16:](https://en.wikipedia.org/wiki/High_availability#Percentage_calculation) is a minimum requirement. There are several methods to achieve high availability in PostgreSQL. This solution document provides [Patroni](#patroni) - the open-source extension to facilitate and manage the deployment of high availability in PostgreSQL. @@ -34,11 +34,11 @@ There are several methods to achieve high availability in PostgreSQL. This solut To address these shortcomings, there are a multitude of third-party, open-source extensions for PostgreSQL. The challenge for a database administrator here is to select the right utility for the current scenario. - Percona Distribution for PostgreSQL solves this challenge by providing the [Patroni](https://patroni.readthedocs.io/en/latest/) extension for achieving PostgreSQL high availability. + Percona Distribution for PostgreSQL solves this challenge by providing the [Patroni :octicons-link-external-16:](https://patroni.readthedocs.io/en/latest/) extension for achieving PostgreSQL high availability. ## Patroni -[Patroni](https://patroni.readthedocs.io/en/latest/) is a template for you to create your own customized, high-availability solution using Python and - for maximum accessibility - a distributed configuration store like ZooKeeper, etcd, Consul or Kubernetes. +[Patroni :octicons-link-external-16:](https://patroni.readthedocs.io/en/latest/) is a template for you to create your own customized, high-availability solution using Python and - for maximum accessibility - a distributed configuration store like ZooKeeper, etcd, Consul or Kubernetes. ### Key benefits of Patroni: @@ -63,7 +63,7 @@ The components in this architecture are: - PostgreSQL nodes - Patroni - a template for configuring a highly available PostgreSQL cluster. -- ETCD - a Distributed Configuration store that stores the state of the PostgreSQL cluster. +- etcd - a Distributed Configuration store that stores the state of the PostgreSQL cluster. - HAProxy - the load balancer for the cluster and is the single point of entry to client applications. @@ -73,9 +73,9 @@ The components in this architecture are: ### How components work together -Each PostgreSQL instance in the cluster maintains consistency with other members through streaming replication. Each instance hosts Patroni - a cluster manager that monitors the cluster health. Patroni relies on the operational ETCD cluster to store the cluster configuration and sensitive data about the cluster health there. +Each PostgreSQL instance in the cluster maintains consistency with other members through streaming replication. Each instance hosts Patroni - a cluster manager that monitors the cluster health. Patroni relies on the operational etcd cluster to store the cluster configuration and sensitive data about the cluster health there. -Patroni periodically sends heartbeat requests with the cluster status to ETCD. ETCD writes this information to disk and sends the response back to Patroni. If the current primary fails to renew its status as leader within the specified timeout, Patroni updates the state change in ETCD, which uses this information to elect the new primary and keep the cluster up and running. +Patroni periodically sends heartbeat requests with the cluster status to etcd. etcd writes this information to disk and sends the response back to Patroni. If the current primary fails to renew its status as leader within the specified timeout, Patroni updates the state change in etcd, which uses this information to elect the new primary and keep the cluster up and running. The connections to the cluster do not happen directly to the database nodes but are routed via a connection proxy like HAProxy. This proxy determines the active node by querying the Patroni REST API. diff --git a/docs/solutions/index.md b/docs/solutions/index.md new file mode 100644 index 000000000..9165b378f --- /dev/null +++ b/docs/solutions/index.md @@ -0,0 +1,7 @@ +# Percona Distribution for PostgreSQL solutions + +Explore the following reference architectures to enhance your PostgreSQL experience: + +* [High-availability of PostgreSQL cluster with Patroni ](high-availability.md) +* [Backup and disaster recovery](pgbackrest.md) +* [Spatial data handling with PostGIS](postgis.md) \ No newline at end of file diff --git a/docs/solutions/pgbackrest.md b/docs/solutions/pgbackrest.md index 7e550d3c1..3feb1b862 100644 --- a/docs/solutions/pgbackrest.md +++ b/docs/solutions/pgbackrest.md @@ -1,6 +1,6 @@ # pgBackRest setup -[pgBackRest](https://pgbackrest.org/) is a backup tool used to perform PostgreSQL database backup, archiving, restoration, and point-in-time recovery. While it can be used for local backups, this procedure shows how to deploy a [pgBackRest server running on a dedicated host](https://pgbackrest.org/user-guide-rhel.html#repo-host) and how to configure PostgreSQL servers to use it for backups and archiving. +[pgBackRest :octicons-link-external-16:](https://pgbackrest.org/) is a backup tool used to perform PostgreSQL database backup, archiving, restoration, and point-in-time recovery. While it can be used for local backups, this procedure shows how to deploy a [pgBackRest server running on a dedicated host :octicons-link-external-16:](https://pgbackrest.org/user-guide-rhel.html#repo-host) and how to configure PostgreSQL servers to use it for backups and archiving. You also need a backup storage to store the backups. It can either be a remote storage such as AWS S3, S3-compatible storages or Azure blob storage, or a filesystem-based one. @@ -14,7 +14,7 @@ $ sudo su - ### Install pgBackRest -1. Enable the repository with [percona-release](https://www.percona.com/doc/percona-repo-config/index.html) +1. Enable the repository with [percona-release :octicons-link-external-16:](https://www.percona.com/doc/percona-repo-config/index.html) ```{.bash data-prompt="$"} $ percona-release setup ppg-{{pgversion}} diff --git a/docs/solutions/postgis-deploy.md b/docs/solutions/postgis-deploy.md index 546e19540..e54703e94 100644 --- a/docs/solutions/postgis-deploy.md +++ b/docs/solutions/postgis-deploy.md @@ -5,7 +5,7 @@ The following document provides guidelines how to install PostGIS and how to run ## Considerations 1. We assume that you have the basic knowledge of spatial data, GIS (Geographical Information System) and of shapefiles. -2. For uploading the spatial data and querying the database, we use the same [data set](https://s3.amazonaws.com/s3.cleverelephant.ca/postgis-workshop-2020.zip) as is used in [PostGIS tutorial](http://postgis.net/workshops/postgis-intro/). +2. For uploading the spatial data and querying the database, we use the same [data set :octicons-link-external-16:](https://s3.amazonaws.com/s3.cleverelephant.ca/postgis-workshop-2020.zip) as is used in [PostGIS tutorial :octicons-link-external-16:](http://postgis.net/workshops/postgis-intro/). ## Install PostGIS @@ -14,7 +14,7 @@ The following document provides guidelines how to install PostGIS and how to run 1. Enable Percona repository - As other components of Percona Distribution for PostgreSQL, PostGIS is available from Percona repositories. Use the [`percona-release`](https://docs.percona.com/percona-software-repositories/installing.html) repository management tool to enable the repository. + As other components of Percona Distribution for PostgreSQL, PostGIS is available from Percona repositories. Use the [`percona-release` :octicons-link-external-16:](https://docs.percona.com/percona-software-repositories/installing.html) repository management tool to enable the repository. ```{.bash data-prompt="$"} $ sudo percona-release setup ppg{{pgversion}} @@ -47,7 +47,7 @@ The following document provides guidelines how to install PostGIS and how to run 2. Enable Percona repository - As other components of Percona Distribution for PostgreSQL, PostGIS is available from Percona repositories. Use the [`percona-release`](https://docs.percona.com/percona-software-repositories/installing.html) repository management tool to enable the repository. + As other components of Percona Distribution for PostgreSQL, PostGIS is available from Percona repositories. Use the [`percona-release` :octicons-link-external-16:](https://docs.percona.com/percona-software-repositories/installing.html) repository management tool to enable the repository. ```{.bash data-prompt="$"} $ sudo percona-release setup ppg{{pgversion}} @@ -122,7 +122,7 @@ PostGIS provides the `shp2pgsql` command line utility that converts the binary d * `-D` flag instructs the command to generate the dump format * `-I` flag instructs to create the spatial index on the table upon the data load - * `-s` indicates the [spatial reference identifier](https://en.wikipedia.org/wiki/Spatial_reference_system) of the data. The data we load is in the Projected coordinate system for North America and has the value 26918. + * `-s` indicates the [spatial reference identifier :octicons-link-external-16:](https://en.wikipedia.org/wiki/Spatial_reference_system) of the data. The data we load is in the Projected coordinate system for North America and has the value 26918. * `nyc_streets.shp` is the source shapefile * `nyc_streets` is the table name to create in the database * `dbname=nyc` is the database name diff --git a/docs/solutions/postgis-upgrade.md b/docs/solutions/postgis-upgrade.md index 37ba522da..0c0c47766 100644 --- a/docs/solutions/postgis-upgrade.md +++ b/docs/solutions/postgis-upgrade.md @@ -13,13 +13,13 @@ The spatial database upgrade consists of two steps: ## Upgrade PostGIS -Each version of PostGIS is compatible with several versions of PostgreSQL and vise versa. The best practice is to first upgrade the PostGIS extension on the source cluster to match the compatible version on the target cluster and then upgrade PostgreSQL. Please see the [PostGIS Support matrix](https://trac.osgeo.org/postgis/wiki/UsersWikiPostgreSQLPostGIS#PostGISSupportMatrix) for version compatibility. +Each version of PostGIS is compatible with several versions of PostgreSQL and vise versa. The best practice is to first upgrade the PostGIS extension on the source cluster to match the compatible version on the target cluster and then upgrade PostgreSQL. Please see the [PostGIS Support matrix :octicons-link-external-16:](https://trac.osgeo.org/postgis/wiki/UsersWikiPostgreSQLPostGIS#PostGISSupportMatrix) for version compatibility. PostGIS is enabled on the database level. This means that the upgrade is also done on the database level. === "PostGIS 3 and above" - Connect to the database where it is enabled and run the [`PostGIS_Extensions_Upgrade()`](https://postgis.net/docs/PostGIS_Extensions_Upgrade.html) function: + Connect to the database where it is enabled and run the [`PostGIS_Extensions_Upgrade()` :octicons-link-external-16:](https://postgis.net/docs/PostGIS_Extensions_Upgrade.html) function: ```sql SELECT postgis_extensions_upgrade(); @@ -50,4 +50,4 @@ PostGIS is enabled on the database level. This means that the upgrade is also do Upgrade PostgreSQL either to the [latest minor](../minor-upgrade.md) or to the [major version](../major-upgrade.md). -If you are using long deprecated views and functions and / or need the expertise in upgrading your spatial database, [contact Percona Managed Services](https://www.percona.com/services/managed-services) for an individual upgrade scenario development. +If you are using long deprecated views and functions and / or need the expertise in upgrading your spatial database, [contact Percona Managed Services :octicons-link-external-16:](https://www.percona.com/services/managed-services) for an individual upgrade scenario development. diff --git a/docs/solutions/postgis.md b/docs/solutions/postgis.md index 19c94073b..35a8ed6cd 100644 --- a/docs/solutions/postgis.md +++ b/docs/solutions/postgis.md @@ -7,7 +7,7 @@ Organizations dealing with spatial data need to store it somewhere and manipulat * Geographical data like points, lines, polygons, GPS coordinates that can be mapped on a sphere. * Geometrical data. This is also points, lines and polygons but they apply to a 2D surface. -To operate with spatial data inside SQL queries, PostGIS supports [spatial functions](https://postgis.net/docs/reference.html#SRS_Functions) like distance, area, union, intersection. It uses the spatial indexes like [R-Tree](https://en.wikipedia.org/wiki/R-tree) and [Quadtree](https://en.wikipedia.org/wiki/Quadtree) for efficient processing of database operations. Read more about supported spatial functions and indexes in [PostGIS documentation](https://postgis.net/workshops/postgis-intro/introduction.html). +To operate with spatial data inside SQL queries, PostGIS supports [spatial functions :octicons-link-external-16:](https://postgis.net/docs/reference.html#SRS_Functions) like distance, area, union, intersection. It uses the spatial indexes like [R-Tree :octicons-link-external-16:](https://en.wikipedia.org/wiki/R-tree) and [Quadtree :octicons-link-external-16:](https://en.wikipedia.org/wiki/Quadtree) for efficient processing of database operations. Read more about supported spatial functions and indexes in [PostGIS documentation :octicons-link-external-16:](https://postgis.net/workshops/postgis-intro/introduction.html). By deploying PostGIS with Percona Distribution for PostgreSQL, you receive the open-source spatial database that you can use in various areas without vendor lock-in. @@ -24,7 +24,7 @@ You can use PostGIS in the following cases: Despite its power and flexibility, PostGIS may not suit your needs if: -* You need to store only a couple of map locations. Consider using the [built-in geometric functions and operations of PostgreSQL](https://www.postgresql.org/docs/current/functions-geometry.html) +* You need to store only a couple of map locations. Consider using the [built-in geometric functions and operations of PostgreSQL :octicons-link-external-16:](https://www.postgresql.org/docs/current/functions-geometry.html) * You need real-time data analysis. While PostGIS can handle real-time spatial data, it may not be the best option for real-time data analysis on large volumes of data. * You need complex 3D analysis or visualization. * You need to acquire spatial data. Use other tools for this purpose and import spatial data into PostGIS to manipulate it. diff --git a/docs/third-party.md b/docs/third-party.md index bd8f29ceb..b9e3253af 100644 --- a/docs/third-party.md +++ b/docs/third-party.md @@ -5,6 +5,7 @@ Percona Distribution for PostgreSQL is supplied with the set of third-party open | Name | Superuser privileges | Description | |------|---------------------|-------------| +| [etcd](https://etcd.io/)| Required | A distributed, reliable key-value store for setting up high available Patroni clusters | | [HAProxy](http://www.haproxy.org/) | Required | A high-availability and load-balancing solution | | [Patroni](https://patroni.readthedocs.io/en/latest/) | Required | An HA (High Availability) solution for PostgreSQL | | [pgAudit](https://www.pgaudit.org/) | Required | Provides detailed session or object audit logging via the standard PostgreSQL logging facility | diff --git a/docs/trademark-policy.md b/docs/trademark-policy.md index 071dad339..94ff02088 100644 --- a/docs/trademark-policy.md +++ b/docs/trademark-policy.md @@ -1,6 +1,6 @@ # Trademark Policy -This [Trademark Policy](https://www.percona.com/trademark-policy) is to ensure that users of Percona-branded products or +This [Trademark Policy :octicons-link-external-16:](https://www.percona.com/trademark-policy) is to ensure that users of Percona-branded products or services know that what they receive has really been developed, approved, tested and maintained by Percona. Trademarks help to prevent confusion in the marketplace, by distinguishing one company’s or person’s products and services diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 000000000..136737ff9 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,23 @@ +# Troubleshooting guide + +## Cannot create a table. Permission denied in schema `public` + +Every database in PostgreSQL has a default schema called `public`. A schema stores database objects like tables, views, indexes and allows organizing them into logical groups. + +When you create a table without specifying a schema name, it ends up in the `public` schema by default. + +Starting with PostgreSQL 15, non-database owners cannot access the `public` schema. Therefore, you can either grant privileges to the database for your user using the [GRANT](https://www.postgresql.org/docs/{{pgvesrion}}/sql-grant.html) command or create your own schema to insert the data. + +To create a schema, use the following statement: + +```sql +CREATE SCHEMA demo; +``` + +To ensure all tables end up in your newly created schema, use the following statement ot set the schema: + +```sql +CREATE SCHEMA demo; +``` + +Replace the `demo` name with your value. diff --git a/docs/uninstalling.md b/docs/uninstalling.md index 19f8e0bc1..90b60f222 100644 --- a/docs/uninstalling.md +++ b/docs/uninstalling.md @@ -10,6 +10,7 @@ To uninstall Percona Distribution for PostgreSQL, remove all the installed packa or Ubuntu, complete the following steps. Run all commands as root or via **sudo**. + {.power-number} 1. Stop the Percona Distribution for PostgreSQL service. @@ -38,6 +39,7 @@ To uninstall Percona Distribution for PostgreSQL, remove all the installed packa Red Hat Enterprise Linux or CentOS, complete the following steps. Run all commands as root or via **sudo**. + {.power-number} 1. Stop the Percona Distribution for PostgreSQL service. diff --git a/docs/whats-next.md b/docs/whats-next.md new file mode 100644 index 000000000..3d18085a7 --- /dev/null +++ b/docs/whats-next.md @@ -0,0 +1,25 @@ +# What's next? + +You've just had your first hands-on experience with PostgreSQL! That's a great start. + +To become more confident and proficient in developing database applications, let's expand your knowledge and skills in using PostgreSQL. Dive deeper into these key topics to solidify your PostgreSQL skills: + +- [SQL Syntax :octicons-link-external-16:](https://www.postgresql.org/docs/current/sql-syntax.html) +- [Data definition :octicons-link-external-16:](https://www.postgresql.org/docs/current/ddl.html) +- [Queries :octicons-link-external-16:](https://www.postgresql.org/docs/current/queries.html) +- [Functions and Operators :octicons-link-external-16:](https://www.postgresql.org/docs/current/functions.html) +- [Indexes :octicons-link-external-16:](https://www.postgresql.org/docs/current/indexes.html) + + +To effectively solve database administration tasks, master these essential topics: + +- [Backup and restore :octicons-link-external-16:](https://www.postgresql.org/docs/current/backup.html) +- [Authentication :octicons-link-external-16:](https://www.postgresql.org/docs/{{pgversion}}/auth-methods.html) and role-based access control +- [PostgreSQL contrib extensions and modules](contrib.md) +- [Monitor PostgreSQL with Percona Monitoring and Management :octicons-link-external-16:](https://docs.percona.com/percona-monitoring-and-management/quickstart/index.html) + + +Also, check out our solutions to help you meet the requirements of your organization. + +[Solutions](solutions.md){.md-button} + diff --git a/docs/yum.md b/docs/yum.md index 54211cbef..0f0596ea6 100644 --- a/docs/yum.md +++ b/docs/yum.md @@ -1,6 +1,6 @@ # Install Percona Distribution for PostgreSQL on Red Hat Enterprise Linux and derivatives -This document describes how to install Percona Distribution for PostgreSQL from Percona repositories on RPM-based distributions such as Red Hat Enterprise Linux and compatible derivatives. [Read more about Percona repositories :material-arrow-top-right:](repo-overview.md). +This document describes how to install Percona Distribution for PostgreSQL from Percona repositories on RPM-based distributions such as Red Hat Enterprise Linux and compatible derivatives. [Read more about Percona repositories](repo-overview.md). ## Platform specific notes @@ -101,7 +101,10 @@ The following are commands for Red Hat Enterprise Linux 9 and derivatives. For R For Red Hat Enterprise Linux 8 and derivatives, replace the operating system version in the following commands accordingly. -=== "RHEL 9" +=== "RHEL 9" + + Run the following commands: + {.power-number} 1. Install `epel` repository @@ -123,6 +126,9 @@ For Red Hat Enterprise Linux 8 and derivatives, replace the operating system ver === "Rocky Linux 9" + Run the following commands: + {.power-number} + 1. Install `epel` repository ```{.bash data-prompt="$"} @@ -144,6 +150,9 @@ For Red Hat Enterprise Linux 8 and derivatives, replace the operating system ver === "Oracle Linux 9" + Run the following commands: + {.power-number} + 1. Install `epel` repository ```{.bash data-prompt="$"} @@ -164,6 +173,9 @@ For Red Hat Enterprise Linux 8 and derivatives, replace the operating system ver === "RHEL UBI 9" + Run the following commands: + {.power-number} + 1. Configure the Oracle-Linux repository. Create the `/etc/yum.repos.d/oracle-linux-ol9.repo` file to install the required dependencies: ```init title="/etc/yum.repos.d/oracle-linux-ol9.repo" @@ -213,7 +225,7 @@ Install `curl` for [Telemetry](telemetry.md). We use it to better understand the $ sudo yum -y install curl ``` -### Configure the repository +### Configure the repository {.power-number} 1. Install the `percona-release` repository management tool to subscribe to Percona repositories: @@ -240,6 +252,9 @@ $ sudo yum -y install curl ``` === "Install packages individually" + + Run the following commands: + {.power-number} 1. Install the PostgreSQL server package: @@ -343,31 +358,10 @@ Start the PostgreSQL service: $ sudo systemctl start postgresql-{{pgversion}} ``` -### Connect to the PostgreSQL server - -By default, `postgres` user and `postgres` database are created in PostgreSQL upon its installation and initialization. This allows you to connect to the database as the `postgres` user. +Congratulations! Your Percona Distribution for PostgreSQL is up and running. -```{.bash data-prompt="$"} -$ sudo su postgres -``` - -Open the PostgreSQL interactive terminal: +## Next steps -```{.bash data-prompt="$"} -$ psql -``` - -!!! hint - - You can connect to `psql` as the `postgres` user in one go: - - ```{.bash data-prompt="$"} - $ sudo su - postgres -c psql - ``` - -To exit the `psql` terminal, use the following command: - -```{.bash data-prompt="$"} -$ \q -``` +[Enable extensions :material-arrow-right:](enable-extensions.md){.md-button} +[Connect to PostgreSQL :material-arrow-right:](connect.md){.md-button} diff --git a/mkdocs-base.yml b/mkdocs-base.yml index 2f83dec98..622a79f52 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -152,38 +152,25 @@ extra: nav: - 'Home': 'index.md' - - Release Notes: - - "Release notes index": "release-notes.md" - - release-notes-v15.7.md - - release-notes-v15.6.md - - release-notes-v15.5.upd.md - - 2023 (versions 15.2 - 15.5): - - release-notes-v15.5.md - - release-notes-v15.4.md - - release-notes-v15.3.md - - release-notes-v15.2.upd.md - - release-notes-v15.2.md - - 2022 (versions 15.0 - 15.1): - - release-notes-v15.1.md - - release-notes-v15.0.md - - Installation and Upgrade: - - Install Percona Distribution for PostgreSQL: - - "Overview": "installing.md" - - "Install via apt": "apt.md" - - "Install via yum": "yum.md" - - enable-extensions.md - - repo-overview.md - - "Run in Docker": docker.md - - migration.md - - major-upgrade.md - - minor-upgrade.md + - Get started: + - Quickstart guide: installing.md + - 1. Install: + - Via apt: apt.md + - Via yum: yum.md + - Run in Docker: docker.md + - enable-extensions.md + - repo-overview.md + - 2. Connect to PostgreSQL: connect.md + - 3. Manipulate data in PostgreSQL: crud.md + - 4. What's next: whats-next.md - Extensions: - 'Extensions': extensions.md - contrib.md - - third-party.md - Percona-authored extensions: - 'pg_stat_monitor': 'pg-stat-monitor.md' + - third-party.md - Solutions: + - Overview: solutions.md - High availability: - 'High availability': 'solutions/high-availability.md' - 'Deploying on Debian or Ubuntu': 'solutions/ha-setup-apt.md' @@ -200,10 +187,28 @@ nav: - Upgrade spatial database: solutions/postgis-upgrade.md - LDAP authentication: - ldap.md - - Telemetry: telemetry.md - - How to: how-to.md + - Upgrade: + - "Major upgrade": major-upgrade.md + - minor-upgrade.md + - migration.md + - Troubleshooting guide: troubleshooting.md - Uninstall: uninstalling.md - - Licensing: licensing.md - - Trademark policy: - - trademark-policy.md + - Release Notes: + - "Release notes index": "release-notes.md" + - release-notes-v15.7.md + - release-notes-v15.6.md + - release-notes-v15.5.upd.md + - 2023 (versions 15.2 - 15.5): + - release-notes-v15.5.md + - release-notes-v15.4.md + - release-notes-v15.3.md + - release-notes-v15.2.upd.md + - release-notes-v15.2.md + - 2022 (versions 15.0 - 15.1): + - release-notes-v15.1.md + - release-notes-v15.0.md + - Reference: + - Telemetry: telemetry.md + - Licensing: licensing.md + - Trademark policy: trademark-policy.md diff --git a/snippets/supported-versions.md b/snippets/supported-versions.md index 78a2a1077..ee4c65856 100644 --- a/snippets/supported-versions.md +++ b/snippets/supported-versions.md @@ -1 +1 @@ -Percona provides installation packages in `DEB` and `RPM` format for 64-bit Linux distributions. Find the full list of supported platforms on the [Percona Software and Platform Lifecycle page](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. Find the full list of supported platforms on the [Percona Software and Platform Lifecycle page :octicons-link-external-16:](https://www.percona.com/services/policies/percona-software-support-lifecycle#pgsql).