Overview
This guide walks you through the manual database preparation steps required to activate NextGen on an on-premise Teramind deployment that uses a non-default PostgreSQL installation running version 12 or older.
If you have a default PostgreSQL setup, you likely do not need this guide. See the applicability table below to confirm.
Does This Guide Apply to You?
Your Setup | PostgreSQL Version | Manual Database Prep Required? |
Any Setup | 13 or higher | No. Proceed directly to NextGen activation. No manual database steps are required. Please refer to the main guide here. |
Default PostgreSQL runs as a service on the Teramind host | 12 or lower | No. Teramind provisions the required databases automatically during activation. |
Non-Default PostgreSQL is external (e.g., Amazon RDS or a database on a separate host), containerized, or remote | 12 or lower | Yes. Complete all steps in this guide before activating NextGen. |
Consider Upgrading Your PostgreSQL Cluster
If your PostgreSQL version is 12 or lower, you can follow the How to Upgrade the Default PostgreSQL Cluster guide to upgrade to version 13. This eliminates the need for manual database preparation entirely, and running a supported PostgreSQL version is strongly recommended for long-term security. If upgrading is not feasible due to cluster size or other constraints, continue with the steps below.
How to Verify a Default PostgreSQL Installation
A default installation means PostgreSQL runs as a service on the same host as Teramind. Run all three checks below via SSH on your Teramind master node.
Check 1: PostgreSQL is listening on port 5432
sudo ss -ltnp 'sport = :5432'
You should see PostgreSQL listed and listening on port 5432:
Check 2: Teramind connects to localhost
cat /usr/local/teramind/conf/teramind.config | grep mdb_host
The output should show 127.0.0.1:
Check 3: PostgreSQL responds to sudo access
sudo -u postgres psql
You should see the PostgreSQL command console. Type exit to leave:
Result
If all 3 checks succeed, you have a default Postgres installation and Teramind will be able to upgrade to NextGen automatically. For all other scenarios, continue reading this guide.
Prerequisites
Before you begin, ensure the following:
SSH access to your Teramind master node (or direct access to your external PostgreSQL instance).
A PostgreSQL user with permission to create databases and extensions.
Your PostgreSQL version confirmed as 12 or lower.
Important: If you have a default installation and PostgreSQL 13 or higher, you do not need to create users, databases, or extensions manually. Run NextGen activation without the database preparation steps in this document.
Step 1: Prepare Database Users
NextGen requires two database users: one for the master database and one for the instance database. You can either reuse your existing Teramind users or create new ones.
Option A: Reuse Existing Users (Recommended)
A standard Teramind installation includes two databases:
Database | Purpose |
| Primary Teramind database |
| Instance database |
To confirm the owner of each database, run the following SQL queries:
SELECT pg_catalog.pg_get_userbyid(d.datdba) AS owner FROM pg_catalog.pg_database d WHERE d.datname = 'teramind';
SELECT pg_catalog.pg_get_userbyid(d.datdba) AS owner FROM pg_catalog.pg_database d WHERE d.datname = 'tm_onsite';
In most installations, the owners are teramind and tm_onsite respectively. Use these as your two database users:
Option B: Create New Users
If you prefer dedicated users for NextGen, create them as follows:
CREATE USER teramind_user WITH PASSWORD '<strong-password>';
CREATE USER onsite_user WITH PASSWORD '<strong-password>';
Note: If you create new users, substitute teramind_user and onsite_user everywhere this guide references teramind and tm_onsite.
Step 2: Create the NextGen Databases
Create two new databases and assign the owners identified in Step 1:
CREATE DATABASE "msp-teramind" OWNER teramind; CREATE DATABASE "msp-onsite" OWNER tm_onsite;
Install Required Extensions
1. Connect to the msp-teramind and run:
CREATE EXTENSION IF NOT EXISTS pgcrypto;
2. Connext to the msp-onsite database and run:
CREATE EXTENSION IF NOT EXISTS pgcrypto;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE EXTENSION IF NOT EXISTS "pg_trgm";
Step 3: Activate NextGen
With the databases and extensions in place, you are ready to activate NextGen.
Build Your Connection URLs
Each database requires a connection URL in the following format:
postgresql://<user>:<password>@<host>:<port>/<database>
Example URLs (localhost, default users):
Database | Connection URL |
|
|
|
|
Replace the host, port, user, and password values to match your environment.
Run the Activation Command
/usr/local/teramind/scripts/tm.pl -func activate_nextgen \
--master-db-url 'postgresql://teramind:[email protected]:5432/msp-teramind' \
--instance-db-url 'postgresql://tm_onsite:[email protected]:5432/msp-onsite'
Tip: If you run the activation script without providing database URLs and your environment requires them, the script will fail at the preflight check and prompt you to supply the URLs. You can then re-run the command above - no need to stop any running process.
Quick Reference
Scenario | What to Do |
PostgreSQL 13 or higher | No database preparation. Please refer to the main guide here. |
Default setup + PostgreSQL 12 or lower | No manual preparation. Databases are provisioned automatically during activation. |
Non-Default setup + PostgreSQL 12 or lower | Complete Steps 1–3 in this guide, then run |
Troubleshooting
Issue | Resolution |
| Verify your connection URLs are correct and that the database user has the required permissions. |
Extension creation fails | Ensure the user has superuser or |
Cannot connect to external database | Confirm the host, port, and firewall rules allow connections from the Teramind master node. |