XRAY: Extension "btree_gist.control" Missing Error in Xray Upgrade

When encountering the error message indicating that the extension "btree_gist.control" is not installed in the database, it is crucial to follow specific steps to resolve this issue before upgrading Xray. for more information, please refer to here.

Cause

This extension is not packaged until Xray version 3.84.x. Suppose you are performing an upgrade from a previous Xray version and using bundled PostgreSQL. In that case, you must manually install the necessary packages based on the PostgreSQL version currently installed.
The error message typically appears as follows:

ERROR: could not open extension control file "/usr/share/pgsql/extension/btree_gist.control": No such file or directory (SQLSTATE 58P01)

This error indicates that the PostgreSQL extension control file for "btree_gist" is missing on the database server.

Solution

1. Stop Xray completely

2. Install the btree_gist Extension: Ensure that the required PostgreSQL extension, "btree_gist", is installed on the database server. Follow these steps:

Manual Installation:

a. Determine the version of bundled PostgreSQL currently installed.
b. Visit the official PostgreSQL repository for RHEL/CentOS at the following URL: https://download.postgresql.org/pub/repos/yum/
c. Download the appropriate PostgreSQL . contrib package version and install them.

3. Once the extension is installed, verify its availability by executing the following SQL

select * from pg_available_extensions;
select * from pg_extension;

4. Create the Extension: Using a superuser (such as the postgres superuser), create the "btree_gist" extension with the following SQL command:

CREATE EXTENSION IF NOT EXISTS btree_gist;

5. Clear Failed Migration: To resolve any pending issues related to failed migrations in Xray's database (assuming the database name is "xraydb"), connect to the database and execute:

\c xraydb
delete from db_migrations_running;

6. After completing the above steps, start Xray and verify if the issue is resolved.

If you continue to encounter difficulties or require further assistance, please contact our support team.