Create the E-Maj Extension in a Database

If an older version of the E-Maj extension already exists in the database, you must upgrade it first.

The standard way to install E-Maj is by creating an EXTENSION object (in PostgreSQL terminology). This requires superuser privileges.

In environments where superuser access is not available (e.g., minimum installation), you can use a psql script instead.

Optional Preliminary Operation

By default, E-Maj technical tables are created in the default tablespace. If you want to store them in a dedicated tablespace, create it if necessary and set it as the default for the session:

SET default_tablespace = <tablespace_name>;

Standard Creation of the E-Maj Extension

To create the E-Maj extension in the database, execute the following SQL command:

CREATE EXTENSION emaj CASCADE;

After verifying PostgreSQL version compatibility, the script:

  • Creates the emaj schema.

  • Populates it with technical tables, functions, and other required objects.

Caution

The emaj schema must contain only E-Maj-related objects.

If they do not already exist, the emaj_adm and emaj_viewer roles are created.

Finally, the installation script checks the instance configuration and may display a warning regarding the max_prepared_transactions parameter.

Creating the Extension via Script

If creating the E-Maj EXTENSION object is not possible, you can use a psql script instead:

\i <emaj_directory>/sql/emaj-<version>.sql

Here, <emaj_directory> is the directory generated by the E-Maj installation, and <version> is the current E-Maj version.

Caution

The installation script can be executed by a non-superuser role. However, in such a case, some functionalities may be limited depending on the installer’s privileges. These limitations and their possible workarounds are detailed here.

Changes in the PostgreSQL Instance Configuration

Two configuration parameters in the postgresql.conf file may need adjustment:

  • max_locks_per_transaction: E-Maj functions set a lock on each table in a processed table group. If an E-Maj operation fails with a message indicating that all entries in the shared lock table are exhausted, increase this parameter. Default value: 128 (PostgreSQL 19+) or 64 (earlier versions).

  • max_prepared_transactions: Required to use the E-Maj parallel rollback client. Default value: 0 (disables the tool). This value must be greater than or equal to the maximum number of concurrent parallel rollback operations.

Note

Modifying either parameter requires a PostgreSQL instance restart.

E-Maj Parameters

Several parameters influence E-Maj behavior. They are described in detail here.

Setting these parameters is optional, as E-Maj works well with default values. However, in order to use the rollback operations monitoring capabilities, or execute parallel E-Maj rollbacks, you must set the dblink_user_password parameter.

Test and Demonstration

To verify that E-Maj is installed correctly and to explore its main features, run the demonstration script in psql:

\i <emaj_directory>/sql/demo.sql

If no errors occur, the script displays the following message:

### This ends the E-Maj demo. Thank you for using E-Maj and have fun!

Reviewing the script output helps you discover many of E-Maj’s features. After execution, the demonstration environment remains intact, allowing you to explore it further.

To clean up, run the following command:

SELECT emaj.emaj_demo_cleanup();

This removes the emaj_demo_app_schema schema and the emaj demo group 1 and emaj demo group 2 table groups that had been created by the demo.sql script.