Create the E-Maj Extension in a Database
========================================

If an older version of the E-Maj extension already exists in the database, you must :doc:`upgrade it <upgrade>` 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., :ref:`minimum installation <minimum_install>`), you can use a *psql* script instead.

----

.. _preliminary_operations:

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>;

----

.. _create_emaj_extension:

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 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 :ref:`max_prepared_transactions parameter <parallel_rollback_prerequisite>`.

----

.. _create_emaj_extension_by_script:

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 :ref:`E-Maj installation <minimum_install>`, 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 :ref:`detailed here <non_superuser_install_limits>`.

----

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 :doc:`E-Maj parallel rollback client <parallelRollbackClient>`. 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 :ref:`here <emaj_param>`.

Setting these parameters is **optional**, as E-Maj works well with default values.

However, in order to use the :ref:`rollback operations monitoring capabilities <emaj_rollback_activity>`, or execute :doc:`parallel E-Maj rollbacks <parallelRollbackClient>`, 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.