Skip to content

Commit c71a4be

Browse files
amunrasklarsaglasstiger
authored
Migrating from Open Source to Enterprise (#168)
Added a guide on what steps to take to upgrade an Open Source installation from Open Source to Enterprise. --------- Co-authored-by: Steven Sklar <[email protected]> Co-authored-by: glasstiger <[email protected]>
1 parent a9c244a commit c71a4be

File tree

2 files changed

+177
-2
lines changed

2 files changed

+177
-2
lines changed

‎documentation/operations/migrate-to-enterprise.md

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
---
2+
title: Migrate to Enterprise edition
3+
sidebar_label: Migrate to Enterprise edition
4+
description:
5+
Instructions on how to upgrade a QuestDB open source installation to QuestDB
6+
Enterprise.
7+
---
8+
9+
This page covers the steps to migrate a database instance from QuestDB open
10+
source edition to QuestDB Enterprise edition.
11+
12+
## Overview
13+
14+
The QuestDB Enterprise edition is based on the Open Source edition of the
15+
database.
16+
17+
Migrating from QuestDB Open Source to QuestDB Enterprise is a straightforward
18+
process. It is nonetheless important to follow the steps carefully to ensure a
19+
successful migration.
20+
21+
## Migration Workflow
22+
23+
### Step 0: Backup your data
24+
25+
Before you start the migration process, consider backing up your data.
26+
27+
You can follow the instructions in the
28+
[Backup and restore](/docs/operations/backup/) guide create a restore point.
29+
It is unlikely that you will need the restore point, but it is a good idea to
30+
have it in case something goes wrong.
31+
32+
In short:
33+
34+
* Checkpoint the database:
35+
```questdb-sql
36+
CHECKPOINT CREATE
37+
```
38+
39+
* Back up the files, such as creating a `.tar` archive or taking an AWS EBS
40+
volume snapshot.
41+
42+
:::info
43+
If backing up is not possible, you can safely skip this step.
44+
:::
45+
46+
### Step 1: Download the Enterprise binaries
47+
48+
You should have received an email detailing the download steps and credentials
49+
to obtain the Enterprise binaries.
50+
51+
Each Enterprise version is built for a specific operating system and
52+
architecture. You should always opt for the latest version of the Enterprise
53+
edition.
54+
55+
:::tip
56+
You may consult the [release notes](https://questdb.com/release-notes/?type=enterprise)
57+
to consult the latest changes and features.
58+
:::
59+
60+
### Step 2: Install and restart the database
61+
62+
* Unpack the binaries in a directory of your choice.
63+
* Replace your existing QuestDB binaries with the new ones.
64+
* Stop the database.
65+
* Start the database with the new binaries _in place_.
66+
67+
:::info
68+
The first time you start the database with the new binaries, the migration
69+
process will kick in and ready the database state for the new features.
70+
:::
71+
72+
### Step 3: Set up TLS connection encryption
73+
74+
Prepare your server TLS certificates in PEM format and continue with the
75+
[TLS Encryption](/docs/operations/tls/) guide.
76+
77+
:::info
78+
If you don't have a TLS certificate yet, you can ask QuestDB to
79+
generate a
80+
[self-signed demo certificate](/docs/operations/tls/#demo-certificates).
81+
:::
82+
83+
### Step 4: Set up user accounts and permissions
84+
85+
First override the default admin credentials in `server.conf`.
86+
It is recommended to select a non-trivial username and password.
87+
```
88+
acl.admin.user=myadmin
89+
acl.admin.password=mypwd
90+
```
91+
The above settings will replace the default built-in admin account
92+
(`admin`/`quest`) to make the database safer.
93+
94+
However, the password is still stored in the configuration file as
95+
plain text.
96+
We recommend to create your own admin account(s), and completely
97+
disable the built-in admin.
98+
99+
To create your own database administrators, start the database up, and
100+
login via the Web Console with the admin credentials specified previously
101+
in `server.conf`. Then create one or more admin accounts which will be
102+
used for database and user management.
103+
104+
For example, the simplest way to create a full admin:
105+
```questdb-sql
106+
CREATE USER administrator WITH PASSWORD adminpwd;
107+
GRANT ALL TO administrator WITH GRANT OPTION;
108+
```
109+
110+
The above `administrator` user replaces the built-in admin, which can be
111+
disabled now in the configuration file:
112+
```
113+
acl.admin.user.enabled=false
114+
```
115+
116+
The built-in admin settings can stay in `server.conf`, and can be
117+
re-enabled in emergency situations, such as all database administrators
118+
have forgotten their passwords.
119+
120+
Now we can go ahead and setup groups, user and service accounts with the
121+
help of the new database administrator(s).
122+
More details on this topic can be found in the
123+
[RBAC documentation](/docs/operations/rbac/#user-management).
124+
125+
For setting up Single Sign-On (SSO), please, refer to the
126+
[OIDC Integration](/docs/operations/openid-connect-oidc-integration) guide,
127+
which explains how QuestDB integrates with OAuth2/OIDC providers in general.
128+
Although we cannot cover all OAuth2 providers, we also documented
129+
[PingFederate](/docs/guides/active-directory-pingfederate)
130+
and [Microsoft EntraID](/docs/guides/microsoft-entraid-oidc)
131+
example setups. Other providers should be configured similarly.
132+
133+
:::warning
134+
135+
It is important to disable the built-in admin user for security purposes.
136+
137+
:::
138+
139+
### Step 5: Setting up replication
140+
141+
If you wish to use the replication features, continue with setting up the
142+
object store and `server.conf` changes as detailed in the
143+
[Database Replication](/docs/operations/replication) guide.
144+
145+
## Unsupported Migration Workflows
146+
147+
When a database is migrated from the Open Source to the Enterprise edition, the
148+
database upgrades the state in each of the database tables to enable the new
149+
features of the Enterprise edition, such as database replication.
150+
151+
Because of this, we only support an in-place edition migration.
152+
153+
:::warning
154+
155+
We do not support directly copying table data directories and files from an Open
156+
Source installation to an Enterprise installation, as the required state for
157+
Enterprise features would not be initialized and the database would not operate
158+
correctly.
159+
160+
If you have a production instance of QuestDB Open Source and have already been
161+
testing the new features of the Enterprise edition on a second instance,
162+
ensure that the two instances don't share any filesystem directories.
163+
If you had activated the replication features on this second instance and want
164+
to reuse the same object store location, you must first clear it to transfer
165+
object store ownership to the new migrated database instance.
166+
167+
If you have a more complex migration scenario, please contact us and we'll be
168+
happy to help with your specific setup.
169+
170+
:::

‎documentation/sidebars.js

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -435,11 +435,12 @@ module.exports = {
435435
label: "Operations",
436436
type: "category",
437437
items: [
438-
"operations/capacity-planning",
439438
{
440-
id: "configuration",
439+
id: "operations/migrate-to-enterprise",
441440
type: "doc",
441+
customProps: { tag: "Enterprise" },
442442
},
443+
"operations/capacity-planning",
443444
"operations/command-line-options",
444445
"operations/backup",
445446
{
@@ -482,6 +483,10 @@ module.exports = {
482483
label: "Multi-primary ingestion",
483484
customProps: { tag: "Enterprise" },
484485
},
486+
{
487+
id: "configuration",
488+
type: "doc",
489+
},
485490
],
486491
},
487492
{

0 commit comments

Comments
 (0)