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:
-
profiletells the shell which database environment and configuration files to use. -
onconfigdefines how the database instance operates. -
sqlhostsdefines 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
This file establishes the environment variables required by GBase Database.
In particular:
-
GBASEDBTSERVERidentifies the target instance. -
GBASEDBTDIRspecifies the database installation directory. -
ONCONFIGidentifies the instance configuration file. -
GBASEDBTSQLHOSTSidentifies the connection configuration file.
File 2: onconfig.gbaseserver
ROOTPATH /opt/GBASE/gbase/dbs/rootdbs
SERVERNUM 1
DBSERVERNAME gbaseserver
This file defines instance-level configuration.
For example:
-
ROOTPATHspecifies the root dbspace path. -
SERVERNUMidentifies the server number. -
DBSERVERNAMEspecifies 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
This file defines the connection entry for the instance.
The fields represent:
- Instance connection name
- Network protocol
- Server IP address
- 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
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
Then verify that the referenced files actually exist:
ls -l "$GBASEDBTDIR/etc/$ONCONFIG"
ls -l "$GBASEDBTSQLHOSTS"
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
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"
The expected output should include entries corresponding to:
GBASEDBTSERVER=gbaseserver
DBSERVERNAME gbaseserver
gbaseserver onsoctcp ...
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
But the actual configuration file may have been renamed:
onconfig.gbaseserver.bak
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"
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)