DEV Community

mmllllzcn
mmllllzcn

Posted on

TIL: Why `localhost` Can Break Your GBase Database sqlhosts Configuration

#gbase #database #数据库 #todayilearned

I was helping a colleague troubleshoot a GBase Database(GBase 8s) connection failure today and found a common configuration pitfall: using localhost in the sqlhosts file.

If your GBase Database instance is already On-Line but dbaccess still returns Can't connect to database server (25574), the sqlhosts configuration is one of the first things to check.

The Problem

After configuring GBase Database(GBase 8s), the instance looks healthy:

onstat -
Enter fullscreen mode Exit fullscreen mode

But connecting with dbaccess fails:

Can't connect to database server (25574)
Enter fullscreen mode Exit fullscreen mode

One possible cause is an incorrect server address in sqlhosts:

gbase01 onsoctcp localhost 9088
Enter fullscreen mode Exit fullscreen mode

It looks harmless, especially when the database server and client are on the same machine. But localhost can introduce protocol and address-resolution problems that are easy to overlook.

Why localhost Can Cause Problems

The sqlhosts file tells GBase Database(GBase 8s) how clients should communicate with a database server.

For TCP/IP connections, onsoctcp should point to a valid network address or hostname. Using localhost forces the connection toward the local loopback interface rather than the server's normal network address.

This becomes especially problematic when:

  • The client connects remotely
  • The server is bound to a specific network interface
  • /etc/hosts resolves the hostname unexpectedly
  • Firewall or network rules restrict loopback traffic

In other words, the database can be On-Line while the client still cannot reach it.

Recommended sqlhosts Configuration

Instead of localhost, use the server's actual IP address:

gbase01 onsoctcp 192.168.1.100 9088
Enter fullscreen mode Exit fullscreen mode

Or use a hostname that resolves correctly:

gbase01 onsoctcp gbase-server-01 9088
Enter fullscreen mode Exit fullscreen mode

Then verify the hostname:

getent hosts gbase-server-01
Enter fullscreen mode Exit fullscreen mode

This simple check can save a lot of troubleshooting time when configuring GBase Database.

How to Troubleshoot GBase Database Connections

First, check the active environment configuration:

onstat -g env | grep sqlhosts
Enter fullscreen mode Exit fullscreen mode

Then verify whether the database port is listening:

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

If you see:

127.0.0.1:9088
Enter fullscreen mode Exit fullscreen mode

the service is listening only on the loopback interface. A remote client will not be able to connect through that address.

If the port is listening on the server's network interface, continue checking firewall rules, hostname resolution, the sqlhosts entry, and the client connection parameters.

GBase Database sqlhosts: A Simple Rule

For GBase Database(GBase 8s) deployments, sqlhosts deserves attention during initial configuration and troubleshooting.

A practical rule is:

Use onsoctcp with a reachable IP address or correctly resolved hostname instead of relying on localhost.

A database being On-Line does not automatically mean that every client connection path is correctly configured.

If you're learning GBase Database(GBase 8s) administration, understanding sqlhosts, network protocols, ports, and hostname resolution is a good place to start.

Top comments (0)