Single node Citus

Docker (Mac and Linux)

DockerImages are for development/test purposes only and are not yet ready for production use.

You can start Citus in Docker with a command:

# start the imageDocker run -d --name citus -p 5432:5432 -e POSTGRES_PASSWORD=mypass \ citusdata/citus:10.2# verify it's running, and that Citus is installed:
psql -U postgres -h localhost -d postgres -c "SELECT * FROM citus_version();"
Copy the code

You should see the latest version of Citus.

Once the cluster is up and running, you can access our tutorials on multi-tenant applications or real-time analytics and start using Citus in minutes.

  • Docs.citusdata.com/en/v10.2/ge…
  • Docs.citusdata.com/en/v10.2/ge…

If you already have PostgreSQL running on your machine, you may encounter this error when starting the Docker container:

Error starting userland proxy:
Bind for 0.0.0.0:5432: unexpected error address already in use
Copy the code

This is because Citus images attempt to bind to standard PostgreSQL port 5432. To resolve this problem, use the -p option to select a different port. You also need to use the new port in the PSQL command below.

Ubuntu and Debian

This section describes the steps required to set up a single-node Citus cluster using the DEB package on your own Linux machine.

  1. The installationPostgreSQL 14 和 Citusextension
# Add Citus repository for package manager
curl https://install.citusdata.com/community/deb.sh | sudo bash

# install the server and initialize dbSudo apt-get -y install postgresql-14-citus-10.2Copy the code

2. Initialize the cluster

Let’s create a new database on disk. To facilitate connection using the PostgreSQL Unix Domain socket, we will use the Postgres user.

# this user has access to sockets in /var/run/postgresql
sudo su - postgres

# include path to postgres binaries
export PATH=$PATH:/usr/lib/postgresql/14/bin

cd ~
mkdir citus
initdb -D citus
Copy the code

Citus is a Postgres extension. To tell Postgres to use this extension, you need to add it to a configuration variable called shared_preload_libraries:

echo "shared_preload_libraries = 'citus'" >> citus/postgresql.conf
Copy the code

3. Start the database server

Finally, we’ll start a PostgreSQL instance for the new directory:

pg_ctl -D citus -o "-p 9700" -l citus_logfile start
Copy the code

Above you added Citus to shared_preload_libraries. This allows it to connect to some of the deeper parts of Postgres, swapping query Planners and executors. Here, we load the user-facing side of Citus (such as the function you’ll be calling soon) :

psql -p 9700 -c "CREATE EXTENSION citus;"
Copy the code
  1. Verify that the installation is successful

To verify that the installation was successful and Citus was installed:

psql -p 9700 -c "select citus_version();"
Copy the code

You should see the details of the Citus extension.

Fedora, CentOS, or Red Hat

This section describes the steps required to set up a single-node Citus cluster using the RPM package on your own Linux machine.

  1. The installationPostgreSQL 14 和 Citusextension
# Add Citus repository for package manager
curl https://install.citusdata.com/community/rpm.sh | sudo bash

# install Citus extension
sudo yum install -y citus102_14
Copy the code

2. Initialize the cluster

Let’s create a new database on disk. To facilitate connection using the PostgreSQL Unix Domain socket, we will use the Postgres user.

# this user has access to sockets in /var/run/postgresql
sudo su - postgres

# include path to postgres binaries
export PATH=$PATH:/usr/pgsql-14/bin

cd ~
mkdir citus
initdb -D citus
Copy the code

Citus is a Postgres extension. To tell Postgres to use this extension, you need to add it to a configuration variable called shared_preload_libraries:

echo "shared_preload_libraries = 'citus'" >> citus/postgresql.conf
Copy the code

3. Start the database server

Finally, we’ll start a PostgreSQL instance for the new directory:

pg_ctl -D citus -o "-p 9700" -l citus_logfile start
Copy the code

Above you added Citus to shared_preload_libraries. This allows it to connect to some of the deeper parts of Postgres, swapping query Planners and executors. Here, we load the user-facing side of Citus (such as the function you’ll be calling soon) :

psql -p 9700 -c "CREATE EXTENSION citus;"
Copy the code
  1. Verify that the installation is successful

To verify that the installation was successful and Citus was installed:

psql -p 9700 -c "select citus_version();"
Copy the code

You should see the details of the Citus extension.

In this step, you have completed the installation process and are ready to use the Citus cluster. To help you get started, we’ve provided a tutorial with instructions on setting up a Citus cluster using sample data in a few minutes.

Multi-node Citus

Ubuntu and Debian

This section describes the steps required to set up a multi-node Citus cluster on your own Linux machine using the DEB package.

Steps performed on all nodes

  1. Add the warehouse
# Add Citus repository for package manager
curl https://install.citusdata.com/community/deb.sh | sudo bash
Copy the code
  1. The installationPostgreSQL + CitusAnd initialize the database
# install the server and initialize dbSudo apt-get -y install postgresql-14-citus-10.2# preload citus extension
sudo pg_conftool 14 main set shared_preload_libraries citus
Copy the code

This in/etc/postgresql / 14 / main installed in the centralized configuration, and in the/var/lib/postgresql / 14 / main created in the database.

  1. Configure connection and authentication

Before starting the database, let’s change its access rights. By default, the database server listens only for clients on localhost. As part of this step, we instruct it to listen on all IP interfaces and then configure the client authentication file to allow all incoming connections from the local network.

sudo pg_conftool 14 main set listen_addresses The '*'
Copy the code
sudo vi /etc/postgresql/14/main/pg_hba.conf
Copy the code
# Allow unrestricted access to nodes in the local network. The following ranges
# correspond to 24, 20, and 16-bit blocks in Private IPv4 address spaces.Host all all 10.0.0.0/8 trust# Also allow the host unrestricted access to connect to itselfHost all all 127.0.0.1/32 trust Host all All ::1/128 trustCopy the code

Your DNS Settings may be different. In addition, these Settings are too loose for some environments, see our notes on improving staff security. The PostgreSQL manual explains how to make them more restrictive.

  1. Start the database server and create the Citus extension
# start the db server
sudo service postgresql restart
# and make it start automatically when computer does
sudo update-rc.d postgresql enable
Copy the code

You must add Citus extensions to each database you want to use in the cluster. The following example adds the extension to a default database named Postgres.

# add the citus extension
sudo -i -u postgres psql -c "CREATE EXTENSION citus;"
Copy the code

Procedure performed on a Coordinator node

The steps listed below must be performed on a Coordinator node only after the steps mentioned earlier have been performed.

  1. addworkerNode information

Coordinator needs to be notified about its worker. To add this information, we call a UDF that adds the node information to the PG_dist_node directory table. For our example, we assume that we have two workers (named worker-101, worker-102). Add the WORKER’s DNS name (or IP address) and server port to the table.

sudo -i -u postgres psql -c "SELECT * from citus_add_node('worker-101', 5432);"
sudo -i -u postgres psql -c "SELECT * from citus_add_node('worker-102', 5432);"
Copy the code
  1. Verify that the installation is successful

To verify that the installation is successful, we check that the Coordinator node has selected the desired working configuration. This command, when run in the PSQL shell, should output the worker node we added to the pg_dist_node table above.

sudo -i -u postgres psql -c "SELECT * FROM citus_get_active_worker_nodes();"
Copy the code

Prepare to use Citus

In this step, you have completed the installation process and are ready to use the Citus cluster. The new Citus database can be accessed in PSQL by the Postgres user:

sudo -i -u postgres psql
Copy the code

Fedora, CentOS, or Red Hat

This section describes the steps required to set up a multi-node Citus cluster using the RPM package on your own Linux machine.

Steps performed on all nodes

  1. Add the warehouse
# Add Citus repository for package manager
curl https://install.citusdata.com/community/rpm.sh | sudo bash
Copy the code
  1. The installationPostgreSQL + CitusAnd initialize the database
# install PostgreSQL with Citus extension
sudo yum install -y citus102_14
# initialize system database (using RHEL 6 vs 7 method as necessary)
sudo service postgresql-14 initdb || sudo /usr/pgsql-14/bin/postgresql-14-setup initdb
# preload citus extension
echo "shared_preload_libraries = 'citus'" | sudo tee -a /var/lib/pgsql/14/data/postgresql.conf
Copy the code

PostgreSQL adds version-specific binaries in /usr/pgSQL-14/bin, but you usually just need PSQL, the latest version of which has been added to your path, and you can use the service command to manage the server itself.

  1. Configure connection and authentication

Before starting the database, let’s change its access rights. By default, the database server listens only for clients on localhost. As part of this step, we instruct it to listen on all IP interfaces and then configure the client authentication file to allow all incoming connections from the local network.

sudo vi /var/lib/pgsql/14/data/postgresql.conf
Copy the code
# Uncomment listen_addresses for the changes to take effect
listen_addresses = The '*'
Copy the code
sudo vi /var/lib/pgsql/14/data/pg_hba.conf
Copy the code
# Allow unrestricted access to nodes in the local network. The following ranges
# correspond to 24, 20, and 16-bit blocks in Private IPv4 address spaces.Host all all 10.0.0.0/8 trust# Also allow the host unrestricted access to connect to itselfHost all all 127.0.0.1/32 trust Host all All ::1/128 trustCopy the code

Your DNS Settings may be different. In addition, these Settings are too loose for some environments, see our notes on improving Worker security. The PostgreSQL manual explains how to make them more restrictive.

  • Docs.citusdata.com/en/v10.2/ad…
  1. Start the database server and create the Citus extension
# start the db server
sudo service postgresql-14 restart
# and make it start automatically when computer does
sudo chkconfig postgresql-14 on
Copy the code

You must add Citus extensions to each database you want to use in the cluster. The following example adds the extension to a default database named Postgres.

sudo -i -u postgres psql -c "CREATE EXTENSION citus;"
Copy the code

Procedure performed on a Coordinator node

The steps listed below must be performed on a Coordinator node only after the steps mentioned earlier have been performed.

  1. addworkerNode information

Coordinator needs to be notified about its worker. To add this information, we call a UDF that adds the node information to the PG_dist_node directory table. For our example, we assume that we have two workers (named worker-101, worker-102). Add the WORKER’s DNS name (or IP address) and server port to the table.

sudo -i -u postgres psql -c "SELECT * from citus_add_node('worker-101', 5432);"
sudo -i -u postgres psql -c "SELECT * from citus_add_node('worker-102', 5432);"
Copy the code
  1. Verify that the installation is successful

To verify that the installation is successful, we check that the Coordinator node has selected the desired working configuration. This command, when run in the PSQL shell, should output the worker node we added to the pg_dist_node table above.

sudo -i -u postgres psql -c "SELECT * FROM citus_get_active_worker_nodes();"
Copy the code

Prepare to use Citus

In this step, you have completed the installation process and are ready to use the Citus cluster. The new Citus database can be accessed in PSQL by the Postgres user:

sudo -i -u postgres psql
Copy the code

More and more

  • Django-multitenant database Project (Python/Django+Postgres+Citus)
  • Official example of distributed PostgreSQL Cluster (Citus) – Time series data