TIL: GBase Database(GBase 8c) cluster_type Does Not Mean Node Count

I spent more time than I should have misreading one configuration parameter in GBase Database(GBase 8c): cluster_type.

It has exactly two values in the deployment configuration:

• multiple-nodes
• single-inst

At first glance, the names seem to describe the number of machines in a database deployment. They do not.

In GBase Database, multiple-nodes identifies a distributed architecture, while single-inst identifies a primary-standby architecture. Neither value directly tells you how many physical hosts are involved.

That distinction matters when configuring a new database environment.

1. Why a Single-Host Deployment Can Use multiple-nodes

Consider the minimal single-node deployment of GBase Database(GBase 8c).

It places all the main components on one host:

• gha_server
• DCS
• GTM
• CN
• DN

There is only one physical machine and no database replicas. Yet the configuration still declares:

env:
  cluster_type: multiple-nodes
  pkg_path: /home/gbase/gbase_package
  prefix: /home/gbase/gbase_db
  version: V6_S1.0.0_B20
  user: gbase
  port: 22
  third_ssh: false

Why?

Because physical host count and database architecture describe two different things.

The minimal topology retains the distributed architecture's component roles and deployment model. All components happen to run on the same machine, but that does not turn the architecture into primary-standby.

In other words:

One host does not automatically mean single-inst.

2. What Does single-inst Actually Mean?

In GBase Database(GBase 8c), single-inst refers to the primary-standby deployment form.

It is not simply a distributed cluster with fewer database instances or a smaller number of machines.

The two configuration values represent different architectural approaches:

Parameter	Architecture	Meaning
multiple-nodes	Distributed	Distributed database architecture, regardless of physical host count
single-inst	Primary-standby	Primary-standby deployment architecture

Understanding this distinction prevents a common configuration mistake: selecting single-inst simply because the deployment uses one physical host.

3. What Happens If You Misconfigure cluster_type?

The problem is not just terminology.

If you infer the configuration value from the number of machines, you may write single-inst for a minimal single-host distributed deployment.

Alternatively, you may assume that primary-standby is simply a distributed cluster running on one machine.

Both assumptions can lead to configuration errors.

These problems may surface during environment verification with:

gha_preinstall -i A

Or later during installation:

gha_ctl install

The installer expects the configuration to match the selected deployment architecture. Changing the parameter based on host count does not transform one architecture into another.

4. Use DN Groups and Replicas to Identify the Actual Topology

If cluster_type does not tell you the number of machines, what should you examine instead?

For the three official distributed deployment layouts of GBase Database(GBase 8c), two more useful indicators are:

1. Number of DN groups.
2. Number of replicas per DN group.

The three layouts can be summarized as follows:

Deployment Topology	DN Groups	Replicas per Group	Total DN Instances
Minimal single-node	1	1	1
Single-HA-group	1	3	3
Default distributed	2	3	6

These numbers reveal the actual data distribution and replication structure much more clearly than physical host count.

The minimal topology has one DN group and one replica. The single-HA-group topology has one DN group with three replicas. The default distributed topology has two DN groups with three replicas each.

This is why two deployments with the same number of hosts can have fundamentally different database architectures.

5. Do Not Build One Configuration by Deleting Lines from Another

One final distinction is worth emphasizing.

A primary-standby configuration is not a distributed configuration with fewer DN instances.

The component roles and installation workflows differ. Removing configuration lines until a distributed configuration appears small enough does not produce a valid primary-standby configuration.

A configuration may pass some preliminary checks and still fail during deployment because its architecture declaration and component definitions do not match.

For GBase Database deployment, start with the official configuration example corresponding to the intended topology. Then adjust the documented parameters for the actual environment.

Takeaway

My updated mnemonic for GBase Database(GBase 8c) is simple:

• multiple-nodes = distributed architecture, regardless of physical host count.
• single-inst = primary-standby architecture.
• DN group count and replicas per group = better indicators of distributed topology.

GBase Database defines deployment parameters by architecture, not by the number of machines.

Once you understand that distinction, the configuration manual becomes much easier to read — and one common installation mistake becomes much easier to avoid.

Have you ever encountered a configuration parameter whose name suggested something different from what it actually controlled?