TIL: GBase Database gsql Ports Come from gbase.yml

The first connection to GBase Database(GBase 8c) often starts with port 5432. It appears in many examples, but it is not a universal port for every database component.

The actual service ports are defined in gbase.yml. Before connecting, you need to identify two things: which component you are connecting to and which port that component uses.

1. Understand CN and DN Service Ports

In common GBase Database deployment examples, the ports are assigned according to the component and cluster layout.

Typical examples include:

These are configuration examples, not universal defaults. Always verify the actual port assignments in your deployment's gbase.yml.

The key is to avoid assuming that every GBase Database instance listens on port 5432.

2. Connect Using gsql

A basic local connection looks like this:

gsql -d postgres -p 5432 -r 

The main connection parameters are:

• -d: Database name
• -p: Service port
• -U: Database user
• -h: Remote database host
• -r: Enable readline support

If the connection succeeds, you should see a prompt similar to:

postgres=# 

This indicates that the client has established a database session.

3. Troubleshoot Connection Failures in the Right Order

If the connection fails, do not immediately assume it is an authentication problem.

Check three things in sequence.

Step 1: Verify component state

Use the GBase Database monitoring command:

gha_ctl monitor all -l http://<DCS>:2379 -H 

Check the CN and DN sections, including their running states and primary/standby roles.

Step 2: Verify the listening port

Use:

ss -tlnp 

This shows listening TCP ports and their associated local addresses. Confirm that the expected database port is actually listening.

Step 3: Verify the listen address

A port listening only on 127.0.0.1 is not accessible through a remote network interface.

Check whether the service is listening on the address required by your application.

Only after confirming component state, port availability, and network binding should you move on to authentication and access-control checks.

4. Connect to the Correct Component

One more detail matters in a distributed GBase Database deployment: the target component's role.

For normal read/write operations, connect through an appropriate CN entry point or the current primary DN, depending on the intended connection path.

A standby DN is not equivalent to a primary. It may support read-only operations, while write operations can be rejected.

This is expected role behavior, not necessarily a database fault.

Always verify the component role before diagnosing a failed write as a connection problem.

5. Keep a Port Mapping Table in the Delivery Package

A port table is a small but valuable part of database deployment documentation.

Record:

• Component name
• Host or IP address
• Service port
• Primary or standby role, where applicable
• Intended connection purpose

Archive this table together with gbase.yml.

When another engineer takes over, a new node is added, or an incident occurs, the port mapping provides an immediate reference instead of forcing someone to reconstruct the configuration.

Key Takeaway

For GBase Database(GBase 8c), 5432 is an example, not a universal connection rule.

The correct gsql connection parameters come from the actual deployment configuration and component roles.

Check the component state, verify the listening port and address, and connect to the appropriate entry point. A documented port mapping makes first-connection testing and future troubleshooting much more predictable.