Five Acceptance Steps as a Script: GBase Database Deployment Validation

A successful installation does not necessarily mean a database is ready for use.

For GBase Database(GBase 8c), first-connection acceptance should verify more than whether the installation command returned successfully. Cluster health, listening ports, database connectivity, and basic read/write operations all need to be checked.

Instead of running these commands manually after every deployment, you can turn the process into a repeatable acceptance script.

This tutorial covers five essential steps for GBase Database deployment validation, along with a practical Bash script structure you can adapt to your environment.

Step 1: Verify the Installation Result

Start by checking the installation command output.

A successful installation returns:

{
  "ret": 0,
  "msg": "Success"
}

The script should verify the return code rather than simply checking whether the command produced output.

However, installation success is only the first checkpoint. It does not confirm that all database components are running or that clients can connect.

Step 2: Check Cluster Health

Use gha_ctl to inspect the cluster:

gha_ctl monitor all -l http://10.x.x.6:2379 -H

For GBase Database(GBase 8c), review four sections in the monitoring output:

• gha_server
• gtm
• coordinator
• datanode

The acceptance criteria should include:

1. No stopped or unstable instances.
2. Exactly one primary in each DN group.
3. All DCS nodes are healthy.
4. Expected cluster components are running.

Do not rely on a single overall status. A cluster may have running processes while its replication roles have not fully converged.

The script should parse the monitoring output by section rather than depending on fixed line numbers, because different deployment layouts can contain different numbers of instances.

Step 3: Verify Listening Ports

Next, check whether the expected database services are listening.

For example:

ss -tlnp | grep -E ':(5432|15432) '

The ports above are examples. Actual service ports should come from the deployment configuration.

There is another detail worth checking: the listening address.

A service bound to 127.0.0.1 can accept local connections but may reject connections from other hosts.

Therefore, automated database port validation should verify both:

• Whether the expected port is listening.
• Whether the listening address matches the intended network access configuration.

Checking only the port number can produce a false sense of readiness.

Step 4: Test Database Connectivity

Use gsql to execute a simple SQL statement:

gsql -d postgres -p 5432 -r -c "select 1"

The -c option executes SQL directly without entering interactive mode.

This makes the connection test easier to automate.

The script should evaluate the command's exit code:

• Exit code 0: connection and query execution succeeded.
• Non-zero exit code: connection or query execution failed.

This is more reliable for automation than waiting for an interactive prompt or manually checking the terminal.

For GBase Database(GBase 8c), this step confirms that the target database instance can accept a client connection and execute a basic query.

Step 5: Validate Read and Write Operations

A successful select 1 does not prove that ordinary write operations work.

The final acceptance step should execute a complete create-insert-select sequence.

For example:

gsql -d postgres -p 5432 -r -c "create database acceptance_tmp"

gsql -d acceptance_tmp -p 5432 -r -c "create table t1(id int)"

gsql -d acceptance_tmp -p 5432 -r -c "insert into t1 values (1)"

gsql -d acceptance_tmp -p 5432 -r -c "select * from t1"

Verify that:

• The temporary database is created successfully.
• The table is created successfully.
• The insert operation succeeds.
• The query returns the expected row.

After validation, remove the temporary database:

gsql -d postgres -p 5432 -r -c "drop database acceptance_tmp"

Use appropriate cleanup handling to avoid leaving temporary objects behind when an earlier step fails.

This final check provides stronger evidence that GBase Database is ready for basic application integration.

Building the Acceptance Script

The script itself does not need complicated logic.

A practical structure is to create one function for each acceptance step:

#!/bin/bash

LOG_FILE="acceptance_$(hostname)_$(date +%Y%m%d_%H%M%S).log"

exec > >(tee -a "$LOG_FILE") 2>&1

run_step() {
    local step_name="$1"
    shift

    echo "========== $step_name =========="

    if "$@"; then
        echo "[PASS] $step_name"
    else
        echo "[FAIL] $step_name"
        exit 1
    fi
}

check_install() {
    # Verify installation result
    return 0
}

check_cluster() {
    # Execute gha_ctl monitor and validate cluster state
    return 0
}

check_ports() {
    # Validate expected listening ports and addresses
    return 0
}

check_connection() {
    gsql -d postgres -p 5432 -r -c "select 1"
}

check_read_write() {
    # Create temporary database and table
    # Insert and verify test records
    # Clean up temporary objects
    return 0
}

run_step "Installation" check_install
run_step "Cluster Health" check_cluster
run_step "Listening Ports" check_ports
run_step "Database Connection" check_connection
run_step "Read/Write Validation" check_read_write

echo "========== ACCEPTANCE PASSED =========="

This is a structural skeleton, not a complete production-ready parser. The cluster, port, and read/write functions still need environment-specific validation logic.

Three implementation principles are particularly important:

1. Fail fast.

Stop when a critical acceptance step fails. Print the failed step instead of continuing and generating a long list of secondary errors.

2. Keep execution records.

Use tee to display output on screen and save it to a log file. Including the hostname and timestamp makes different acceptance runs easier to compare.

3. Reuse deployment configuration.

Do not hard-code ports, cluster names, and connection parameters. Read them from gbase.yml or the deployment specification.

When the cluster layout changes, the acceptance script should follow the configuration rather than maintaining a separate set of parameters.

Final Thoughts

The purpose of automated acceptance is not to create another complicated deployment tool.

It is to make database readiness measurable and repeatable.

For GBase Database(GBase 8c), the five steps cover the essential path from installation to basic usability:

1. Installation result
2. Cluster health
3. Listening ports
4. Database connectivity
5. Read/write validation

Running these checks after installation helps identify problems while the deployment window is still open.

A successful installation tells you that deployment finished. A successful acceptance script gives you evidence that the database is ready for the next stage.

Comments

[Alex Shev]

An acceptance script is strongest when every check produces both an expected value and a failure-handling branch. That way the handoff proves not just that the happy path passed, but who owns the next action when replication, permissions, or observability checks are wrong.