KaiwuDB Docs

Download PDFSubmit Feedback

  • Upgrade Using Deployment Scripts
  • Upgrading with Deployment Scripts
    • Upgrading Standalone Instances
    • Upgrading Multi-Replica Clusters
    • Upgrading Single-Replica Clusters
  • Upgrade for Source Code Compilation
    • Prerequisites
    • Steps
  • Upgrade for Container Image Deployment
    • Upgrade Using Docker Compose
    • Upgrade Using Docker Commands

Database Upgrade

This section covers upgrade procedures for KWDB database across different deployment scenarios, including upgrades using deployment scripts and container images.

Before upgrading, carefully review all precautions and select the appropriate upgrade method based on your deployment approach.

Upgrade Using Deployment Scripts

Upgrading with Deployment Scripts

Script-based upgrades are the most common method for KWDB instances installed through deployment scripts. Upgrade procedures vary based on your deployment topology: standalone instances, multi-replica clusters, and single-replica clusters each require different approaches. The available upgrade methods depend on your specific deployment type:

Note

  • Direct downgrades to the previous version are not supported after an upgrade. To perform a downgrade, you must first uninstall the current version, then install the original version of KWDB. Afterward, restore the data from the backup created before uninstallation. For instructions, see Uninstall Standalone Databases or Uninstall Clusters.
  • KWDB supports upgrading from any previous version to the latest version through import-export method. For specific operations, see Data Export and Data Import. Note: When upgrading from version 2.x, the exported meta.sql file contains PARTITION INTERVAL syntax for time-series tables. This syntax has been deprecated in version 3.1.0 (it remains supported for time-series databases). You must manually remove this syntax from the file before importing; failure to do so will cause the import to fail. Additionally, upgrading via the import-export method may impact high availability in multi-replica clusters.

Upgrading Standalone Instances

If any upgrade errors occur—such as KWDB not being installed, KWDB still running, incorrect version, or incorrect deployment method—the system aborts the upgrade and displays the relevant error messages.

If the upgrade fails during new version installation, the system retains the data directory, certificates, and configuration files while removing the new version files from the node. You can then choose to manually install either the new or the old version.

Prerequisites

  • KWDB is installed on the target node.
  • The data directory is backed up.
  • You have obtained the new version package.
  • You have one of the following user permissions:
    • Root user access
    • Regular user with sudo privileges (users with passwordless sudo won't need to enter passwords during upgrade; others will be prompted when needed)
    • For container deployment: Regular user in the docker group (add with sudo usermod -aG docker $USER)

Steps

  1. Copy the new version package to the target node and extract the contents.

  2. Check if KWDB is stopped. If the service is still running, stop it using systemctl stop kaiwudb.

    systemctl status kaiwudb

  3. Navigate to the directory of the new version package.

  4. Run the local upgrade command:

    ./deploy.sh upgrade -l

    or

    ./deploy.sh upgrade --local

    If the upgrade succeeds, the console displays:

    UPGRADE COMPLETED: KaiwuDB has been upgraded successfully!

  5. Start KWDB:

    systemctl start kaiwudb

  6. Verify that the service is running:

    systemctl status kaiwudb

Upgrading Multi-Replica Clusters

During the upgrade process, compression and lifecycle operations on the upgraded nodes may fail temporarily but resume once the upgrade completes. If upgrade errors occur—such as KWDB not being installed, unhealthy or unavailable nodes, incorrect version, or incorrect deployment method—the system aborts the upgrade and displays the relevant error messages.

Preparing for Upgrade

Steps

  1. Ensure that the client communicates with multiple nodes to avoid communication interruption when upgrading a single node.

  2. Check the cluster status:

    1. Check node status:

      • Deployment script:

        kw-status

      • kwbase command:

        <kwbase_path>/kwbase node status [--host=<ip:port>] [--insecure | --certs-dir=<path>]

    2. Check replica status:

      SELECT sum((metrics->>'ranges.unavailable')::DECIMAL)::INT AS ranges_unavailable,
sum((metrics->>'ranges.underreplicated')::DECIMAL)::INT As ranges_underreplicated
FROM kwdb_internal.kv_store_status;

  3. Check for ongoing schema changes or bulk import jobs using the SHOW JOBS SQL command.

  4. Use the SELECT * FROM kwdb_internal.ranges SQL command to check if leaseholders and replicas are evenly distributed across the nodes in the cluster.

  5. Back up the cluster. If the upgrade fails, you can restore the cluster from the backup.

Executing Upgrade

Perform the upgrade on each node in the cluster, one at a time. After each node rejoins the cluster and its version and status are verified, proceed to upgrade the next node.

Prerequisites

  • KWDB is installed on the target node.
  • The node is available (both is_available and is_live are true).
  • The user data directory is backed up.
  • You have obtained the new version package.
  • You have one of the following user permissions:
    • Root user access
    • Regular user with sudo privileges (users with passwordless sudo won't need to enter passwords during upgrade; others will be prompted when needed)
    • For container deployment: Regular user in the docker group (add with sudo usermod -aG docker $USER)

Steps

  1. Copy the new version installation package to the target node and extract the contents.

  2. Check if KWDB is stopped. If the service is still running, stop it using systemctl stop kaiwudb.

    systemctl status kaiwudb

  3. Navigate to the directory of the new version installation package.

  4. Run the local upgrade command:

    ./deploy.sh upgrade -l

    or

    ./deploy.sh upgrade --local

    If the upgrade succeeds, the console displays:

    UPGRADE COMPLETED: KaiwuDB has been upgraded successfully!

  5. Start KWDB:

    systemctl start kaiwudb

  6. Verify that the service is running:

    systemctl status kaiwudb

Upgrading Single-Replica Clusters

If upgrade errors occur—such as KWDB not being installed, KWDB still running, incorrect version, or incorrect deployment method—the system aborts the upgrade and displays the relevant error messages.

If the upgrade fails during new version installation, the system retains the data directory, certificates, and configuration files while removing the new version installation files from the node. You can then choose to manually install either the new or the old version.

Prerequisites

  • KWDB is installed on all target nodes.
  • The data directory is backed up on all nodes.
  • You have obtained the new version package.
  • You have one of the following user permissions:
    • Root user access
    • Regular user with sudo privileges (users with passwordless sudo won't need to enter passwords during upgrade; others will be prompted when needed)
    • For container deployment: Regular user in the docker group (add with sudo usermod -aG docker $USER)

Steps

  1. Stop KWDB on all nodes in the cluster:

    systemctl stop kaiwudb

  2. Perform the following upgrade operations on each node:

    1. Copy the new version package to the node and extract the contents.

    2. Navigate to the directory of the new version package.

    3. Run the local upgrade command:

      ./deploy.sh upgrade -l

      or

      ./deploy.sh upgrade --local

      If the upgrade succeeds, the console displays:

      UPGRADE COMPLETED: KaiwuDB has been upgraded successfully!

  3. After all nodes are upgraded, execute the following commands on each node to start the database:

    1. Start KWDB:

      systemctl start kaiwudb

    2. Verify that the service is running:

      systemctl status kaiwudb

Upgrade for Source Code Compilation

For KWDB instances installed by compiling from source code, you can upgrade by compiling the new version. This upgrade method is suitable for users with specific customization requirements who have compilation and deployment experience.

Prerequisites

Steps

  1. Compile the new version following the KWDB compilation documentationopen in new window.
  2. Start the service using the same startup command as the previous version.
  3. Verify that the service is running as expected.

Upgrade for Container Image Deployment

For KWDB deployed using Docker container images, upgrades are performed by updating the container image.

This section covers two upgrade methods:

  • Upgrade using Docker Compose
  • Upgrade using Docker commands

Upgrade Using Docker Compose

Prerequisites

  • Data and configuration files have been backed up.
  • The new version container image has been obtained.

Steps

  1. Load the new container image:

    docker load < KaiwuDB.tar

  2. Stop and remove existing containers:

    docker-compose down

  3. Remove the old version image:

    docker rmi ${image_name}

  4. Update the image version in docker-compose.yml.

  5. Start KWDB with the new version:

    docker-compose up -d

Upgrade Using Docker Commands

Prerequisites

  • Data and configuration files have been backed up.

Steps

  1. Stop the KWDB container. The container name is the one specified by the --name parameter when running the container.

       docker stop <kwdb-container>

  2. Remove the container:

       docker rm <kwdb-container>

  3. Obtain the new version image:

    • Pull from image repository:

         docker pull kwdb/kwdb:<new_version_number>

    • Import from local file:

         docker load < KaiwuDB.tar

  4. Start the new version container. All parameters should remain consistent with the original container except for the image name.

    • Insecure mode:

      docker run -d --privileged --name kwdb \
      --ulimit memlock=-1 \
      --ulimit nofile=$max_files \
      -p $db_port:26257 \
      -p $http_port:8080 \
      -v /var/lib/kaiwudb:/kaiwudb/deploy/kwdb-container \
      --ipc shareable \
      -w /kaiwudb/bin \
      <kwdb_image> \
      ./kwbase start-single-node \
      --insecure \
      --listen-addr=0.0.0.0:26257 \
      --http-addr=0.0.0.0:8080 \
      --store=/kaiwudb/deploy/kwdb-container

    • Secure mode:

      docker run -d --privileged --name kwdb \
    --ulimit memlock=-1 \
    --ulimit nofile=$max_files \
    -p $db_port:26257 \
    -p $http_port:8080 \
    -v /etc/kaiwudb/certs:<certs_dir> \
    -v /var/lib/kaiwudb:/kaiwudb/deploy/kwdb-container \
    --ipc shareable \
    -w /kaiwudb/bin \
    <kwdb_image> \
    ./kwbase start-single-node \
    --certs-dir=<certs_dir> \
    --listen-addr=0.0.0.0:26257 \
    --http-addr=0.0.0.0:8080 \
    --store=/kaiwudb/deploy/kwdb-container