DEV Community

mmllllzcn
mmllllzcn

Posted on

GBase Database Manual Instance Initialization: A Five-Step Guide

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 gbasedbt operating 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
Enter fullscreen mode Exit fullscreen mode

Checkpoint:

Confirm that:

  • The dbs directory belongs to gbasedbt.
  • The rootdbs file belongs to gbasedbt.
  • The rootdbs permission is 660.

You can verify the result with:

ls -ld /opt/GBASE/gbase/dbs
ls -l /opt/GBASE/gbase/dbs/rootdbs
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Expected output:

gbaseserver
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

For the initial configuration, start with these essential parameters:

ROOTPATH     /opt/GBASE/gbase/dbs/rootdbs
SERVERNUM    1
DBSERVERNAME gbaseserver
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Add the following entry:

gbaseserver  onsoctcp  192.168.127.101  9088
Enter fullscreen mode Exit fullscreen mode

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:

  1. The IP address is the actual server address reachable by clients.
  2. The port is consistent with the network and firewall plan.
  3. The instance name matches GBASEDBTSERVER and DBSERVERNAME.

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 -
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 -
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Add the required exports and reload the profile:

source ~/.bash_profile
Enter fullscreen mode Exit fullscreen mode

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.gbaseserver
  • sqlhosts.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:

  1. Create the data directory and rootdbs.
  2. Configure the instance environment.
  3. Define the essential onconfig parameters.
  4. Configure network connectivity through sqlhosts.
  5. 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)