Update documentation for Citus 13 (#1132)

Author: mulander

admin_guide/upgrading_citus.rst

@@ -13,21 +13,21 @@ Upgrading the Citus version requires first obtaining the new Citus extension and
 Patch Version Upgrade
 ---------------------
 
-To upgrade a Citus version to its latest patch, issue a standard upgrade command for your package manager. Assuming version 12.1 is currently installed on Postgres 16:
+To upgrade a Citus version to its latest patch, issue a standard upgrade command for your package manager. Assuming version 13.0 is currently installed on Postgres 16:
 
 **Ubuntu or Debian**
 
 .. code-block:: bash
 
   sudo apt-get update
-  sudo apt-get install --only-upgrade postgresql-16-citus-12.1
+  sudo apt-get install --only-upgrade postgresql-16-citus-13.0
   sudo service postgresql restart
 
-**Fedora, CentOS, or Red Hat**
+**Red Hat**
 
 .. code-block:: bash
 
-  sudo yum update citus121_16
+  sudo yum update citus130_16
   sudo service postgresql-16 restart
 
 .. _major_minor_upgrade:
@@ -46,23 +46,23 @@ Each major and minor version of Citus is published as a package with a separate
 Step 1. Update Citus Package
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If upgrading both Citus and Postgres, always be sure to upgrade the Citus extension first, and the PostgreSQL version second (see :ref:`upgrading_postgres`). Here is how to do a Citus upgrade from 11.3 to 12.1 on Postgres 15:
+If upgrading both Citus and Postgres, always be sure to upgrade the Citus extension first, and the PostgreSQL version second (see :ref:`upgrading_postgres`). Here is how to do a Citus upgrade from 12.1 to 13.0 on Postgres 16:
 
 **Ubuntu or Debian**
 
 .. code-block:: bash
 
   sudo apt-get update
-  sudo apt-get install postgresql-15-citus-12.1
+  sudo apt-get install postgresql-16-citus-13.0
   sudo service postgresql restart
 
-**Fedora, CentOS, or Red Hat**
+**Red Hat**
 
 .. code-block:: bash
 
   # Fedora, CentOS, or Red Hat
-  sudo yum swap citus113_15 citus121_15
-  sudo service postgresql-15 restart
+  sudo yum swap citus121_16 citus130_16
+  sudo service postgresql-16 restart
 
 Step 2. Apply Update in DB
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -102,7 +102,7 @@ After installing the new package and restarting the database, run the extension
 
 .. _upgrading_postgres:
 
-Upgrading PostgreSQL version from 15 to 16
+Upgrading PostgreSQL version from 16 to 17
 ##########################################
 
 .. note::
@@ -114,17 +114,17 @@ Upgrading PostgreSQL version from 15 to 16
 
 Record the following paths before you start (your actual paths may be different than those below):
 
-Existing data directory (e.g. /opt/pgsql/15/data)
-  :code:`export OLD_PG_DATA=/opt/pgsql/15/data`
+Existing data directory (e.g. /opt/pgsql/16/data)
+  :code:`export OLD_PG_DATA=/opt/pgsql/16/data`
 
-Existing PostgreSQL installation path (e.g. /usr/pgsql-15)
-  :code:`export OLD_PG_PATH=/usr/pgsql-15`
+Existing PostgreSQL installation path (e.g. /usr/pgsql-16)
+  :code:`export OLD_PG_PATH=/usr/pgsql-16`
 
 New data directory after upgrade
-  :code:`export NEW_PG_DATA=/opt/pgsql/16/data`
+  :code:`export NEW_PG_DATA=/opt/pgsql/17/data`
 
 New PostgreSQL installation path
-  :code:`export NEW_PG_PATH=/usr/pgsql-16`
+  :code:`export NEW_PG_PATH=/usr/pgsql-17`
 
 For Every Node
 --------------

conf.py

@@ -58,9 +58,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '12.1'
+version = '13.0'
 # The full version, including alpha/beta/rc tags.
-release = '12.1'
+release = '13.0.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

develop/api_guc.rst

@@ -116,7 +116,6 @@ The ``citus.node_conninfo`` GUC sets non-sensitive `libpq connection parameters
 
 Citus honors only a specific subset of the allowed options, namely:
 
-* application_name
 * connect_timeout
 * gsslib†
 * host
@@ -128,6 +127,7 @@ Citus honors only a specific subset of the allowed options, namely:
 * sslcompression
 * sslcrl
 * sslmode  (defaults to "require" as of Citus 8.1)
+* sslnegotiation
 * sslrootcert
 * tcp_user_timeout
 

index.rst

@@ -1,7 +1,7 @@
 Citus Documentation
 ===================
 
-Welcome to the documentation for Citus 12.1! Citus is an open source extension
+Welcome to the documentation for Citus 13.0! Citus is an open source extension
 to PostgreSQL that transforms Postgres into a distributed database. To scale
 out Postgres horizontally, Citus employs distributed tables, reference tables,
 and a distributed SQL query engine. The query engine parallelizes SQL queries

installation/citus_cloud.rst

@@ -9,6 +9,7 @@ the cloud on Azure. The Citus managed service is available as
 <https://learn.microsoft.com/azure/cosmos-db/postgresql/introduction/>`_, formerly known as Hyperscale (Citus) in Azure Database for PostgreSQL.
 
 To get started with Citus on Azure, you can take advantage of our `quickstart for Azure Cosmos DB for PostgreSQL
-<https://learn.microsoft.com/azure/cosmos-db/postgresql/quickstart-create-portal>`_ in the Azure docs,
-or go straight to the `free trial <https://cosmos.azure.com/try/>`_ on Azure.)
+<https://learn.microsoft.com/azure/cosmos-db/postgresql/quickstart-create-portal>`_ in the Azure docs.
 
+Citus is also now in preview on Flexible server. Learn more on `Postgres horizontal scaling with elastic clusters on Azure Database for PostgreSQL Flexible server
+<https://techcommunity.microsoft.com/blog/adforpostgresql/postgres-horizontal-scaling-with-elastic-clusters-on-azure-database-for-postgres/4303508>`_

installation/multi_node_debian.rst

@@ -26,12 +26,12 @@ Steps to be executed on all nodes
 ::
 
   # install the server and initialize db
-  sudo apt-get -y install postgresql-16-citus-12.1
+  sudo apt-get -y install postgresql-17-citus-13.0
 
   # preload citus extension
-  sudo pg_conftool 16 main set shared_preload_libraries citus
+  sudo pg_conftool 17 main set shared_preload_libraries citus
 
-This installs centralized configuration in `/etc/postgresql/16/main`, and creates a database in `/var/lib/postgresql/16/main`.
+This installs centralized configuration in `/etc/postgresql/17/main`, and creates a database in `/var/lib/postgresql/17/main`.
 
 .. _post_enterprise_deb:
 
@@ -41,11 +41,11 @@ Before starting the database let's change its access permissions. By default the
 
 ::
 
-  sudo pg_conftool 16 main set listen_addresses '*'
+  sudo pg_conftool 17 main set listen_addresses '*'
 
 ::
 
-  sudo vi /etc/postgresql/16/main/pg_hba.conf
+  sudo vi /etc/postgresql/17/main/pg_hba.conf
 
 ::
 

installation/multi_node_rhel.rst

@@ -26,13 +26,13 @@ Steps to be executed on all nodes
 ::
 
   # install PostgreSQL with Citus extension
-  sudo yum install -y citus121_16
+  sudo yum install -y citus130_17
   # initialize system database
-  sudo /usr/pgsql-16/bin/postgresql-16-setup initdb
+  sudo /usr/pgsql-17/bin/postgresql-17-setup initdb
   # preload citus extension
-  echo "shared_preload_libraries = 'citus'" | sudo tee -a /var/lib/pgsql/16/data/postgresql.conf
+  echo "shared_preload_libraries = 'citus'" | sudo tee -a /var/lib/pgsql/17/data/postgresql.conf
 
-PostgreSQL adds version-specific binaries in `/usr/pgsql-16/bin`, but you'll usually just need psql, whose latest version is added to your path, and managing the server itself can be done with the *service* command.
+PostgreSQL adds version-specific binaries in `/usr/pgsql-17/bin`, but you'll usually just need psql, whose latest version is added to your path, and managing the server itself can be done with the *service* command.
 
 .. _post_enterprise_rhel:
 
@@ -42,7 +42,7 @@ Before starting the database let's change its access permissions. By default the
 
 ::
 
-  sudo vi /var/lib/pgsql/16/data/postgresql.conf
+  sudo vi /var/lib/pgsql/17/data/postgresql.conf
 
 ::
 
@@ -51,7 +51,7 @@ Before starting the database let's change its access permissions. By default the
 
 ::
 
-  sudo vi /var/lib/pgsql/16/data/pg_hba.conf
+  sudo vi /var/lib/pgsql/17/data/pg_hba.conf
 
 ::
 
@@ -71,9 +71,9 @@ Before starting the database let's change its access permissions. By default the
 ::
 
   # start the db server
-  sudo service postgresql-16 restart
+  sudo service postgresql-17 restart
   # and make it start automatically when computer does
-  sudo chkconfig postgresql-16 on
+  sudo chkconfig postgresql-17 on
 
 You must add the Citus extension to **every database** you would like to use in a cluster. The following example adds the extension to the default database which is named `postgres`.
 

installation/single_node_debian.rst

@@ -7,15 +7,15 @@ Ubuntu or Debian
 
 This section describes the steps needed to set up a single-node Citus cluster on your own Linux machine from deb packages.
 
-**1. Install PostgreSQL 16 and the Citus extension**
+**1. Install PostgreSQL 17 and the Citus extension**
 
 .. code-block:: sh
 
   # Add Citus repository for package manager
   curl https://install.citusdata.com/community/deb.sh | sudo bash
 
   # install the server and initialize db
-  sudo apt-get -y install postgresql-16-citus-12.1
+  sudo apt-get -y install postgresql-17-citus-13.0
 
 
 .. _post_install:
@@ -30,7 +30,7 @@ Let's create a new database on disk. For convenience in using PostgreSQL Unix do
   sudo su - postgres
 
   # include path to postgres binaries
-  export PATH=$PATH:/usr/lib/postgresql/16/bin
+  export PATH=$PATH:/usr/lib/postgresql/17/bin
 
   cd ~
   mkdir citus

installation/single_node_docker.rst

@@ -14,7 +14,7 @@ You can start Citus in Docker with one command:
 
   # start the image
   docker run -d --name citus -p 5432:5432 -e POSTGRES_PASSWORD=mypass \
-             citusdata/citus:12.1
+             citusdata/citus:13.0
 
   # verify it's running, and that Citus is installed:
   psql -U postgres -h localhost -d postgres -c "SELECT * FROM citus_version();"

installation/single_node_rhel.rst

@@ -7,15 +7,15 @@ Fedora, CentOS, or Red Hat
 
 This section describes the steps needed to set up a single-node Citus cluster on your own Linux machine from RPM packages.
 
-**1. Install PostgreSQL 16 and the Citus extension**
+**1. Install PostgreSQL 17 and the Citus extension**
 
 .. code-block:: sh
 
   # Add Citus repository for package manager
   curl https://install.citusdata.com/community/rpm.sh | sudo bash
 
   # install Citus extension
-  sudo yum install -y citus121_16
+  sudo yum install -y citus130_17
 
 .. _post_install:
 
@@ -29,7 +29,7 @@ Let's create a new database on disk. For convenience in using PostgreSQL Unix do
   sudo su - postgres
 
   # include path to postgres binaries
-  export PATH=$PATH:/usr/pgsql-16/bin
+  export PATH=$PATH:/usr/pgsql-17/bin
 
   cd ~
   mkdir citus