The installation command returned success, but gsql cannot connect.
This is a common first-connection problem when deploying GBase Database(GBase 8c). The database may be installed correctly, but that does not guarantee that every component is running, listening, or accessible.
The fastest way to troubleshoot is to check each layer in order instead of changing configuration randomly.
This guide covers four essential layers of GBase Database connection troubleshooting, plus one environment issue that is often mistaken for a connection failure.
Layer 1: Check Cluster Status
Start with the cluster monitoring command:
gha_ctl monitor all -l http://10.x.x.6:2379 -H
Review the four sections:
gha_servergtmcoordinatordatanode
Check whether the expected components are running.
Pay particular attention to stopped or unstable instances. If a component is not healthy, the connection failure may be a symptom of a cluster problem rather than a client configuration issue.
For a distributed deployment, also verify that each DN group has the expected primary and standby roles.
Troubleshooting rule: Fix cluster state before investigating client connectivity.
Layer 2: Verify the Listening Port
If the cluster components appear healthy, check whether the target service is listening.
For example:
ss -tlnp | grep 5432
Two situations are particularly common.
Case 1: The expected port is missing.
Possible causes include:
- The target instance is not running.
- The service uses a different port.
- The service failed to bind to the configured address.
Check the instance status and actual port configuration before changing anything.
Case 2: The port listens only on 127.0.0.1.
A local connection may work, but a remote client cannot access a service bound exclusively to the loopback interface.
Check the listening address as well as the port number.
For GBase Database(GBase 8c), the actual service port should be confirmed from the deployment configuration rather than assumed from an example.
Layer 3: Check Authentication and Access Control
If the port is listening and network connectivity is available, the next step is authentication and access control.
For PostgreSQL-compatible connection management in GBase Database, inspect pg_hba.conf in the relevant data directory.
This file defines which client addresses, users, and authentication methods are allowed to connect.
Review the following:
- Does the client's source IP belong to an allowed subnet?
- Is the requested database user covered by an applicable rule?
- Is the authentication method appropriate?
- Are the rules ordered correctly?
After modifying the file, reload the relevant database configuration using the supported procedure for your deployment.
Do not confuse authentication failures with connection refusal. They indicate different troubleshooting layers.
Layer 4: Verify Client Connection Parameters
If the cluster is running, the port is listening, and authentication rules are correct, verify the client parameters.
A typical gsql connection looks like this:
gsql -h <host> -p <port> -d <database> -U <user> -r
Check four parameters:
| Parameter | What to verify |
|---|---|
| Host | Correct CN or target service address |
| Port | Matches the configured listening port |
| Database | Database name exists |
| User | Correct account and privileges |
In a distributed GBase Database deployment, connect through the appropriate CN endpoint for normal application access.
Also distinguish primary and standby behavior. A standby may support read-only operations while rejecting writes, depending on its role and configuration.
A successful connection does not automatically mean every SQL operation is permitted.
Special Case: Installation Succeeded, but Commands Are Not Found
Sometimes the actual problem appears before the connection attempt.
For example:
gsql: command not found
This is not a database connection failure. It usually indicates that the required environment variables or executable paths have not been loaded.
If the environment configuration is already defined in .bashrc, run:
source ~/.bashrc
Alternatively, reconnect using the intended gbase account and verify the database environment.
Check that the executable path is available before continuing with connection troubleshooting.
Keep a Record of Every Layer
One final recommendation: record the output from each troubleshooting step.
A simple record can look like this:
| Check | Result | Evidence |
|---|---|---|
| Cluster status | Pass / Fail | gha_ctl monitor |
| Listening port | Pass / Fail | ss -tlnp |
| Authentication | Pass / Fail | Connection error / configuration |
| Client parameters | Pass / Fail |
gsql command |
This makes it easier to distinguish between two fundamentally different situations:
- Not running: The database component is not operating correctly.
- Running but unreachable: The component is running, but network, access control, or client parameters prevent a successful connection.
For GBase Database(GBase 8c), these distinctions save time because each failure points to a different troubleshooting direction.
Final Thoughts
A successful installation is only the beginning of database acceptance.
When the first gsql connection fails, follow a fixed sequence:
- Check cluster status.
- Verify listening ports and addresses.
- Inspect authentication and access control.
- Confirm client connection parameters.
- Check the execution environment if commands are unavailable.
Do not change multiple settings at once. Identify the failing layer, collect evidence, and then apply the appropriate fix.
GBase Database troubleshooting becomes much more predictable when every connection failure is investigated in the same order.
Top comments (1)
A connection guide becomes far more reusable when each symptom maps to a boundary: network reachability, listener state, credentials, client configuration, or cluster health. Capturing the expected command output at each step also helps operators distinguish a bad install from a bad application connection string.