DEV Community

mmllllzcn
mmllllzcn

Posted on

GBase Database: What Do profile, onconfig, and sqlhosts Actually Do?

When initializing GBase Database(GBase 8s), three configuration files are easy to confuse: profile, onconfig, and sqlhosts.

All three may include the instance name as a suffix, but they serve completely different purposes.

Confusing them can send database troubleshooting in the wrong direction. Understanding their responsibilities is essential for database initialization, configuration management, and connection troubleshooting.

1. Three Files, Three Different Responsibilities

The easiest way to understand these files is to separate their responsibilities:

Configuration file Responsibility Typical contents
profile.gbaseserver Environment variables GBASEDBTSERVER, GBASEDBTDIR, ONCONFIG, GBASEDBTSQLHOSTS
onconfig.gbaseserver Instance configuration ROOTPATH, SERVERNUM, DBSERVERNAME, BUFFERPOOL, LOCKS
sqlhosts.gbaseserver Connection configuration Instance name, protocol, IP address, port

In simple terms:

  • profile tells the shell which database environment and configuration files to use.
  • onconfig defines how the database instance operates.
  • sqlhosts defines the network connection information used by clients.

These files work together, but they are not interchangeable.

2. A Minimal Configuration Example

Consider an instance named gbaseserver.

File 1: profile.gbaseserver

export GBASEDBTSERVER=gbaseserver
export GBASEDBTDIR=/opt/GBASE/gbase
export ONCONFIG=onconfig.gbaseserver
export GBASEDBTSQLHOSTS=$GBASEDBTDIR/etc/sqlhosts.gbaseserver
Enter fullscreen mode Exit fullscreen mode

This file establishes the environment variables required by GBase Database.

In particular:

  • GBASEDBTSERVER identifies the target instance.
  • GBASEDBTDIR specifies the database installation directory.
  • ONCONFIG identifies the instance configuration file.
  • GBASEDBTSQLHOSTS identifies the connection configuration file.

File 2: onconfig.gbaseserver

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

This file defines instance-level configuration.

For example:

  • ROOTPATH specifies the root dbspace path.
  • SERVERNUM identifies the server number.
  • DBSERVERNAME specifies the database server name.

Production configurations contain additional parameters, including memory, buffer pool, and lock settings.

File 3: sqlhosts.gbaseserver

gbaseserver  onsoctcp  192.168.127.101  9088
Enter fullscreen mode Exit fullscreen mode

This file defines the connection entry for the instance.

The fields represent:

  1. Instance connection name
  2. Network protocol
  3. Server IP address
  4. Listening port

For remote connections, the IP address, port, protocol, and corresponding listener configuration must agree.

3. How Do the Three Files Work Together?

The relationship can be understood as a simple configuration chain:

profile
   |
   |-- GBASEDBTSERVER
   |-- ONCONFIG
   |       |
   |       v
   |    onconfig
   |       |
   |       v
   |    Instance configuration
   |
   |-- GBASEDBTSQLHOSTS
           |
           v
        sqlhosts
           |
           v
      Client connection
Enter fullscreen mode Exit fullscreen mode

The profile establishes the environment, onconfig controls instance behavior, and sqlhosts provides connection information.

A mismatch in any of these layers can cause startup or connectivity problems.

4. Troubleshoot in the Right Order

The troubleshooting sequence should follow the responsibility of each file.

Case A: The instance cannot start

Start with profile.

Check the instance name and configuration paths:

echo $GBASEDBTSERVER
echo $GBASEDBTDIR
echo $ONCONFIG
echo $GBASEDBTSQLHOSTS
Enter fullscreen mode Exit fullscreen mode

Then verify that the referenced files actually exist:

ls -l "$GBASEDBTDIR/etc/$ONCONFIG"
ls -l "$GBASEDBTSQLHOSTS"
Enter fullscreen mode Exit fullscreen mode

Next, inspect onconfig.

Check whether ROOTPATH points to the intended location and whether the required directory or device exists with the correct ownership and permissions.

Case B: The instance starts, but remote clients cannot connect

Start with sqlhosts.

Verify:

  • The instance connection name
  • The network protocol
  • The server IP address
  • The configured port

Then check whether the database listener is running and whether the port is listening:

ss -tlnp | grep 9088
Enter fullscreen mode Exit fullscreen mode

Also verify firewall rules and network reachability.

The key is to avoid changing instance parameters when the actual problem is a connection configuration mismatch.

5. One Grep Command to Check Instance Name Consistency

A quick consistency check can help identify mismatched instance names across the three files.

grep -H 'gbaseserver' \
  "$GBASEDBTDIR/etc/profile.gbaseserver" \
  "$GBASEDBTDIR/etc/onconfig.gbaseserver" \
  "$GBASEDBTSQLHOSTS"
Enter fullscreen mode Exit fullscreen mode

The expected output should include entries corresponding to:

GBASEDBTSERVER=gbaseserver
DBSERVERNAME gbaseserver
gbaseserver onsoctcp ...
Enter fullscreen mode Exit fullscreen mode

If one of these entries is missing or uses a different instance name, investigate that file first.

This check does not validate every configuration detail, but it quickly rules out a common class of instance-name inconsistencies.

6. A Hidden Problem: ONCONFIG Points to the Wrong File

One particularly easy mistake is an incorrect ONCONFIG value.

For example, the environment may contain:

export ONCONFIG=onconfig.gbaseserver
Enter fullscreen mode Exit fullscreen mode

But the actual configuration file may have been renamed:

onconfig.gbaseserver.bak
Enter fullscreen mode Exit fullscreen mode

The environment variable is set, but its value does not point to the intended configuration file.

This is why checking whether a variable exists is insufficient.

Verify the actual path:

echo "$ONCONFIG"
ls -l "$GBASEDBTDIR/etc/$ONCONFIG"
Enter fullscreen mode Exit fullscreen mode

A valid environment variable does not guarantee a valid configuration file.

7. Include All Three Files in the Delivery Baseline

GBase Database initialization scripts can generate the required configuration files automatically. During manual initialization, administrators may need to create and maintain them themselves.

Regardless of how the files are generated, verify their consistency after every configuration change.

I recommend including all three files in the database delivery baseline or configuration management process.

A few dozen lines of configuration can determine whether an instance starts correctly and whether clients can connect.

Also, assign clear ownership for maintaining these files. When different administrators independently modify profile, onconfig, and sqlhosts, configuration drift becomes much harder to identify.

A single owner, a documented baseline, and one consistency check can prevent many recurring connection and startup incidents.

For GBase Database(GBase 8s), remember the distinction: profile defines the environment, onconfig defines the instance, and sqlhosts defines the connection. Get these three files right before troubleshooting anything more complicated.

Top comments (0)