ADB service actions

Anton Vasilev

This article describes the actions available for the ADB service in the ADCM web interface.

Create database

Recreates the default database. The default name is adb.

Under normal circumstances, the action is not required because the database is created automatically during ADB installation. You can use this action though if you’ve accidentally deleted the default database.

After the action completes successfully, you can check that the database exists:

  1. On the ADB coordinator host, log in as the gpadmin user:

    $ sudo su - gpadmin

  2. List all databases:

    $ psql -l

    The output should contain the adb database:

                                   List of databases
   Name    |  Owner  | Encoding |  Collate   |   Ctype    |  Access privileges
-----------+---------+----------+------------+------------+---------------------
 adb       | gpadmin | UTF8     | en_US.utf8 | en_US.utf8 | =Tc/gpadmin        +
           |         |          |            |            | gpadmin=CTc/gpadmin
 postgres  | gpadmin | UTF8     | en_US.utf8 | en_US.utf8 |
 template0 | gpadmin | UTF8     | en_US.utf8 | en_US.utf8 | =c/gpadmin         +
           |         |          |            |            | gpadmin=CTc/gpadmin
 template1 | gpadmin | UTF8     | en_US.utf8 | en_US.utf8 | =c/gpadmin         +
           |         |          |            |            | gpadmin=CTc/gpadmin
(5 rows)

Create role

Adds a new role to the database cluster.

The Create role window
The Create role window

On the Configuration tab of the window that opens, configure the following parameters.

Parameter Description Default value

Role name

A unique name for the new role

 — 

Role password

The password of the role. Can’t be left empty

 — 

Allow this role to log in

Determines whether a role is allowed to log in. When set to true, the role can be thought of as a user

true

Make role superuser

Determines whether a role is a superuser

false

Allow role to create databases

Determines whether the role can create new databases

false

Allow role to create users/roles

Determines whether the role can create new roles

false

Allow role to create external tables

Determines whether the role can create external tables

false

Resource Group

The name of an existing resource group to which a new role should be assigned. The value cannot be empty since each user should belong to a resource group

default_group

Enable auto core dump

Installs the Auto Core Dump service (systemd-coredump) on the coordinator, standby coordinator, and every segment host. The action uses the following values of the service configuration options:

  • Storage=external — core dumps will be stored in /var/lib/systemd/coredump/.

  • MaxUse=1024M — remove old core dumps when their size exceeds 1 GB.

To check that the service was successfully installed and started, run the following command on the coordinator, standby coordinator, or any segment host:

$ systemctl status systemd-coredump.socket

The service should have the active (listening) status:

systemd-coredump.socket - Process Core Dump Socket
     Loaded: loaded (/lib/systemd/system/systemd-coredump.socket; static)
     Active: active (listening) since Thu 2025-09-04 10:24:43 UTC; 21min ago
       Docs: man:systemd-coredump(8)
     Listen: /run/systemd/coredump (SequentialPacket)
   Accepted: 0; Connected: 0;
     CGroup: /system.slice/systemd-coredump.socket

Disable auto core dump

Removes the Auto Core Dump service (systemd-coredump) and its configuration files.

Enable mirroring

Enables synchronous replication for primary data segments by adding mirrors to the cluster.

On the Configuration tab of the window that opens, in the Type of mirroring list, select the mirroring type: spread or group.

Spread mirroring is used by default. If you select spread mirroring, the action verifies that the number of segment hosts in your cluster is greater than the number of segments configured per host and that the number of segments per host can be divided by the number of the data directories on the host without remainder. If these conditions are not met, the action will fail.

The Enable mirroring window
The Enable mirroring window

Install diskquota

Installs the Diskquota ADB extension. This extension allows users to limit the disk space used by schemas and roles.

The action creates the diskquota database and the diskquota schema and registers diskquota as a database extension.

You can check the diskquota extension by running:

SELECT * FROM pg_extension WHERE extname = 'diskquota';

The output should be similar to:

  oid  |  extname  | extowner | extnamespace | extrelocatable | extversion |   extconfig   | extcondition
-------+-----------+----------+--------------+----------------+------------+---------------+--------------
 20312 | diskquota |       10 |         2200 | t              | 2.3        | {20314,20321} | {"",""}
(1 row)

After diskquota is installed, the Uninstall diskquota and Reinstall diskquota actions become available.

Install MADlib

Installs the MADlib library.

The action creates the madlib extension and schema.

Check the installed version by running:

SELECT madlib.version();

The output should be similar to:

          version
---------------------------------------------------------------------------------------------------------
 MADlib version: 2.1.0, git revision: 6.22.1_arenadata41-244-g5ab0b4c4, cmake configuration time: Tue Oct 14 14:
46:34 UTC 2025, build type: RelWithDebInfo, build system: Linux-4.15.0-175-generic, C compiler: gcc 11, C++ comp
iler: g++ 11
(1 row)

After MADlib is installed, the Uninstall MADlib and Reinstall MADlib actions become available.

Install PostGIS

Installs the PostGIS extension.

To check the version of installed PostGIS, run the following command in your database:

SELECT PostGIS_Lib_Version();

The output should be similar to the following:

 postgis_lib_version
---------------------
 3.3.2
(1 row)

After PostGIS is installed, the Uninstall PostGIS and Reinstall PostGIS actions become available.

Reconfigure

Updates the service configuration according to the configuration settings.

The action restarts the cluster (using gpstop -arM fast) if any of the following configuration parameters are changed:

  • Interconnect properties → Interconnect type

  • Any option under SSL

Otherwise, the action reloads the configuration (using gpstop -au).

Redistribute

 

The Redistribute action redistributes tables to balance existing data over the newly expanded ADB cluster. The action is available only after the Expand cluster action has completed successfully. The action uses the Greenplum utility gpexpand.

It is recommended to rank the database tables before starting the action, i.e. specify the order in which tables should be redistributed.

Rank tables for redistribution

A priority of the table processing during redistribution is determined by the rank column value in the gpexpand.status_detail table. Tables with the lowest rank are redistributed first. To rank tables, follow the steps:

  1. Connect to the postgres database of the ADB cluster under the gpadmin user (e.g. via psql).

  2. For all rows of the gpexpand.status_detail table, set the initial value for the rank column that will be considered as maximum (and will match the lowest processing priority), e.g. 100:

    UPDATE gpexpand.status_detail SET rank = 100;

  3. Decrease the rank value for those tables that should be redistributed first. For example, as a result of the following queries, the Redistribute action will process the public.test table first, then the public.test2 table, and then other tables in gpexpand.status_detail.

    UPDATE gpexpand.status_detail SET rank = 10 WHERE fq_name = 'public.test';
UPDATE gpexpand.status_detail SET rank = 20 WHERE fq_name = 'public.test2';
TIP

  • Use a fully qualified table name (including a schema name) as the fq_name column value.

  • It is recommended to use the step 10 when ranking tables (instead of 1) — to provide the ability to quickly increase a table priority without affecting other tables.

  • Assign the highest priority (the smallest rank value) to those tables that are used more often than others.

  • To exclude any table from the redistribution process, you can remove it from the gpexpand.status_detail table.

Run redistribution

To run data redistribution, select the Redistribute action. It is recommended to perform redistribution during low-use hours when table locks do not have a significant impact on the cluster operations.

IMPORTANT

  • To perform redistribution, segment hosts should have enough disk space to temporarily store a copy of the largest table/partition.

  • During redistribution, each table or partition is locked (with the ACCESS EXCLUSIVE lock type) and becomes unavailable for read and write operations. Once its redistribution is completed, normal operations for this particular table resume.

  • New tables and partitions are distributed across all segments like under normal operating conditions.

After you select the Redistribute action, a dialog box opens in which you can set the following fields:

  • Timeout for expanding — the maximum redistribution duration in hours, minutes, and seconds.

  • Number of parallel processes — defines the number of tables to redistribute simultaneously (which maps to the -n option value for the gpexpand utility). Valid values are 1 — 96. Each table redistribution process requires two database connections: one to alter the table and another to update the table status in the gpexpand schema. Before increasing Number of parallel processes, check the current value of the server configuration parameter max_connections to ensure that the maximum connection limit is not exceeded.

The Redistribute window
The Redistribute window

To run the Redistribute action, click Run in the dialog box. If redistribution of all tables is completed within the time specified in the Timeout for expanding field, the gpexpand schema is removed from the postgres database. Otherwise, you can retry redistribution by running the Redistribute action again.

Monitor redistribution

To track the redistribution progress, you can run SQL queries against the following objects of the gpexpand schema in the postgres database:

  • gpexpand.status — the table that stores a history of redistribution status changes.

    Structure
    Column Description

    status

    A status of the ADB redistribution. Possible values:

    • SETUP — preparations for the cluster expansion are started during the Expand action.

    • SETUP DONE — preparations for the cluster expansion are completed during the Expand action.

    • EXPANSION STARTED — table redistribution is started during the Redistribute action.

    • EXPANSION STOPPED — table redistribution is stopped. The additional launch of the Redistribute action is required.

    • COMPLETED — redistribution of all tables is successfully completed after one or more launches of the Redistribute action.

    updated

    A timestamp of the status change
    Query example
    SELECT * FROM gpexpand.status;

    Result:

          status       |          updated
-------------------+----------------------------
 EXPANSION STARTED | 2024-02-28 08:02:31.026412
 SETUP DONE        | 2024-02-27 17:40:55.160054
 SETUP             | 2024-02-27 17:40:50.830922
(3 rows)

  • gpexpand.expansion_progress — a view that shows the current redistribution status: how many tables/bytes have been successfully redistributed and how many are left. Also, the view provides calculations of the estimated redistribution rate and estimated time to completion. Calculations restart each time you run the Redistribute action — after the first table redistribution is completed. Statistics on tables/bytes are refreshed as they are redistributed.

    NOTE

    In ADB, the gpexpand utility is used with the --simple-progress option to improve performance by reducing the amount of progress information written to the gpexpand tables. Due to this, only the Tables Expanded and Tables Left metrics have values in the gpexpand.expansion_progress table.
    Structure
    Column Description

    name

    A metric name:

    • Bytes Left — amount of data that is not yet redistributed (in bytes).

    • Bytes Done — amount of data that is successfully redistributed (in bytes).

    • Estimated Expansion Rate — the estimated rate of data redistribution (with a measurement unit).

    • Estimated Time to Completion — the estimated time required for redistribution completion (in hours, minutes, and seconds).

    • Tables Expanded — a number of tables that are successfully redistributed.

    • Tables Left — a number of tables that are not yet redistributed.

    value

    A value of the metric that is specified in the name column
    Query example
    SELECT * FROM gpexpand.expansion_progress;

    Result:

          name       | value
-----------------+-------
 Tables Expanded | 90
 Tables Left     | 7
(2 rows)

  • gpexpand.status_detail — the table that stores the current redistribution status for each table/partition.

    Structure
    Column Description

    table_oid

    A table object identifier (OID)

    dbname

    A name of the database to which the table belongs

    fq_name

    A fully qualified name of the table (with a schema name)

    root_partition_oid

    For a partitioned table, the OID of the root partition. Otherwise, None

    rank

    A rank that determines the priority of table processing during redistribution. Tables with the lowest rank are processed first

    external_writable

    Indicates whether the table is EXTERNAL WRITABLE (such tables require a different syntax when using gpexpand)

    status

    The current status of the table redistribution:

    • NOT STARTED;

    • IN PROGRESS;

    • COMPLETED;

    • NO LONGER EXISTS — the table does not exist anymore.

    expansion_started

    A timestamp of the table redistribution start. This column is only populated after the table is successfully redistributed

    expansion_finished

    A timestamp of the table redistribution completion

    source_bytes

    The disk size associated with the source table (in bytes). Due to the possible data bloat in heap tables and differing numbers of segments after expansion, it is not guaranteed that the final number of bytes will be equal to the source number. Values of the source_bytes column are used to estimate the redistribution duration.

    In ADB, the source_bytes value is equal to 0 for all tables due to using the --simple-progress option
    Query example
    SELECT dbname, fq_name, status, expansion_started, expansion_finished, source_bytes FROM gpexpand.status_detail;

    The output fragment:

      dbname   |                        fq_name                        |   status    |     expansion_started      |     expansion_finished     | source_bytes
-----------+-------------------------------------------------------+-------------+----------------------------+----------------------------+--------------
 adb       | kadb.offsets                                          | NOT STARTED |                            |                            |            0
 adb       | arenadata_toolkit.db_files_history_1_prt_p202310      | NOT STARTED |                            |                            |            0
 gpperfmon | public.database_history_1_prt_r1013160842             | NOT STARTED |                            |                            |            0
 gpperfmon | public.log_alert_history_1_prt_r598663655             | NOT STARTED |                            |                            |            0
 gpperfmon | public.log_alert_history_1_prt_r1113542580            | NOT STARTED |                            |                            |            0
 adb       | public.kafka_ssl                                      | NOT STARTED |                            |                            |            0
 adb       | public.adb_to_kafka_table3                            | NOT STARTED |                            |                            |            0
 adb       | arenadata_toolkit.db_files_current                    | NOT STARTED |                            |                            |            0
 adb       | arenadata_toolkit.db_files_history_1_prt_p202312      | NOT STARTED |                            |                            |            0
 gpperfmon | public.database_history_1_prt_r2098142994             | NOT STARTED |                            |                            |            0
 gpperfmon | public.network_interface_history_1_prt_1              | NOT STARTED |                            |                            |            0
 adb       | public.ext_adb_to_kafka_sasl_gssapi                   | NOT STARTED |                            |                            |            0
 adb       | public.adb_to_kafka_table7                            | NOT STARTED |                            |                            |            0
 adb       | arenadata_toolkit.db_files_history_1_prt_default_part | NOT STARTED |                            |                            |            0
 gpperfmon | public.queries_history_1_prt_r81170841                | NOT STARTED |                            |                            |            0
 gpperfmon | public.queries_history_1_prt_r419258856               | NOT STARTED |                            |                            |            0
 gpperfmon | public.diskspace_history_1_prt_r526486693             | NOT STARTED |                            |                            |            0
 adb       | public.test2                                          | COMPLETED   | 2024-02-28 08:02:37.00728  | 2024-02-28 08:02:38.048592 |            0
 gpperfmon | public.system_history_1_prt_r1569528921               | COMPLETED   | 2024-02-28 08:02:41.066986 | 2024-02-28 08:02:44.182122 |            0
 gpperfmon | public.database_history_1_prt_r932188937              | COMPLETED   | 2024-02-28 08:02:44.305985 | 2024-02-28 08:02:44.697928 |            0
 gpperfmon | public.segment_history_1_prt_1                        | COMPLETED   | 2024-02-28 08:02:44.841786 | 2024-02-28 08:02:45.426392 |            0
 diskquota | arenadata_toolkit.db_files_history_1_prt_default_part | COMPLETED   | 2024-02-28 08:02:46.096083 | 2024-02-28 08:02:48.04711  |            0
 adb       | diskquota.target                                      | COMPLETED   | 2024-02-28 08:02:48.166249 | 2024-02-28 08:02:48.602075 |            0
 adb       | arenadata_toolkit.db_files_history_1_prt_p202402      | COMPLETED   | 2024-02-28 08:02:48.73606  | 2024-02-28 08:02:49.505108 |            0

Reinstall ADB

Reinstalls the ADB service.

On the Configuration tab of the window that opens, configure the following parameters:

  • Reboot cluster servers after installation — a flag that indicates whether to reboot ADB hosts automatically after the Reinstall ADB action is completed. The default value is false meaning you need to restart hosts manually.

  • Reboot timeout, sec — a timeout that is used to wait for the reboot of ADB hosts (in seconds). The default value is 1800. The value must be at least 600.

The Reinstall ADB window
The Reinstall ADB window

Run SQL

Runs any custom SQL command on behalf of the gpadmin user.

The command is executed in the adb database unless another database is specified as the default database for client connections.

In the window that opens, in the SQL query field, enter your command.

The Run SQL window
The Run SQL window

To view the action result, on the Jobs page click the action name and open the Ansible [check] tab — the result will be in the SQL query line.

Start

Starts the ADB service.

Stop

Stops the ADB service. After you select the action, a dialog box opens in which you can set the ADB shutdown mode:

  • fast — the ADB service will be stopped after all transactions are interrupted and rolled back, and all active connections are closed. This is the default mode.

  • smart — the ADB service will be stopped only if there are no active client connections. Otherwise, the action fails with a warning.

  • immediate — the ADB service will be stopped after all transactions are aborted and PostgreSQL processes are killed. This mode does not allow a database server to complete transaction processing and clean up any temporary or in-process work files. It is not recommended to use the immediate mode since it can damage databases in some cases.

Manage tablespace

Creates a tablespace or modifies existing tablespaces.

Parameter Description Default value

Name

A unique name for the new tablespace. The name cannot start with the pg_ prefix.

Alternatively, you can specify the name of an existing tablespace to modify its parameters

pg_default

Path

The path to the directory that will be used for the tablespace. The parameter is required if you create a new tablespace. The directory must exist on the coordinator host and on every segment host; the action does not create it

 — 

Use for temporary and transaction files

Use the tablespace to store temporary objects. The action adds the tablespace to the temp_tablespaces configuration parameter.

To check tablespaces currently used to store temporary objects, you can run the following command:

$ gpconfig -s temp_tablespaces

The output should be similar to:

Values on all segments are consistent
GUC              : temp_tablespaces
Coordinator value: fast_storage
Segment     value: fast_storage

false
The Manage tablespace window
The Manage tablespace window
Found a mistake? Seleсt text and press Ctrl+Enter to report it