Database Migration

This page covers migrating the NetXMS database between different database engines — for example, moving from SQLite to PostgreSQL or from MySQL to PostgreSQL.

For command-line tools reference, see Command-Line Tools.

If you are moving NetXMS to a new server but keeping the same database engine, see Server Migration instead. Native database tools (such as pg_dump/pg_restore or mysqldump) are faster and more efficient for same-engine moves. The procedures on this page are for switching to a different engine.

Before You Begin

Always create a full backup before starting any migration. See Backup and Recovery for backup procedures.

The NetXMS server must be stopped during migration (except for background stages of the two-stage procedure)
Run nxdbmgr check on the source database before migration to ensure consistency
Set up the target database and user account (see Database Setup)
If you are also moving to a new server, remember to copy the server data directory (MIB files, uploaded files). See Copying the Data Directory for details.

Method 1: nxdbmgr migrate (Preferred)

The nxdbmgr migrate command copies data directly from one database to another. This is the preferred method when both the source and destination databases are network-accessible from the same machine.

How It Works

The migrate command uses two configuration files:

The destination database is read from nxdbmgr’s own config — by default /etc/netxmsd.conf (or $NETXMS_HOME/etc/netxmsd.conf), overridden with -c <file>
The source database is specified by the config file path passed as an argument to migrate

Both files use the same format. Only the database connection parameters need to differ.

You can run nxdbmgr migrate from any machine with network access to both databases:

Where you run nxdbmgr Command

Where you run nxdbmgr	Command
Old server	`nxdbmgr -c netxmsd-new.conf migrate /etc/netxmsd.conf`
New server	`nxdbmgr migrate old-netxmsd.conf`
Third-party machine	`nxdbmgr -c netxmsd-new.conf migrate old-netxmsd.conf`

Old server

nxdbmgr -c netxmsd-new.conf migrate /etc/netxmsd.conf

New server

nxdbmgr migrate old-netxmsd.conf

Third-party machine

nxdbmgr -c netxmsd-new.conf migrate old-netxmsd.conf

The procedure below uses explicit -c netxmsd-new.conf for the destination config, which works from any location. If running on the new server where /etc/netxmsd.conf already points to the new database, omit -c.

Basic Procedure

Create a configuration file for the destination database — for example, netxmsd-new.conf:

DBDriver = pgsql.ddr
DBServer = new-db-server.example.com
DBName = netxms_db
DBLogin = netxms
DBPassword = new_secure_password

Initialize the destination database:

nxdbmgr -c netxmsd-new.conf init

This initializes the new (empty) destination database. The running server is not affected — it still uses the old database loaded at startup. Do not restart the server between this step and completing the migration.

Stop the NetXMS server:
```
sudo systemctl stop netxms-server
```
Run the migration. The argument is the path to the source (old) database config:
```
nxdbmgr -c netxmsd-new.conf migrate /etc/netxmsd.conf
```
Start the server:
```
sudo systemctl start netxms-server
```

Quick Migration (Skip Collected Data)

For a faster migration that skips historical performance data and logs, use the -s flag combined with -Z all:

nxdbmgr -c netxmsd-new.conf -s -Z all migrate /etc/netxmsd.conf

This migrates all configuration, nodes, DCI definitions, and thresholds, but skips:

Collected DCI data (idata/tdata tables)
All log tables (event log, audit log, syslog, SNMP trap log, etc.)

The server will start collecting fresh data immediately after migration. Historical data from before the migration will not be available.

Two-Stage Migration (Minimal Downtime)

For large databases, a two-stage migration minimizes downtime by transferring configuration first, then migrating historical data in the background while the server is already running on the new database.

Stage 1: Migrate Configuration (Server Downtime Required)

Prepare the destination configuration file as described in the basic procedure above (for example, netxmsd-new.conf)
Initialize the destination database:
```
nxdbmgr -c netxmsd-new.conf init
```
Stop the server:
```
sudo systemctl stop netxms-server
```
Migrate configuration and alarms, skipping collected data and large logs:
```
nxdbmgr -c netxmsd-new.conf -s -Z audit -Z event -Z snmptrap -Z syslog -Z winevent migrate /etc/netxmsd.conf
```
This transfers all configuration, node definitions, DCI definitions, alarms, and small log tables. Large historical logs are deferred to the background stage.
Start the server on the new database:
```
sudo systemctl start netxms-server
```

The server is now operational on the new database. New data collection and logging begins immediately.

Stage 2: Migrate Historical Data (Background)

With the server running on the new database, transfer the remaining data in the background.

Migrate the deferred log tables:

nxdbmgr -c netxmsd-new.conf -S -L audit -L event -L snmptrap -L syslog -L winevent migrate /etc/netxmsd.conf

Migrate collected performance data:

nxdbmgr -c netxmsd-new.conf -D migrate /etc/netxmsd.conf

These commands can run while the server is active. New data written by the server is not affected by the background migration.

nxdbmgr Options for Migration

Option Description

Option	Description
`-s`	Skip collected data (idata/tdata). Tables are created but not populated.
`-S`	Skip collected data and do not create data tables. Use with `-L` for background log migration.
`-D`	Migrate only collected data into existing tables. Does not clear or recreate the destination.
`-L <log>`	Migrate only the specified log. Can be repeated. Use `all` to include all logs.
`-Z <log>`	Exclude the specified log. Can be repeated. Use `all` to exclude all logs.
`-e <table>`	Exclude a specific database table by name. Can be repeated.
`-Y <table>`	Migrate only the specified table. Can be repeated.
`-T <recs>`	Transaction size (rows per commit). Default: 4096. Range: 1-100000.
`-j <count>`	Number of parallel migration workers. Default: 4. Range: 1-64.
`-x`	Ignore errors in collected data migration and continue.

-s

Skip collected data (idata/tdata). Tables are created but not populated.

-S

Skip collected data and do not create data tables. Use with -L for background log migration.

-D

Migrate only collected data into existing tables. Does not clear or recreate the destination.

-L <log>

Migrate only the specified log. Can be repeated. Use all to include all logs.

-Z <log>

Exclude the specified log. Can be repeated. Use all to exclude all logs.

-e <table>

Exclude a specific database table by name. Can be repeated.

-Y <table>

Migrate only the specified table. Can be repeated.

-T <recs>

Transaction size (rows per commit). Default: 4096. Range: 1-100000.

-j <count>

Number of parallel migration workers. Default: 4. Range: 1-64.

-x

Ignore errors in collected data migration and continue.

Log names for -L and -Z: action, ai, alarm, asset, audit, certificate, deployment, downtime, event, incident, maintenance, notification, otel, snmptrap, syslog, winevent, all.

Method 2: nxdbmgr export/import (Alternative)

When direct database-to-database connectivity is not available — for example, when the source and destination are on different networks or in air-gapped environments — use the export/import method.

How It Works

The nxdbmgr export command creates a portable database file (internally an SQLite database) containing the entire NetXMS database contents. This file can be transferred to another machine and imported into any supported database engine using nxdbmgr import.

Procedure

Step 1: Export from the Source Database

Stop the server and export the database:

sudo systemctl stop netxms-server
nxdbmgr export /tmp/netxms-db-export.nxd

The export file can be large — approximately the same size as the source database. Ensure sufficient disk space.

To export configuration only (skip collected data and logs):

nxdbmgr -s -Z all export /tmp/netxms-db-export.nxd

Step 2: Transfer the Export File

Copy the export file to the destination server using any file transfer method (SCP, USB drive, etc.):

scp /tmp/netxms-db-export.nxd new-server:/tmp/netxms-db-export.nxd

Step 3: Prepare the Destination Database

On the new server, set up the database (see Database Setup) and update netxmsd.conf with the new database connection parameters.

Initialize the database schema:

nxdbmgr init

This runs on the new server where /etc/netxmsd.conf already points to the new (empty) database, so no -c flag is needed.

Step 4: Import into the Destination Database

nxdbmgr import /tmp/netxms-db-export.nxd

The same filtering options (-s, -Z, -e) can be used during import to skip collected data or exclude specific tables.

Step 5: Start the Server

sudo systemctl start netxms-server

Post-Migration Verification

After completing the migration (regardless of method), verify the result:

Run a database consistency check:
```
nxdbmgr check
```
Verify data integrity in the management console:
- Node count matches the original system
- Recent DCI data is present (if historical data was migrated)
- Event log contains historical entries (if logs were migrated)
- Server configuration variables are intact
- Alarms and their states are preserved