Managing an Advanced Server installation v13

Suggest edits

Unless otherwise noted, the commands and paths noted in the following section assume that you have performed an installation using the native packages.

Starting and stopping Advanced Server and supporting components

A service is a program that runs in the background and requires no user interaction (in fact, a service provides no user interface); a service can be configured to start at boot time, or manually on demand. Services are best controlled using the platform-specific operating system service control utility. Many of the Advanced Server supporting components are services.

The following table lists the names of the services that control Advanced Server and services that control Advanced Server supporting components:

Advanced Server Component NameLinux Service NameDebian Service Name
Advanced Serveredb-as-13edb-as@13-main
pgAgentedb-pgagent-13edb-as13-pgagent
PgBounceredb-pgbouncer-1.14edb-pgbouncer114
pgPool-IIedb-pgpool-4.1edb-pgpool41
Slonyedb-slony-replication-13edb-as13-slony-replication
EFMedb-efm-4.0edb-efm-4.0

You can use the Linux command line to control Advanced Server's database server and the services of Advanced Server's supporting components. The commands that control the Advanced Server service on a Linux platform are host specific.

Controlling a service on RHEL/Rocky Linux/AlmaLinux 8.x

If your installation of Advanced Server resides on RHEL/Rocky Linux/AlmaLinux 8.x, you must use the systemctl command to control the Advanced Server service and supporting components.

The systemctl command must be in your search path and must be invoked with superuser privileges. To use the command, open a command line, and enter:

systemctl <action> <service_name>

Where:

service_name specifies the name of the service.

action specifies the action taken by the service command. Specify:

  • start to start the service.
  • stop to stop the service.
  • restart to stop and then start the service.
  • status to discover the current status of the service.

Controlling a service on Ubuntu

If your installation of Advanced Server resides on Ubuntu, assume superuser privileges and invoke the following commands (using bundled scripts) to manage the service. Use the following commands to:

  • Discover the current status of a service:

    /usr/edb/as13/bin/epas_ctlcluster 13 main status

  • Stop a service:

    /usr/edb/as13/bin/epas_ctlcluster 13 main stop

  • Restart a service:

    /usr/edb/as13/bin/epas_ctlcluster 13 main restart

  • Reload a service:

    /usr/edb/as13/bin/epas_ctlcluster 13 main reload

  • Control the component services:

    systemctl restart edb-as@13-main

Using pg_ctl to control Advanced Server

You can use the pg_ctl utility to control an Advanced Server service from the command line on any platform. pg_ctl allows you to start, stop, or restart the Advanced Server database server, reload the configuration parameters, or display the status of a running server. To invoke the utility, assume the identity of the cluster owner, navigate into the home directory of Advanced Server, and issue the command:

./bin/pg_ctl -D <data_directory> <action>

data_directory is the location of the data controlled by the Advanced Server cluster.

action specifies the action taken by the pg_ctl utility. Specify:

  • start to start the service.
  • stop to stop the service.
  • restart to stop and then start the service.
  • reload sends the server a SIGHUP signal, reloading configuration parameters
  • status to discover the current status of the service.

For more information about using the pg_ctl utility or the command line options available, see the official PostgreSQL Core Documentation.

Choosing Between pg_ctl and the service Command

You can use the pg_ctl utility to manage the status of an Advanced Server cluster, but it is important to note that pg_ctl does not alert the operating system service controller to changes in the status of a server, so it is beneficial to use the service command whenever possible.

Configuring component services to AutoStart at System Reboot

After installing, configuring, and starting the services of Advanced Server supporting components on a Linux system, you must manually configure your system to autostart the service when your system reboots. To configure a service to autostart on a Linux system, open a command line, assume superuser privileges, and enter the following command.

On a Redhat-compatible Linux system, enter:

/sbin/chkconfig <service_name> on

Where service_name specifies the name of the service.

Connecting to Advanced Server with edb-psql

edb-psql is a command line client application that allows you to execute SQL commands and view the results. To open the edb-psql client, the client must be in your search path. The executable resides in the bin directory, under your Advanced Server installation.

Use the following command and options to start the edb-psql client:

psql -d edb -U enterprisedb

Where:

-d specifies the database to which edb-psql will connect.

-U specifies the identity of the database user that will be used for the session.

edb-psql is a symbolic link to a binary called psql, a modified version of the PostgreSQL community psql, with added support for Advanced Server features. For more information about using the command line client, see the PostgreSQL Core Documentation.

Configuring a package installation

The packages that install the database server component create service startup scripts.

Creating a database cluster and starting the service

The PostgreSQL initdb command creates a database cluster; when installing Advanced Server with an RPM package, the initdb executable is in /usr/edb/asx.x/bin. After installing Advanced Server, you must manually configure the service and invoke initdb to create your cluster. When invoking initdb, you can:

  • Specify environment options on the command line.
  • Include the systemd service manager on RHEL/Rocky Linux/AlmaLinux 8.x and use a service configuration file to configure the environment.

For more information, see the initdb documentation.

After specifying any options in the service configuration file, you can create the database cluster and start the service; these steps are platform specific.

On RHEL/Rocky Linux/AlmaLinux 8.x

To invoke initdb on a RHEL/Rocky Linux/AlmaLinux 8.x system, with the options specified in the service configuration file, assume the identity of the operating system superuser:

su - root

To initialize a cluster with the non-default values, you can use the PGSETUP_INITDB_OPTIONS environment variable by invoking the edb-as-13-setup cluster initialization script that resides under EPAS_Home/bin.

To invoke initdb export the PGSETUP_INITDB_OPTIONS environment variable with the following command:

PGSETUP_INITDB_OPTIONS="-E UTF-8" /usr/edb/as13/bin/edb-as-13-setup initdb

After creating the cluster, use systemctl to start, stop, or restart the service:

systemctl { start | stop | restart } edb-as-13

On Debian 10.x | 11 or Ubuntu 18.04 | 20.04

You can initialize multiple clusters using the bundled scripts. To create a new cluster, assume root privileges, and invoke the bundled script:

/usr/bin/epas_createcluster 13 main2

To start a new cluster, use the following command:

/usr/bin/epas_ctlcluster 13 main2 start

To list all the available clusters, use the following command:

/usr/bin/epas_lsclusters
Note

The data directory is created under /var/lib/edb-as/13/main2 and configuration directory is created under /etc/edb-as/13/main/.

Specifying Cluster Options with INITDBOPTS

You can use the INITDBOPTS variable to specify your cluster configuration preferences. By default, the INITDBOPTS variable is commented out in the service configuration file; unless modified, when you run the service startup script, the new cluster will be created in a mode compatible with Oracle databases. Clusters created in this mode will contain a database named edb, and have a database superuser named enterprisedb.

Initializing the Cluster in Oracle Mode

If you initialize the database using Oracle compatibility mode, the installation includes:

  • Data dictionary views compatible with Oracle databases.
  • Oracle data type conversions.
  • Date values displayed in a format compatible with Oracle syntax.
  • Support for Oracle-styled concatenation rules (if you concatenate a string value with a NULL value, the returned value is the value of the string).
  • Support for the following Oracle built-in packages.
PackageFunctionality compatible with Oracle Databases
dbms_alertProvides the capability to register for, send, and receive alerts.
dbms_jobProvides the capability for the creation, scheduling, and managing of jobs.
dbms_lobProvides the capability to manage on large objects.
dbms_outputProvides the capability to send messages to a message buffer, or get messages from the message buffer.
dbms_pipeProvides the capability to send messages through a pipe within or between sessions connected to the same database cluster.
dbms_rlsEnables the implementation of Virtual Private Database on certain Advanced Server database objects.
dbms_sqlProvides an application interface to the EDB dynamic SQL functionality.
dbms_utilityProvides various utility programs.
dbms_aqadmProvides supporting procedures for Advanced Queueing functionality.
dbms_aqProvides message queueing and processing for Advanced Server.
dbms_profilerCollects and stores performance information about the PL/pgSQL and SPL statements that are executed during a performance profiling session.
dbms_randomProvides a number of methods to generate random values.
dbms_redactEnables the redacting or masking of data that is returned by a query.
dbms_lockProvides support for the DBMS_LOCK.SLEEP procedure.
dbms_schedulerProvides a way to create and manage jobs, programs, and job schedules.
dbms_cryptoProvides functions and procedures to encrypt or decrypt RAW, BLOB or CLOB data. You can also use DBMS_CRYPTO functions to generate cryptographically strong random values.
dbms_mviewProvides a way to manage and refresh materialized views and their dependencies.
dbms_sessionProvides support for the DBMS_SESSION.SET_ROLE procedure.
utl_encodeProvides a way to encode and decode data.
utl_httpProvides a way to use the HTTP or HTTPS protocol to retrieve information found at an URL.
utl_fileProvides the capability to read from, and write to files on the operating system’s file system.
utl_smtpProvides the capability to send e-mails over the Simple Mail Transfer Protocol (SMTP).
utl_mailProvides the capability to manage e-mail.
utl_urlProvides a way to escape illegal and reserved characters within an URL.
utl_rawProvides a way to manipulate or retrieve the length of raw data types.

Initializing the Cluster in Postgres Mode

Clusters created in PostgreSQL mode do not include compatibility features. To create a new cluster in PostgreSQL mode, remove the pound sign (#) in front of the INITDBOPTS variable, enabling the "--no-redwood-compat" option. Clusters created in PostgreSQL mode will contain a database named postgres and have a database superuser named postgres.

You may also specify multiple initdb options. For example, the following statement:

INITDBOPTS="--no-redwood-compat -U alice --locale=en_US.UTF-8"

Creates a database cluster (without compatibility features for Oracle) that contains a database named postgres that is owned by a user named alice; the cluster uses UTF-8 encoding.

If you initialize the database using "--no-redwood-compat" mode, the installation includes the following package:

PackageFunctionality non-compatible with Oracle Databases
dbms_aqadmProvides supporting procedures for Advanced Queueing functionality.
dbms_aqProvides message queueing and processing for Advanced Server.
edb_bulkloadProvides direct/conventional data loading capability when loading huge amount of data into a database.
edb_genProvides miscellaneous packages to run built-in packages.
edb_objectsProvides Oracle compatible objects such as packages, procedures etc.
waitstatesProvides monitor session blocking.
edb_dblink_libpqProvides link to foreign databases via libpq.
edb_dblink_ociProvides link to foreign databases via OCI.
snap_tablesCreates tables to hold wait information. Included with DRITA scripts.
snap_functionsCreates functions to return a list of snap ids and the time the snapshot was taken. Included with DRITA scripts.
sys_statsProvides OS performance statistics.

In addition to the cluster configuration options documented in the PostgreSQL core documentation, Advanced Server supports the following initdb options:

--no-redwood-compat

Include the --no-redwood-compat keywords to instruct the server to create the cluster in PostgreSQL mode. When the cluster is created in PostgreSQL mode, the name of the database superuser will be postgres and the name of the default database will be postgres. The few Advanced Server’s features compatible with Oracle databases will be available with this mode. However, we recommend using the Advanced server in redwood compatibility mode to use all its features.

--redwood-like

Include the --redwood-like keywords to instruct the server to use an escape character (an empty string ('')) following the LIKE (or PostgreSQL-compatible ILIKE) operator in a SQL statement that is compatible with Oracle syntax.

--icu-short-form

Include the --icu-short-form keywords to create a cluster that uses a default ICU (International Components for Unicode) collation for all databases in the cluster. For more information about Unicode collations, refer to the EDB Postgres Advanced Server Guide available at:

https://www.enterprisedb.com/docs

For more information about using initdb, and the available cluster configuration options, see the PostgreSQL Core Documentation.

You can also view online help for initdb by assuming superuser privileges and entering:

/path_to_initdb_installation_directory/initdb --help

Where path_to_initdb_installation_directory specifies the location of the initdb binary file.

Modifying the Data Directory Location

on RHEL or Rocky Linux 8.x

On a RHEL/Rocky Linux/AlmaLinux 8.x host, the unit file is named edb-as-13.service and resides in /usr/lib/systemd/system. The unit file contains references to the location of the Advanced Server data directory. You should avoid making any modifications directly to the unit file because it may be overwritten during package upgrades.

By default, data files reside under /var/lib/edb/as13/data directory. To use a data directory that resides in a non-default location, perform the following steps:

  • Create a copy of the unit file under the /etc directory:

    cp /usr/lib/systemd/system/edb-as-13.service /etc/systemd/system/

  • After copying the unit file to the new location, create the service file /etc/systemd/system/edb-as-13.service.

  • Update the following values with new location of data directory in the /lib/systemd/system/edb-as-13.service file:

    Environment=PGDATA=/var/lib/edb/as13/data
PIDFile=/var/lib/edb/as13/data/postmaster.pid

  • Delete the entire content of /etc/systemd/system/edb-as-13.service file, except the following line:

    .include /lib/systemd/system/edb-as-13.service

  • Run the following command to initialize the cluster at the new location:

    PGSETUP_INITDB_OPTIONS="-E UTF-8" /usr/edb/as13/bin/edb-as-13-setup initdb

  • Use the following command to reload systemd, updating the modified service scripts:

    systemctl daemon-reload

  • Start the Advanced Server service with the following command:

    systemctl start edb-as-13

Configuring SELinux Policy to Change the Data Directory Location on RHEL/Rocky Linux/AlmaLinux 8.x

By default, the data files resides under /var/lib/edb/as13/data directory. To change the default data directory location depending on individual environment preferences, you must configure the SELinux policy and perform the following steps:

  • Stop the server using the following command:

    systemctl stop edb-as-13

  • Check the status of SELinux using the getenforce or sestatus command:

    # getenforce
Enforcing

# sestatus
SELinux status:                 enabled
SELinuxfs mount:                /sys/fs/selinux
SELinux root directory:         /etc/selinux
Loaded policy name:             targeted
Current mode:                   enforcing
Mode from config file:          enforcing
Policy MLS status:              enabled
Policy deny_unknown status:     allowed
Max kernel policy version:      31

  • Use the following command to view the SELinux context of the default database location:

    ls -lZ /var/lib/edb/as13/data
drwx------. enterprisedb enterprisedb unconfined_u:object_r:var_lib_t:s0 log

  • Create a new directory for a new location of the database using the following command:

    mkdir /opt/edb

  • Use the following command to move the data directory to /opt/edb:

    mv /var/lib/edb/as13/data /opt/edb/

  • Create a file edb-as-13.service under /etc/systemd/system directory to include the location of a new data directory:

    .include /lib/systemd/system/edb-as-13.service
[Service]
Environment=PGDATA=/opt/edb/data
PIDFile=/opt/edb/data/postmaster.pid

  • Use the semanage utility to set the context mapping for /opt/edb/. The mapping is written to /etc/selinux/targeted/contexts/files/file.contexts.local file.

    semanage fcontext --add --equal /var/lib/edb/as13/data /opt/edb

  • Apply the context mapping using restorecon utility:

    restorecon -rv /opt/edb/

  • Reload systemd to modify the service script using the following command:

    systemctl daemon-reload

  • Now, the /opt/edb location has been labeled correctly with the context, use the following command to start the service:

    systemctl start edb-as-13

Enabling Core Dumps

You can use core dumps to diagnose or debug errors. A core dump is a file containing a process's address space (memory) when the process terminates unexpectedly. Core dumps may be produced on-demand (such as by a debugger) or automatically upon termination.

Enabling Core Dumps on a RHEL/Rocky Linux/AlmaLinux 8 Host

On a RHEL/Rocky Linux/AlmaLinux 8.x, core file creation is disabled by default. To enable the core file generation, follow the following commands:

  • Identify the system's current limit using the ulimit -c or ulimit -a command. 0 indicates that core file generation is disabled.

    # ulimit -c
0

# ulimit -a
core file size          (blocks, -c) 0
data seg size           (kbytes, -d) unlimited
scheduling priority             (-e) 0
file size               (blocks, -f) unlimited
pending signals                 (-i) 3756
max locked memory       (kbytes, -l) 64
max memory size         (kbytes, -m) unlimited
open files                      (-n) 1024
pipe size            (512 bytes, -p) 8
POSIX message queues     (bytes, -q) 819200
real-time priority              (-r) 0
stack size              (kbytes, -s) 8192
cpu time               (seconds, -t) unlimited
max user processes              (-u) 3756
virtual memory          (kbytes, -v) unlimited
file locks                      (-x) unlimited

  • Create a new directory to store the core dumps and modify kernel.core_pattern to store the dumps in a specified directory:

    mkdir -p /var/coredumps
chmod a+w /var/coredumps

sysctl kernel.core_pattern=/var/coredumps/core-%e-%p
kernel.core_pattern = /var/coredumps/core-%e-%p

  • Use the following command to persist the kernel.core_pattern setting across reboots:

    echo 'kernel.core_pattern=/var/coredumps/core-%e-%p' >> /etc/sysctl.conf

  • Enable core dumps in /etc/security/limits.conf to allow a user to create core files. Each line describes a limit for a user in the following form:

    <domain>  <type>  <item>  <value>
   *       soft    core    unlimited

    Use * to enable the core dump size to unlimited.

  • Set the limit of core file size to UNLIMITED by using the following command:

    ulimit -c unlimited

ulimit -c
unlimited

  • To set a core limit for the services, add the following setting in /usr/lib/systemd/system/edb-as-13.service.

    [Service]
LimitCore=Infinity

  • Reload the service configuration:

    systemctl daemon-reload

  • Modify the global default limit using systemd, add the following setting in /etc/systemd/system.conf.

    DefaultLimitCORE=Infinity

  • Restart the systemd:

    systemctl daemon-reexec

  • Stop and then start Advanced Server:

    systemctl stop edb-as-13
systemctl start edb-as-13

  • Now, the core dumps are enabled, install the gdb tool and debug packages using the following command: 

    yum install gdb
debuginfo-install edb-as13 edb-as13-server-contrib edb-as13-server edb-as13-libs

  • Replace the path to a core dump file before proceeding to get a backtrace using the bt command to analyze output:

    gdb /usr/edb/as13/bin /var/coredumps/core-edb-postgres-65499
(gdb) bt full

Enabling Core Dumps on a Debian or Ubuntu Host

On Debian 10 or Ubuntu 18, 20, core file creation is disabled by default. To enable the core file generation, follow the following commands:

  • Identify the system's current limit using the ulimit -c or ulimit -a command. 0 indicates that core file generation is disabled.

    # ulimit -c
0

# ulimit -a
core file size          (blocks, -c) 0
data seg size           (kbytes, -d) unlimited
scheduling priority             (-e) 0
file size               (blocks, -f) unlimited
pending signals                 (-i) 7617
max locked memory       (kbytes, -l) 65536
max memory size         (kbytes, -m) unlimited
open files                      (-n) 1024
pipe size            (512 bytes, -p) 8
POSIX message queues     (bytes, -q) 819200
real-time priority              (-r) 0
stack size              (kbytes, -s) 8192
cpu time               (seconds, -t) unlimited
max user processes              (-u) 7617
virtual memory          (kbytes, -v) unlimited
file locks                      (-x) unlimited

  • Create a new directory to store the core dumps and modify kernel.core_pattern to store the dumps in a specified directory:

    mkdir -p /var/coredumps
chmod a+w /var/coredumps

sysctl kernel.core_pattern=/var/coredumps/core-%e-%p
kernel.core_pattern = /var/coredumps/core-%e-%p

  • Use the following command to persist the kernel.core_pattern setting across reboots:

    echo 'kernel.core_pattern=/var/coredumps/core-%e-%p' >> /etc/sysctl.conf

  • Enable core dumps in /etc/security/limits.conf to allow a user to create core files. Each line describes a limit for a user in the following form:

    <domain>  <type>  <item>  <value>
   *       soft    core    unlimited

    Use * to enable the core dump size to unlimited.

  • Set the limit of core file size to UNLIMITED by using the following command:

    ulimit -c unlimited

ulimit -c
unlimited

  • To set a core limit for the services, add the following setting in /lib/systemd/system/edb-as@.service.

    [Service]
LimitCore=Infinity

  • Reload the service configuration:

    systemctl daemon-reload

  • Modify the global default limit using systemd, add the following setting in /etc/systemd/system.conf.

    DefaultLimitCORE=Infinity

  • Restart the systemd:

    systemctl daemon-reexec

  • Stop and then start Advanced Server:

    systemctl stop edb-as@13.service
systemctl start edb-as@13.service

  • Now, the core dumps are enabled, install the gdb tool and debug symbols using the following command: 

    apt-get install gdb
apt-get install edb-as13 edb-as-contrib edb-as13-server edb-debugger-dbgsym

  • Replace the path to a core dump file before proceeding to get a backtrace using the bt command to analyze output:

    gdb /usr/lib/edb-as/13/bin /var/coredumps/core-edb-postgres-21638
(gdb) bt full
Note
  • The debug info packages name on a Debian or Ubuntu host may vary and include -dbgsym or -dbg suffix. For more information about setting sources.list and installing the debug info packages, visit Debian or Ubuntu wiki at https://wiki.debian.org/HowToGetABacktrace or https://wiki.ubuntu.com/Debug%20Symbol%20Packages respectively.
  • The core files can be huge depending on the memory usage, enabling the core dumps on a system may fill up its mass storage over time.

Starting Multiple Postmasters with Different Clusters

You can configure Advanced Server to use multiple postmasters, each with its own database cluster. The steps required are version specific to the Linux host.

On RHEL/Rocky Linux/AlmaLinux 8.x

The edb-as13-server-core RPM for version 8.x contains a unit file that starts the Advanced Server instance. The file allows you to start multiple services, with unique data directories and that monitor different ports. You must have root access to invoke or modify the script.

The example that follows creates an Advanced Server installation with two instances; the secondary instance is named secondary:

  • Make a copy of the default file with the new name. As noted at the top of the file, all modifications must reside under /etc. You must pick a name that is not already used in /etc/systemd/system.

    cp /usr/lib/systemd/system/edb-as-13.service /etc/systemd/system/secondary-edb-as-13.service

  • Edit the file, changing PGDATA to point to the new data directory that you will create the cluster against.

  • Create the target PGDATA with user enterprisedb.

  • Run initdb, specifying the setup script:

    /usr/edb/as13/bin/edb-as-13-setup initdb secondary-edb-as-13

  • Edit the postgresql.conf file for the new instance, specifying the port, the IP address, TCP/IP settings, etc.

  • Make sure that new cluster runs after a reboot:

    systemctl enable secondary-edb-as-13

  • Start the second cluster with the following command:

    systemctl start secondary-edb-as-13

Creating an Advanced Server Repository on an Isolated Network

You can create a local repository to act as a host for the Advanced Server RPM packages if the server on which you wish to install Advanced Server (or supporting components) cannot directly access the EDB repository. Please note that this is a high-level listing of the steps requires; you will need to modify the process for your individual network.

To create and use a local repository, you must:

  • Use dnf to install the epel-release, yum-utils, and createrepo packages.

    On RHEL or Rocky Linux or AlmaLinux 8.x:

    dnf install epel-release
dnf install yum-utils
dnf install createrepo

  • Create a directory in which to store the repository:

    mkdir /srv/repos

  • Copy the RPM installation packages to your local repository. You can download the individual packages or use a tarball to populate the repository. The packages are available from the EDB repository at https://repos.enterprisedb.com/.

  • Sync the RPM packages and create the repository.

    reposync -r edbas13 -p /srv/repos
createrepo /srv/repos

  • Install your preferred webserver on the host that will act as your local repository, and ensure that the repository directory is accessible to the other servers on your network.

  • On each isolated database server, configure yum or dnf to pull updates from the mirrored repository on your local network. For example, you might create a repository configuration file called /etc/yum.repos.d/edb-repo with connection information that specifies:

    [edbas13]
name=EnterpriseDB Advanced Server 13
baseurl=https://yum.your_domain.com/edbas13
enabled=1
gpgcheck=0

After specifying the location and connection information for your local repository, you can use dnf to install Advanced Server and its supporting components on the isolated servers. For example:

  • On RHEL or Rocky Linux or AlmaLinux 8:

    dnf -y install edb-as13-server
← Prev

Available native packages

↑ Up

Linux installation details

Next →

Windows installation details