Table of Contents

Migration Guide

Migration Modes
Using the ALL-IN-ONE Script
Using the Migration Tool Directly

Binary Location
Command Line
Examples

RustDesk → BetterDesk Go
SQLite → PostgreSQL
PostgreSQL → SQLite
Node.js Console → Go Server

Data Preservation
Docker Migration

Migrate from RustDesk Docker
Migrate Docker to PostgreSQL

Upgrading from RustDesk Rust Server

Step 1: Stop Old Services
Step 2: Install BetterDesk
Step 3: Migrate Data
Step 4: Verify
Step 5: Clean Up

Backup Before Migration
Troubleshooting Migration

"Migration tool not found"
"Outdated migration binary"
PostgreSQL connection refused
Duplicate key errors

See also

Migration Guide

BetterDesk provides migration tools for moving between databases and from legacy RustDesk deployments.

Migration Modes

The migration tool supports 5 modes:

Mode	Source	Target	Description
`rust2go`	RustDesk Rust `db_v2.sqlite3`	BetterDesk Go SQLite	Migrate from original RustDesk server
`sqlite2pg`	BetterDesk Go SQLite	PostgreSQL	Move to PostgreSQL for production
`pg2sqlite`	PostgreSQL	BetterDesk Go SQLite	Reverse migration for backup/testing
`nodejs2go`	Node.js console SQLite	BetterDesk Go SQLite	Merge Node.js console data
`backup`	Any SQLite	SQLite copy	Create timestamped backup

Using the ALL-IN-ONE Script

The simplest way to migrate:

# Linux
sudo ./betterdesk.sh
# Choose option M — Migrate databases

# Windows
.\betterdesk.ps1
# Choose option M — Migrate databases

The script:

Detects current database configuration
Offers available migration paths
Creates automatic backup before migration
Runs the migration tool
Updates .env and service files
Restarts services

Using the Migration Tool Directly

Binary Location

# Linux
./betterdesk-server/tools/migrate/migrate-linux-amd64

# Or compile from source
cd betterdesk-server/tools/migrate
go build -o migrate .

Command Line

./migrate -mode <mode> -src <source> -dst <destination> [options]

Examples

RustDesk → BetterDesk Go

./migrate -mode rust2go \
  -src /path/to/rustdesk/db_v2.sqlite3 \
  -dst /opt/betterdesk/db_v2.sqlite3

This handles schema differences:

peer table → peers table
Column name mapping
UUID generation for entries without UUIDs

SQLite → PostgreSQL

./migrate -mode sqlite2pg \
  -src /opt/betterdesk/db_v2.sqlite3 \
  -dst "postgres://betterdesk:password@localhost:5432/betterdesk?sslmode=disable"

Migrated data:

All peers with status, tags, notes
Users with roles and TOTP config
API keys
Server config
Audit log entries
Address books
Access policies

PostgreSQL → SQLite

./migrate -mode pg2sqlite \
  -src "postgres://betterdesk:password@localhost:5432/betterdesk" \
  -dst /opt/betterdesk/db_v2.sqlite3

Useful for creating portable backups or moving to a smaller deployment.

Node.js Console → Go Server

./migrate -mode nodejs2go \
  -src /opt/BetterDeskConsole/data/auth.db \
  -dst /opt/betterdesk/db_v2.sqlite3 \
  -node-auth /opt/BetterDeskConsole/data/auth.db

Merges:

peer table → peers
users table → users
Folder assignments
Tags

Data Preservation

The migration tool preserves:

Data	rust2go	sqlite2pg	pg2sqlite	nodejs2go
Peers	✅	✅	✅	✅
Ed25519 keys	✅	✅	✅	N/A
UUIDs	✅ (generated)	✅	✅	✅ (generated)
ID history	✅	✅	✅	N/A
Bans	✅	✅	✅	N/A
Tags	✅	✅	✅	✅
Notes	N/A	✅	✅	✅
Users	N/A	✅	✅	✅
API keys	N/A	✅	✅	N/A
Audit log	N/A	✅	✅	N/A
Address books	N/A	✅	✅	N/A
Access policies	N/A	✅	✅	N/A

Docker Migration

Migrate from RustDesk Docker

./betterdesk-docker.sh
# Choose option M — Migrate from RustDesk Docker

The script:

Detects existing RustDesk containers and volumes
Copies db_v2.sqlite3 and id_ed25519 from old volumes
Runs rust2go migration
Creates BetterDesk containers with migrated data

Migrate Docker to PostgreSQL

./betterdesk-docker.sh
# Choose option P — Migrate to PostgreSQL

Adds a PostgreSQL container, runs sqlite2pg migration, and updates services.

Upgrading from RustDesk Rust Server

If you're running the original RustDesk hbbs+hbbr:

Step 1: Stop Old Services

sudo systemctl stop rustdesksignal rustdeskrelay
# or
sudo systemctl stop hbbs hbbr

Step 2: Install BetterDesk

sudo ./betterdesk.sh
# Choose option 1 — New installation

Step 3: Migrate Data

sudo ./betterdesk.sh
# Choose option M — Migrate databases
# Select "Rust → Go" migration

Step 4: Verify

# Check device count
curl http://localhost:21114/api/server/stats

# Verify in web console
open http://localhost:5000

Step 5: Clean Up

# Remove old services (the installer does this automatically)
sudo systemctl disable rustdesksignal rustdeskrelay
sudo rm /etc/systemd/system/rustdesk*.service

Backup Before Migration

Always create a backup before migrating:

# Using the installer
sudo ./betterdesk.sh
# Choose option 5 — Backup

# Manual backup
cp /opt/betterdesk/db_v2.sqlite3 /opt/betterdesk/db_v2.sqlite3.backup
cp /opt/BetterDeskConsole/data/auth.db /opt/BetterDeskConsole/data/auth.db.backup

Troubleshooting Migration

"Migration tool not found"

# If Go is installed, compile from source
cd betterdesk-server/tools/migrate
go build -o migrate .

"Outdated migration binary"

The installer checks if the binary supports the -mode flag. If not:

# Rebuild
cd betterdesk-server/tools/migrate
go build -o migrate .

PostgreSQL connection refused

# Check PostgreSQL is running
sudo systemctl status postgresql

# Test connection
psql "postgres://betterdesk:password@localhost:5432/betterdesk"

# Check firewall
sudo ufw allow 5432/tcp

Duplicate key errors

If migrating to a database that already has data, the migration tool uses INSERT OR IGNORE (SQLite) or ON CONFLICT DO NOTHING (PostgreSQL) to skip duplicates.