Meta Description: Learn how to manually initialize a GBase Database(GBase 8s) instance in five steps, from creating the rootdbs file and configuring onconfig to setting up sqlhosts and verifying startup.
Script-based initialization is convenient for quick validation. But when deploying GBase Database(GBase 8s) in a production environment, manual instance initialization offers more control over directory permissions, configuration files, instance naming, network settings, and startup verification.
This guide walks through the manual initialization process in five steps, with executable commands and checkpoints for each stage.
The goal is not simply to get a database instance running. It is to establish a configuration baseline that can be checked, reproduced, and maintained.
Prerequisites
Before starting, make sure the following conditions are met:
- GBase Database(GBase 8s) installation is complete.
- The
gbasedbtoperating system user already exists. - The installation directory is
/opt/GBASE/gbase. - You have the required permissions to create directories and configure files.
The example uses the following instance settings:
| Item | Value |
|---|---|
| Installation directory | /opt/GBASE/gbase |
| Database user | gbasedbt |
| Instance name | gbaseserver |
| Server port | 9088 |
| Root database space | /opt/GBASE/gbase/dbs/rootdbs |
Step 1: Create the Data Directory and rootdbs
The first step is to prepare the directory and root database space file.
Run the following commands:
mkdir -p /opt/GBASE/gbase/dbs
chown gbasedbt:gbasedbt /opt/GBASE/gbase/dbs
chmod 755 /opt/GBASE/gbase/dbs
touch /opt/GBASE/gbase/dbs/rootdbs
chown gbasedbt:gbasedbt /opt/GBASE/gbase/dbs/rootdbs
chmod 660 /opt/GBASE/gbase/dbs/rootdbs
Checkpoint:
Confirm that:
- The
dbsdirectory belongs togbasedbt. - The
rootdbsfile belongs togbasedbt. - The
rootdbspermission is660.
You can verify the result with:
ls -ld /opt/GBASE/gbase/dbs
ls -l /opt/GBASE/gbase/dbs/rootdbs
Why does permission 660 matter?
The database process needs read and write access to rootdbs. The file should not be accessible to unrelated users.
A common initialization failure occurs when the file is created by root but its ownership is never changed. The database process then cannot write the required reserved page.
Step 2: Configure the Instance Environment
Next, define the environment variables required by the GBase Database instance.
Create or edit the instance profile:
export GBASEDBTSERVER=gbaseserver
export GBASEDBTDIR=/opt/GBASE/gbase
export ONCONFIG=onconfig.gbaseserver
export GBASEDBTSQLHOSTS=$GBASEDBTDIR/etc/sqlhosts.gbaseserver
export PATH=$GBASEDBTDIR/bin:$PATH
These variables define:
-
GBASEDBTSERVER: The target instance name. -
GBASEDBTDIR: The GBase Database installation directory. -
ONCONFIG: The configuration file used by the instance. -
GBASEDBTSQLHOSTS: The network connectivity configuration file. -
PATH: The executable search path.
Checkpoint:
Verify the instance name:
echo $GBASEDBTSERVER
Expected output:
gbaseserver
Make sure the instance name is consistent across the environment configuration, onconfig, and sqlhosts.
Step 3: Create the onconfig File
The onconfig file defines the main configuration parameters for a GBase Database instance.
Create:
/opt/GBASE/gbase/etc/onconfig.gbaseserver
For the initial configuration, start with these essential parameters:
ROOTPATH /opt/GBASE/gbase/dbs/rootdbs
SERVERNUM 1
DBSERVERNAME gbaseserver
The three parameters serve different purposes:
| Parameter | Purpose |
|---|---|
ROOTPATH |
Specifies the root database space file |
SERVERNUM |
Defines the server number |
DBSERVERNAME |
Defines the database server name |
For production environments, this minimal configuration is only a starting point.
Additional parameter groups should be planned according to CPU resources, memory capacity, connection requirements, and locking demand.
These performance and capacity parameters deserve a separate tuning exercise rather than being added without workload analysis.
Step 4: Configure sqlhosts
The sqlhosts file defines how clients connect to the database instance.
Create:
/opt/GBASE/gbase/etc/sqlhosts.gbaseserver
Add the following entry:
gbaseserver onsoctcp 192.168.127.101 9088
The fields represent:
-
gbaseserver: The instance name. -
onsoctcp: The connection protocol. -
192.168.127.101: The server IP address. -
9088: The listening port.
Checkpoint:
Before initialization, verify that:
- The IP address is the actual server address reachable by clients.
- The port is consistent with the network and firewall plan.
- The instance name matches
GBASEDBTSERVERandDBSERVERNAME.
Avoid using localhost when the instance needs to accept remote client connections.
Step 5: Initialize and Verify the Instance
With the directory, environment, and configuration files ready, proceed with the first initialization.
Run the following commands as the gbasedbt user:
oninit -ivy
onstat -
The first command initializes the instance. The second checks its current status.
An example of successful output is:
gbaseserver: On-Line -- Up 00:00:13 -- 1121592 Kbytes
The On-Line status indicates that the instance has entered normal operating mode.
Checkpoint:
Verify that:
- The instance name is
gbaseserver. - The instance status is
On-Line. - The uptime is increasing.
- The reported memory usage is reasonable for the configured environment.
What If Initialization Fails?
Do not immediately repeat oninit -ivy.
First, inspect the current instance state:
onstat -
Then investigate according to the reported condition.
Case 1: Shared memory not initialized
Check whether the ROOTPATH file exists and whether its ownership and permissions are correct.
ls -l /opt/GBASE/gbase/dbs/rootdbs
Also verify that the current shell environment points to the intended instance.
Case 2: Port or network error
Return to the sqlhosts configuration and verify the server address, port, and network access rules.
Case 3: Instance does not reach On-Line
Check the instance configuration and startup diagnostics before attempting another initialization.
Initialization should be performed only after confirming the existing instance state. Repeatedly running initialization commands without understanding the failure can make troubleshooting more difficult.
Two Additional Tasks After Initialization
Completing the five steps does not mean the environment is fully ready for long-term operations.
Two additional tasks help make the deployment reproducible.
1. Persist the Environment Variables
Add the environment variables from Step 2 to the gbasedbt user's shell startup file.
This avoids manually exporting the variables every time the user logs in.
For example, depending on the user's shell:
vi ~/.bash_profile
Add the required exports and reload the profile:
source ~/.bash_profile
Verify that the environment points to the correct instance before running administrative commands.
2. Preserve the Configuration Baseline
Keep the following files together as part of the deployment baseline:
onconfig.gbaseserversqlhosts.gbaseserver- The instance environment profile
If your configuration management process supports version control, use it to track changes and compare configurations across rebuilds.
This makes it easier to identify configuration differences during migration, recovery, and future maintenance.
Conclusion: Manual Initialization Creates a Reproducible Baseline
Manual initialization of GBase Database(GBase 8s) is more than an alternative to script-based deployment.
It provides an opportunity to verify every important decision before the instance starts:
- Create the data directory and
rootdbs. - Configure the instance environment.
- Define the essential
onconfigparameters. - Configure network connectivity through
sqlhosts. - Initialize the instance and verify its state with
onstat -.
Finally, archive the configuration files, initialization results, and server specifications together.
The extra effort spent on manual initialization creates a reference baseline for future scaling, rebuilding, and recovery.
A successfully initialized GBase Database instance is the starting point. A reproducible configuration is what makes it maintainable.
Top comments (0)