kwbase Command Reference

kwbase start

Description

The kwbase start command is used to start a KWDB node.

Command Syntax

./kwbase start [flags]

Parameters

Parameter Details

Parameter	Description
`--advertise-addr`	The IP address or hostname used by the node to communicate with other nodes, in the format `<addr/host>[:<port>]`. If a hostname is used, it must be resolvable. If an IP address is used, it must be accessible. For IPv6 addresses, use the `[...]` notation, for example: `[::1]:26257` or `[fe80::f6f2::1]:26257`. If not specified, the value of `--listen-addr` is used by default. If only part of the parameter value is specified, the unspecified parts use the corresponding values from `--listen-addr`. The effect of this parameter depends on the combination with `--listen-addr`. For example, if the port number differs from the one used in `--listen-addr`, port forwarding needs to be configured. Default value: the value of `--listen-addr`.
`--attrs`	An ordered list of node attributes separated by colons (`:`). Node attributes can be arbitrary strings that specify machine capabilities. Machine capabilities may include specialized hardware or core counts (for example, gpu, x16c). For example, `--attrs=x16c:gpu`.
`--background`	Start the KWDB node in the background. This is similar to adding `&` at the end of the command line directly. However, when starting the KWDB node with the `--background` option, control is not returned to the shell until the KWDB node is ready to accept requests. Note The `--background` parameter is suitable for short-lived running and testing services. Currently, since it cannot be fully detached from the current terminal, it is not recommended for long-running services. In such cases, it is recommended to use a service manager or tools like daemon(8).
`--brpc-addr`	The brpc communication address between timing engines, in the format `<host>:<port>` or `:<port>`: - The port number must be included, otherwise the system reports an error `failed to start server: --brpc-addr's port not specified`. - The IP address can be omitted; if not specified, the system will use the IP from `--advertise-addr` or `--listen-addr` in order. Note `--advertise-addr` and `--brpc-addr` are both inter-node communication addresses, so ensure network connectivity between all nodes. It is recommended to use the format `--brpc-addr=:<port>`, and the system will automatically obtain the IP address.
`--buffer-pool-size`	AE executor buffer pool size. Default value: 4096
`--cache`	The cache size, shared across multiple physical storage devices. The parameter value supports precise memory values (in bytes), decimal values (converted to percentage values), and percentage values: - `--cache=.25` - `--cache=25%` - `--cache=1000000000`: 1000000000 bytes - `--cache=1GB`: 1000000000 bytes - `--cache=1GiB`: 1073741824 bytes Default value: `128 MiB` Note If using the format with a percentage sign (%), ensure the system can properly recognize the escaped percentage sign (%). For example, in some configuration files, the percentage sign (%) may be recognized as a comment character. Therefore, it is recommended to use decimal values.
`--certs-dir`	The path to the secure certificates directory, used to access and verify clusters deployed in secure mode. Default value: `${HOME}/.kaiwudb-certs/`
`-h`, `--help`	Help information for the `kwbase start` command.
`--http-addr`	The IP address or hostname for the Admin interface. IPv6 addresses use the `[...]` notation, for example: `[::1]:8080` or `[fe80::f6f2::1]:8080`. Default value: same as `--listen-addr` parameter, with port `8080`.
`--import-path`	The path where import files are located.
`--insecure`	Start the cluster in insecure mode. If not specified, the cluster starts in secure mode.
`-j, --join`	The address for the node to join the cluster. During initialization, you need to specify the addresses and ports of 3-5 nodes in the cluster, then execute the `kwbase init` command to start the cluster. If this parameter is not specified, a single-node cluster is started. In this case, you do not need to execute the `kwbase init` command. To add new nodes to an existing cluster, you can use this parameter to specify the addresses and ports of 3-5 nodes in the cluster.
`--listen-addr`	The IP address/hostname and port for listening to connections from other nodes and clients. IPv6 addresses use the `[...]` notation, for example: `[::1]` or `[fe80::f6f2::1]`. The effect of this parameter depends on the combination with `--advertise-addr`. If `--advertise-addr` is not specified, it uses the `canonical hostname` to communicate with other nodes. Default value: listen on all IP addresses, port `26257`.
`--log-dir`	Enable logging and record logs in the specified directory. When `--log-dir` is set to an empty string (`--log-dir=""`), it means logging is disabled.
`--log-dir-max-size`	When the total size of all log files reaches the threshold, KWDB will delete the earliest log. Default value: `100 MiB`
`--log-file-verbosity`	Output logs at and above the specified level to the log file, for example: `--log-file-verbosity=WARNING`. Default value: `INFO`
`--max-disk-temp-storage`	The maximum storage space available on disk for temporary data from SQL queries that exceed the memory budget. This ensures that JOIN, SORT, and other memory-intensive SQL operations can spill intermediate results to disk. This value can be a percentage or an exact value (in bytes), for example: - `--max-disk-temp-storage=.25` - `--max-disk-temp-storage=25%` - `--max-disk-temp-storage=10000000000`: 1000000000 bytes - `--max-disk-temp-storage=1GB`: 1000000000 bytes - `--max-disk-temp-storage=1GiB`: 1073741824 bytes. These temporary files are stored in a subdirectory of the first storage directory specified by the `--store` parameter. Default value: `32GiB` Note If using the format with a percentage sign (%), ensure the system can properly recognize the escaped percentage sign (%). For example, in some configuration files, the percentage sign (%) may be recognized as a comment character. Therefore, it is recommended to use decimal values.
`--max-offset`	The maximum clock offset allowed for the cluster. If the observed clock offset exceeds this limit, the server will crash to minimize the possibility of reading inconsistent data. Increasing this value will prolong failure recovery time and increase the frequency of uncertainty-based read restarts. Note that this value must be consistent across all nodes in the cluster. To change this value, you must stop all nodes in the cluster and then restart them with the new value. Default value: `500ms`
`--max-sql-memory`	The maximum memory space available for temporary data cached by SQL queries, including prepared queries and intermediate data rows during query execution. This value can be a percentage or an exact value (in bytes), for example: - `--max-sql-memory=.25` - `--max-sql-memory=25%` - `--max-sql-memory=10000000000`: 1000000000 bytes - `--max-sql-memory=1GB`: 1000000000 bytes - `--max-sql-memory=1GiB`: 1073741824 bytes. These temporary files are stored in the `--temp-dir` folder. Note If using the format with a percentage sign (%), ensure the system can properly recognize the escaped percentage sign (%). For example, in some configuration files, the percentage sign (%) may be recognized as a comment character. Therefore, it is recommended to use decimal values.
`--restful-port`	RESTful port, valid range: `[0, 65535]`. Default value: `8080`
`--restful-timeout`	RESTful API timeout. Default value: 60
`--sql-audit-dir`	The location of the security audit log. By default, SQL audit logs are written to the same directory as other logs generated by KWDB.
`-s, --store`	The storage device path for storing database data. Supports specifying device attributes and space size simultaneously. If using multiple devices to store data, use the format `--store=/mnt/ssd01 --store=/mnt/ssd02`.
`--thread-pool-size`	AE executor thread pool size. Default value: 10
`--upgrade-complete`	Node upgrade completed.

Examples

The following example starts a multi-node KWDB cluster.

TLS secure mode

The following example assumes certificates have been generated for the root user. For more details about generating certificates, see the Examples section of the kwbase cert command.

./kwbase start \
--certs-dir=/root/certs \
--store=/opt/node1 \
--advertise-addr=<node1_address>:26257 \
--brpc-addr=:27257 \
--listen-addr=<node1_address>:26257 \
--http-addr=<node1_address>:8080 \
--join=<node1_address>,<node2_address>,<node3_address> \
--cache=.25 \
--max-sql-memory=.25 \
--background

Insecure mode

./kwbase start \
--insecure \
--store=/opt/node1 \
--advertise-addr=<node1_address>:26257 \
--brpc-addr=:27257 \
--listen-addr=<node1_address>:26257 \
--http-addr=<node1_address>:8080 \
--join=<node1_address>,<node2_address>,<node3_address> \
--cache=.25 \
--max-sql-memory=.25 \
--background

kwbase start-single-replica

Description

The kwbase start-single-replica command is used to start a single-replica node.

Command Syntax

./kwbase start-single-replica [flags]

Parameters

Parameter Details

Parameter	Description
`--advertise-addr`	The IP address or hostname used by the node to communicate with other nodes. Format: `<addr/host>[:<port>]`. - Hostname must be resolvable - IP address must be accessible - IPv6 addresses use `[...]` notation, like `[::1]:26257` - If not specified, defaults to the value of `--listen-addr` - If only part of the value is specified, the unspecified part uses the corresponding value from `--listen-addr` - Works with `--listen-addr`, port forwarding is needed when ports differ Default value: the value of `--listen-addr`
`--attrs`	Node attribute list, separated by colons (`:`). Can be arbitrary strings to specify machine capabilities, such as specialized hardware or core counts. Example: `--attrs=x16c:gpu`
`--background`	Start the node in the background. Similar to adding `&` at the end of the command line, but waits for the node to be ready before returning control. Note: Suitable for short-term testing, not recommended for long-term running. For long-term running, use a service manager or daemon(8)
`--brpc-addr`	brpc communication address between timing engines. Format: `<host>:<port>` or `:<port>`. - Port number must be specified - IP can be omitted; if not specified, uses the IP from `--advertise-addr` or `--listen-addr` Note: Both `--advertise-addr` and `--brpc-addr` are inter-node communication addresses, ensure network connectivity. Recommended to use the `:<port>` format
`--buffer-pool-size`	AE executor buffer pool size. Default value: 4096
`--cache`	Cache size shared across multiple storage devices. Supports the following formats: - Decimal: `--cache=.25` - Percentage: `--cache=25%` - Bytes: `--cache=1000000000` - GB: `--cache=1GB` (1000000000 bytes) - GiB: `--cache=1GiB` (1073741824 bytes) Default value: `128 MiB` Note: Recommended to use decimal format to avoid percentage escaping issues
`--certs-dir`	Secure certificates directory path. Default value: `${HOME}/.kaiwudb-certs/`
`-h`, `--help`	Display help information
`--http-addr`	IP address or hostname for the Admin interface. IPv6 uses `[...]` notation. Default value: same as `--listen-addr`, port 8080
`--import-path`	Import file path
`--insecure`	Start in insecure mode. Secure mode is used if not specified
`-j`, `--join`	Node address to join the cluster. During initialization, 3-5 node addresses and ports need to be specified. Starts a single-node cluster if not specified
`--listen-addr`	Listening address for receiving connections from other nodes and clients. IPv6 uses `[...]` notation. Default value: listen on all IPs, port 26257
`--log-dir`	Log directory. Set to empty string to disable logging
`--log-dir-max-size`	Maximum total size of log files; deletes oldest logs when exceeded. Default value: `100 MiB`
`--log-file-verbosity`	Log file recording level. Default value: `INFO`
`--max-offset`	Maximum allowed clock offset. Server crashes if exceeded. Must be consistent across all nodes. Default value: `500ms`
`--max-sql-memory`	Maximum memory for SQL query temporary data. Supports the same formats as `--cache`. Data is stored in the `--temp-dir` directory
`--restful-port`	RESTful port. Range: [0,65535]. Default value: 8080
`--restful-timeout`	RESTful API timeout. Default value: 60
`--sql-audit-dir`	SQL audit log directory. Default is the same directory as other logs
`-s`, `--store`	Data storage path. Can specify multiple: `--store=/mnt/ssd01 --store=/mnt/ssd02`
`--thread-pool-size`	AE executor thread pool size. Default value: 10
`--upgrade-complete`	Mark node upgrade as complete

Examples

The following example starts a single-replica node.

./kwbase start-single-replica \
--insecure \
--store=/opt/node1 \
--advertise-addr=<node1_address>:26257 \
--brpc-addr=:27257 \
--listen-addr=<node1_address>:26257 \
--http-addr=<node1_address>:8080 \
--join=<node1_address>

kwbase start-single-node

Description

The kwbase start-single-node command is used to start a single-node cluster.

Command Syntax

./kwbase start-single-node [flags]

Parameters

Parameter Details

Parameter	Description
`--attrs`	Node attribute list, separated by colons (`:`). Can be arbitrary strings to specify machine capabilities, such as specialized hardware or core counts. Example: `--attrs=x16c:gpu`
`--background`	Start the node in the background. Similar to adding `&` at the end of the command line, but waits for the node to be ready before returning control. Note: Suitable for short-term testing, not recommended for long-term running. For long-term running, use a service manager or daemon(8)
`--buffer-pool-size`	AE executor buffer pool size. Default value: 4096
`--cache`	Cache size shared across multiple storage devices. Supports the following formats: - Decimal: `--cache=.25` - Percentage: `--cache=25%` - Bytes: `--cache=1000000000` - GB: `--cache=1GB` (1000000000 bytes) - GiB: `--cache=1GiB` (1073741824 bytes) Default value: `128 MiB` Note: Recommended to use decimal format to avoid percentage escaping issues
`--certs-dir`	Secure certificates directory path. Default value: `${HOME}/.kaiwudb-certs/`
`-h`, `--help`	Help information for the `kwbase start-single-node` command
`--http-addr`	IP address or hostname for the Admin interface. IPv6 uses `[...]` notation. Default value: same as `--listen-addr`, port 8080
`--import-path`	Import file path
`--insecure`	Start in insecure mode. Secure mode is used if not specified
`--listen-addr`	Listening address for receiving connections from other nodes and clients. IPv6 uses `[...]` notation. Default value: listen on all IPs, port 26257
`--log-dir`	Log directory. Set to empty string to disable logging
`--log-dir-max-size`	Maximum total size of log files; deletes oldest logs when exceeded. Default value: `100 MiB`
`--log-file-verbosity`	Log file recording level. Default value: `INFO`
`--max-disk-temp-storage`	Maximum disk storage for SQL query temporary data. Supports the following formats: - Decimal: `--max-disk-temp-storage=.25` - Percentage: `--max-disk-temp-storage=25%` - Bytes: `--max-disk-temp-storage=10000000000` - GB: `--max-disk-temp-storage=1GB` - GiB: `--max-disk-temp-storage=1GiB` Temporary files are stored in the first `--store` directory. Default value: `32GiB` Note: Recommended to use decimal format to avoid percentage escaping issues
`--max-sql-memory`	Maximum memory space for SQL query temporary data. Supports the following formats: - Decimal: `--max-sql-memory=.25` - Percentage: `--max-sql-memory=25%` - Bytes: `--max-sql-memory=10000000000` - GB: `--max-sql-memory=1GB` - GiB: `--max-sql-memory=1GiB` Temporary files are stored in the `--temp-dir` directory. Note: Recommended to use decimal format to avoid percentage escaping issues
`--restful-port`	RESTful port. Range: [0,65535]. Default value: 8080
`--restful-timeout`	RESTful API timeout. Default value: 60
`--sql-audit-dir`	SQL audit log directory. Default is the same directory as other logs
`-s`, `--store`	Data storage path. Can specify multiple: `--store=/mnt/ssd01 --store=/mnt/ssd02`
`--thread-pool-size`	AE executor thread pool size. Default value: 10
`--upgrade-complete`	Mark node upgrade as complete

Examples

The following example starts a single-node KWDB cluster.

TLS secure mode

The following example assumes certificates have been generated for the root user. For more details about generating certificates, see the Examples section of the kwbase cert command.
```
./kwbase start-single-node \
--certs-dir=/root/certs \
--listen-addr=0.0.0.0:26257 \
--advertise-addr=127.0.0.1:26257 \
--http-addr=0.0.0.0:8080 \
--store=/kaiwudb/deploy/kaiwudb
```

Insecure mode

./kwbase start-single-node \
--insecure \
--listen-addr=0.0.0.0:26257 \
--advertise-addr=127.0.0.1:26257 \
--http-addr=0.0.0.0:8080 \
--store=/kaiwudb/deploy/kaiwudb

kwbase init

Description

The kwbase init command is used to initialize a KWDB cluster.

Command Syntax

./kwbase init [flags]

Parameters

Parameter Details

Parameter	Description
`--certs-dir`	The path to the secure certificates directory, used to access and verify clusters deployed in secure mode. Default value: `${HOME}/.kaiwudb-certs/`
`-h`, `--help`	Help information for the `kwbase init` command.
`--host`	The KWDB node to connect to. Supports IP address/hostname, in the format `<addr/host>[:<port>]`. - Default port is 26257 if not specified - IPv6 addresses use `[...]` notation, like `[::1]:26257` Environment variable: `KWBASE_HOST`
`--insecure`	Start the cluster in insecure mode. Secure mode is used if not specified.
`--url`	The connection URL, in the format `postgresql://[user[:passwd]@]host[:port]/[db][?parameters...]` Example: postgresql://myuser@localhost:26257/mydb If not specified, uses connection parameters such as host, port, user, database, insecure, certs-dir. Environment variable: `KWBASE_URL`

Examples

The following example assumes KWDB has been started. For more details, see the Examples section of the kwbase start command.

You can execute the kwbase init command on any node in the cluster.

./kwbase init \
--certs-dir=/root/certs \
--host=<address_of_any_node>

kwbase cert

Description

The kwbase cert command is used to generate Certificate Authority (CA), node, and client certificates.

Command Syntax

./kwbase cert <subcommand> [flags]

create-ca

./kwbase cert create-ca --certs-dir=<path-to-kaiwudb-certs-dir> --ca-key=<path-to-ca-key> [flags]

create-client-ca

./kwbase cert create-client-ca --certs-dir=<path-to-kaiwudb-certs-dir> --ca-key=<path-to-client-ca-key> [flags]

create-node

./kwbase cert create-node --certs-dir=<path-to-kaiwudb-certs-dir> --ca-key=<path-to-ca-key> <host1> <host2> ... <hostN> [flags]

create-client

./kwbase cert create-client --certs-dir=<path-to-kaiwudb-certs-dir> --ca-key=<path-to-ca-key> <username> [flags]

list
```
./kwbase cert list [flags]
```

Subcommands

Subcommand	Description
`create-ca`	Generate CA certificate and key.
`create-client-ca`	Generate client CA certificate and key.
`create-node`	Generate node certificate and key.
`create-client`	Generate client certificate and key.
`list`	View certificates in the `--cert-dir` directory.

Parameters

Parameter Details

Parameter	Description	Supported Commands
`--allow-ca-key-reuse`	Use an existing CA key.	- `kwbase cert create-ca` - `kwbase cert create-client-ca`
`--ca-key`	The path to the CA key. Environment variable: `KWBASE_CA_KEY`	- `kwbase cert create-ca` - `kwbase cert create-client-ca` - `kwbase cert create-node` - `kwbase cert create-client`
`--cert-principal-map`	A comma-separated list of `<cert-principal>:<db-principal>` mappings that allows mapping principals in certificates to database principals, such as nodes, root, or any SQL user. This applies when the certificate management system has restrictions on the `Subject.CommonName` or `SubjectAlternateName` fields in certificates (for example, not allowing node or root as `CommonName`). If there are multiple mappings for the same certificate principal, the last specified mapping takes precedence. Principals not specified in the mapping are passed through as-is. If the database principal name is contained in the mapped `CommonName` or DNS-type `SubjectAlternateName` field, the certificate is allowed to authenticate for the database principal.	- `kwbase cert create-ca` - `kwbase cert create-client-ca` - `kwbase cert create-node` - `kwbase cert create-client` - `kwbase cert list`
`--certs-dir`	The path to the secure certificates directory, used to access and verify clusters deployed in secure mode. Default value: `${HOME}/.kaiwudb-certs/`	- `kwbase cert create-ca` - `kwbase cert create-client-ca` - `kwbase cert create-node` - `kwbase cert create-client` - `kwbase cert list`
`-h`, `--help`	Help information for the command.	- `kwbase cert` - `kwbase cert create-ca` - `kwbase cert create-client-ca` - `kwbase cert create-node` - `kwbase cert create-client` - `kwbase cert list`
`--key-size`	The size of the CA, node, and client certificate keys (in bits). Default value: 2048 bits	- `kwbase cert create-ca` - `kwbase cert create-client-ca` - `kwbase cert create-node` - `kwbase cert create-client`
`--lifetime`	The lifetime of the certificate. Default value: `43920h0m0s`	- `kwbase cert create-ca` - `kwbase cert create-client-ca` - `kwbase cert create-node` - `kwbase cert create-client`
`--overwrite`	Overwrite existing certificate and key files.	- `kwbase cert create-ca` - `kwbase cert create-client-ca` - `kwbase<br/>-` cert create-node`kwbase cert create-client`

Examples

Create the /opt/certs and /opt/my-safe-directory directories.
```
mkdir /opt/certs
mkdir /opt/my-safe-directory
```
- /opt/certs: Used to store the generated CA certificate and all node and client certificate and key files, some of which will be transferred to node machines.
- /opt/my-safe-directory: Used to store the generated CA key file, used when creating certificates and keys for nodes and users.
Create the CA certificate and key.
```
./ kwbase cert create-ca \
--certs-dir=/opt/certs \
--ca-key=/opt/my-safe-directory/ca.key
```
It is recommended to back up the generated CA certificate and key pair.

Create the certificate and key for the first node in the cluster.

./kwbase cert create-node <IP_address_of_node1> [<node1_hostname>]   [<other_common_names_for_ node1>] localhost 127.0.0.1 [<load_balancer_IP_address>]   [<load_balancer hostname>] [<other_common_names_for_load_balancer>] \
--certs-dir=/opt/certs \
--ca-key=/opt/my-safe-directory/ca.key

::: warning Note

The node IP address is the internal or external IP address used for generating certificates. Example:

./kwbase cert create-node 117.73.10.12 localhost   127.0.0.1 \
--certs-dir=/opt/certs \
--ca-key=/opt/my-safe-directory/ca.key

:::

Transfer the CA certificate, node certificate, and key to the first node.

ssh <username>@<node1_address>   "mkdir /root/certs"
scp /opt/certs/ca.crt /opt/certs/node.crt /opt/certs/node.key   <username>@<node1_address>:/root/certs

Delete the local node certificate and key.

rm /opt/certs/node.crt /opt/certs/node.key

Repeat steps 3-5 to create certificates and keys for other nodes in the cluster.

Create the client certificate and key for the root user.

./kwbase cert create-client root   \
--certs-dir=/opt/certs \
--ca-key=/opt/my-safe-directory/ca.key

Transfer the certificate and key to the machine where KWDB commands are executed, which can be a node inside or outside the cluster. Machines with certificates can execute KWDB commands using the root account and access the cluster through that node.
```
ssh <username>@<workload address>   "mkdir /root/certs"
scp /opt/certs/ca.crt /opt/certs/client.root.crt   /opt/certs/client.root.key <username>@<workload   address>:/root/certs
```
::: warning Note

If you need to run KWDB client commands on other machines in the future, you need to copy the root user's certificate and key to that node. Only nodes that have the root user's certificate and key can access the cluster. :::

kwbase sql

Description

The kwbase sql command is used to open an interactive SQL Shell.

Command Syntax

./kwbase sql [flags]

Parameters

Parameter Details

Parameter	Description
`--cert-principal-map`	A comma-separated list of `<cert-principal>:<db-principal>` mappings. Used to map certificate principals to database principals (such as nodes, root, or other SQL users). Applies when the certificate system has restrictions on `Subject.CommonName` or `SubjectAlternateName` fields. When multiple mappings exist, the last one takes precedence. Unmapped principals are passed through as-is. The database principal name must be contained in the mapped `CommonName` or DNS-type `SubjectAlternateName` field.
`--certs-dir`	The path to the secure certificates directory, used to access and verify clusters deployed in secure mode. Default value: `${HOME}/.kaiwudb-certs/`
`-d`, `--database`	The name of the database to connect to. Environment variable: `KWBASE_DATABASE`
`--debug-sql-cli`	Simplify SQL CLI for debugging. Echo SQL statements, remove database name and transaction status from prompts, making behavior independent of transaction state.
`--echo-sql`	Display SQL statements implicitly sent by the command line tool.
`-e`, `--execute`	Execute SQL statements and exit. Can be used multiple times, supporting multiple statements separated by semicolons. Exits with a non-zero status code on error. Results are output to standard output.
`--format`	Set the table display format: - `tsv` - `csv` - `table` - `records` - `sql` - `raw` - `html` Non-interactive defaults to `tsv`, interactive defaults to `table`. Default value: `table`
`-h`, `--help`	Display help information for the `kwbase sql` command.
`--insecure`	Start the cluster in insecure mode. Secure mode is used by default.
`--safe-updates`	Disable SQL statements that may have unexpected side effects (such as DELETE/UPDATE without WHERE clause). Enabled by default (`true`). Can be disabled with `SET sql_safe_updates = FALSE`.
`--set`	Set client configuration parameters before starting the SQL Shell.
`--url`	The connection URL, in the format: `postgresql://[user[:passwd]@]host[:port]/[db][?parameters...]` Example: postgresql://myuser@localhost:26257/mydb If not specified, uses other connection parameters. Environment variable: `KWBASE_URL`
`-u`, `--user`	The KWDB database username. Environment variable: `KWBASE_USER`
`--watch`	Repeatedly execute the SQL statements specified by `--execute` at the specified interval. Stops monitoring when execution fails.

Examples

TLS secure mode

The following example assumes certificates have been generated for the root user. For more details about generating certificates, see the Examples section of the kwbase cert command.
```
./kwbase sql --certs-dir=certs --host=<address_of_any node>
```

Insecure mode

./kwbase sql --insecure --host=<address_of_any_node>

kwbase auth-session

Description

The kwbase auth-session command is used to create and manage sessions and authentication tokens for HTTP interfaces.

Required Permissions

The user is a member of the admin role. By default, the root user belongs to the admin role.

Command Syntax

./kwbase auth-session <subcommand> [flags]

login

./kwbase auth-session login <session-username> [flags]

logout

./kwbase auth-session logout <session-username> [flags]

list
```
./kwbase auth-session list [flags]
```

Subcommands

Subcommand	Description
`login`	Create an HTTP session and token for the specified user.
`logout`	Revoke all HTTP session tokens previously created for the specified user.
`list`	View currently active HTTP sessions.

Parameters

Parameter Details

Parameter	Description	Supported Commands
`--cert-principal-map`	A comma-separated list of `<cert-principal>:<db-principal>` mappings. Used to map certificate principals to database principals (such as nodes, root, or other SQL users). Applies when the certificate system has restrictions on `Subject.CommonName` or `SubjectAlternateName` fields. When multiple mappings exist, later ones take precedence. Unmapped principals are passed through as-is.	- `kwbase auth-session login` - `kwbase auth-session logout` - `kwbase auth-session list`
`--certs-dir`	The path to the secure certificates directory, used to access and verify clusters deployed in secure mode. Default value: `${HOME}/.kaiwudb-certs/`	- `kwbase auth-session login` - `kwbase auth-session logout` - `kwbase auth-session list`
`--echo-sql`	Display SQL statements implicitly sent by the command line tool.	- `kwbase auth-session login` - `kwbase auth-session logout` - `kwbase auth-session list`
`--expire-after`	The validity period of the HTTP authentication token. Specify using a number followed by `h` (hours), `m` (minutes), or `s` (seconds). Default value: `1h0m0s`	`kwbase auth-session login`
`--format`	Table display format for results: - `tsv` - `csv` - `table` - `records` - `sql` - `raw` - `html` Default: `tsv` for non-interactive, `table` for interactive	- `kwbase auth-session login` - `kwbase auth-session logout` - `kwbase auth-session list`
`-h`, `--help`	Display help information for the command.	- `kwbase auth-session` - `kwbase auth-session login` - `kwbase auth-session logout` - `kwbase auth-session list`
`--insecure`	Start the cluster in insecure mode. Secure mode is used if not specified.	- `kwbase auth-session login` - `kwbase auth-session logout` - `kwbase auth-session list`
`--only-cookie`	Only display the newly created HTTP authentication token (cookie), for output to other commands.	`kwbase auth-session login`
`--url`	The connection URL, in the format: `postgresql://[user[:passwd]@]host[:port]/[db][?parameters...]` Example: `postgresql://myuser@localhost:26257/mydb` If not specified, uses other connection parameters. Environment variable: `KWBASE_URL`	- `kwbase auth-session login` - `kwbase auth-session logout` - `kwbase auth-session list`
`-u`, `--user`	The KWDB database username. Environment variable: `KWBASE_USER`	- `kwbase auth-session login` - `kwbase auth-session logout` - `kwbase auth-session list`

Return Fields Description

Field	Description
`username`	The username of the authenticated user.
`session ID`	The HTTP interface session ID created for the specified user.
`authentication cookie`	The authentication token used for users to authenticate when accessing the HTTP interface through CLI tools or other tools.

auth-session logout

Field	Description
`username`	The username of the user whose session was revoked
`session ID`	The HTTP interface session ID created for the specified user
`revoked`	The date and time when the authentication session was revoked for the specified user

auth-session list

Field	Description
`username`	The username of the authenticated user
`session ID`	The HTTP interface session ID created for the specified user
`created`	The date and time when the authentication session was created
`expired`	The date and time when the authentication session expires
`revoked`	The date and time when the authentication session was revoked for the specified user. If the authentication session is still active, displays `NULL`
`last used`	The date and time when the session token was last used to access the HTTP interface

kwbase node

Description

The kwbase node command is used to view, inspect, drain, or remove each node in a KWDB cluster.

Command Syntax

./kwbase node <subcommand> [flags]

ls
```
./kwbase node ls [flags]
```

status

./kwbase node status [<node_id>] [flags]

decommission

./kwbase node decommission <node_id 1> [<node_id 2> ...] [flags]

recommission

./kwbase node recommission <node_id 1> [<node_id 2> ...] [flags]

drain
```
./kwbase node drain [flags]
```

upgrade

./kwbase node upgrade <node_id 1> [<node_id 2> ...] [flags]

Subcommands

Subcommand	Description
`ls`	List all node IDs in the cluster.
`status`	View the status of a single or all nodes in the cluster.
`decommission`	Decommission cluster nodes.
`recommission`	Recommission decommissioned cluster nodes.
`drain`	Drain nodes.
`upgrade`	Upgrade nodes.

Parameters

Parameter Details

Parameter	Description	Supported Commands
`--all`	View detailed information for all nodes. If node ID is not specified, view all decommissioned nodes in the cluster.	`kwbase node status`
`--cert-principal-map`	A comma-separated list of `<cert-principal>:<db-principal>` mappings that allows mapping principals in certificates to database principals, such as nodes, root, or any SQL user. This applies when the certificate management system has restrictions on the `Subject.CommonName` or `SubjectAlternateName` fields in certificates (for example, not allowing node or root as `CommonName`). If there are multiple mappings for the same certificate principal, the last specified mapping takes precedence. Principals not specified in the mapping are passed through as-is. If the database principal name is contained in the mapped `CommonName` or DNS-type `SubjectAlternateName` field, the certificate is allowed to authenticate for the database principal.	`kwbase node ls` `kwbase node status` `kwbase node decommission` `kwbase node recommission` `kwbase node drain` `kwbase node upgrade`
`--certs-dir`	The path to the secure certificates directory, used to access and verify clusters deployed in secure mode. Default value: `${HOME}/.kaiwudb-certs/`	`kwbase node ls` `kwbase node status` `kwbase node decommission` `kwbase node recommission` `kwbase node drain` `kwbase node upgrade`
`--cluster-name`	Set a name for the remote node or cluster to verify its identity. This value must match this node and the remote nodes specified via the `--join` parameter. This name can be used as an additional verification means when the node or cluster or both are not yet initialized and their cluster ID is unknown. To add a cluster name to an already initialized cluster, use this parameter together with `--disable-cluster-name-verification`.	`kwbase node ls` `kwbase node status` `kwbase node decommission` `kwbase node recommission` `kwbase node drain` `kwbase node upgrade`
`--decommission`	View detailed information about node decommissioning. If node ID is not specified, view all decommissioned nodes in the cluster.	`kwbase node status`
`--disable-cluster-name-verification`	Configure the server to ignore cluster name mismatches. Applicable when starting an existing cluster or after changing the cluster name. Restart the cluster with `--cluster-name` and `--disable-cluster-name-verification` parameters. Once all nodes have been updated to know the new cluster name, you can remove this parameter and restart the cluster again.	`kwbase node ls` `kwbase node status` `kwbase node decommission` `kwbase node recommission` `kwbase node drain` `kwbase node upgrade`
`--drain-wait`	The time the system waits for the node to drain all active client connections and migrate data shard leases. Default value: `10m0s`	`kwbase node drain`
`--format`	Choose how to display table rows in results. Supports the following values: - `tsv` - `csv` - `table` - `records` - `sql` - `raw` - `html` If not specified, defaults to `tsv` for non-interactive sessions and `table` for interactive sessions. Default value: `table`	`kwbase node ls` `kwbase node status` `kwbase node decommission` `kwbase node recommission` `kwbase node drain` `kwbase node upgrade`
`-h`, `--help`	Help information for the command.	`kwbase node` `kwbase node ls` `kwbase node status` `kwbase node decommission` `kwbase node recommission` `kwbase node drain` `kwbase node upgrade`
`--host`	The KWDB node to connect to. Supports IP address/hostname, in the format `<addr/host>[:<port>]`. If port is not specified, defaults to `26257`. For IPv6 addresses, use `[...]` notation, for example: `[::1]:26257` or `[fe80::f6f2::1]:26257`. Environment variable: `KWBASE_HOST`	`kwbase node ls` `kwbase node status` `kwbase node decommission` `kwbase node recommission` `kwbase node drain` `kwbase node upgrade`
`--insecure`	Start the cluster in insecure mode. If not specified, the cluster starts in secure mode.	`kwbase node ls` `kwbase node status` `kwbase node decommission` `kwbase node recommission` `kwbase node drain` `kwbase node upgrade`
`--ranges`	View detailed information about node data shards and replicas.	`kwbase node status`
`--stats`	View detailed information about node disk usage.	`kwbase node status`
`--timeout`	Set the timeout for the subcommand to run. If the operation is not completed within the specified time,
`--url`	The connection URL, in the format `postgresql://[user[:passwd]@]host[:port]/[db][?parameters...]`, for example "postgresql://myuser@localhost:26257/mydb". If not specified, uses connection parameters such as `host`, `port`, `user`, `database`, `insecure`, `certs-dir`. Environment variable: `KWBASE_URL`	- `kwbase node ls` - `kwbase node decommission` - `kwbase node recommission` - `kwbase node drain` - `kwbase node upgrade`
`--wait`	Specify when to return after marking the target node as decommissioned. This parameter supports the following values: - `all`: Wait until the replica count on all target nodes drops to zero. - `none`: Mark the target node as decommissioned without waiting for the entire process to complete. Use this value when manually polling from an external system. Default value: `all`	- `kwbase node decommission` - `kwbase node upgrade`

kwbase gen

Description

The kwbase gen command is used to generate CLI tool information, SQL Shell configuration examples, database examples, and other information.

Command Syntax

./kwbase gen <subcommand> [flags]

haproxy
```
./kwbase gen haproxy [flags]
```
encryption-key
```
./kwbase gen encryption-key [flags]
```

Subcommands

Subcommand	Description
`haproxy`	Generate an `haproxy.cfg` file for the connected cluster.
`encryption-key`	Generate a storage key for static encryption.

Parameters

Parameter Details

Parameter	Description	Supported Commands
`--cert-principal-map`	A comma-separated list of `<cert-principal>:<db-principal>` mappings used to map certificate principals to database principals (such as nodes, root, or SQL users). Applies when the certificate system has restrictions on `Subject.CommonName` or `SubjectAlternateName` fields. When multiple mappings exist, the last one takes precedence. Unmapped principals are passed through as-is.	`kwbase gen haproxy`
`--certs-dir`	Secure certificates directory path. Default value: `${HOME}/.kaiwudb-certs/`	`kwbase gen haproxy`
`--cluster-name`	Set the remote node/cluster name for identity verification. Must match this node and the remote nodes specified by `--join`. Used for additional verification of uninitialized nodes. Use with `--disable-cluster-name-verification` when joining an already initialized cluster.	`kwbase gen haproxy`
`--disable-cluster-name-verification`	Ignore cluster name mismatches. Used when starting an existing cluster or after changing the cluster name. Use with `--cluster-name` to restart the cluster. Can be removed and restart after all nodes are updated with the new cluster name.	`kwbase gen haproxy`
`-h`, `--help`	Display help information.	- `kwbase gen` - `kwbase gen haproxy` - `kwbase gen encryption-key`
`--host`	The address of the node to connect to. Format: `<addr/host>[:<port>]`. - Default port: 26257 - IPv6 format: `[::1]:26257` Environment variable: `KWBASE_HOST`	`kwbase gen haproxy`
`--insecure`	Start in insecure mode. Secure mode is used by default.	`kwbase gen haproxy`
`--out`	HAProxy configuration file path. Default value: `haproxy.cfg`	`kwbase gen haproxy`
`--overwrite`	Overwrite existing keys.	`kwbase gen encryption-key`
`-s`, `--size`	AES static encryption key size: - 128 - 192 - 256 Default value: 128	`kwbase gen encryption-key`
`--url`	The connection URL. Format: `postgresql://[user[:passwd]@]host[:port]/[db][?parameters...]` Example: postgresql://myuser@localhost:26257/mydb If not specified, uses individual connection parameters. Environment variable: `KWBASE_URL`	`kwbase gen haproxy`

kwbase version

Description

The kwbase version command is used to view version information for KWDB.

Command Syntax

./kwbase version [flags]

Parameters

Parameter	Description
`-h`, `--help`	Help information for the `kwbase version` command.

Examples

The following example views KWDB version information.

./kwbase version
KWDB Version:  2.1.1
Build Time:       2024/12/02 06:42:24
Distribution:
Platform:         linux amd64 (x86_64-linux-gnu)
Go Version:       go1.16.15
C Compiler:       gcc 11.4.0
Build SHA-1:      83c35a67ab352611ce97300307ebe7d704d24888

kwbase help

Description

The kwbase help command is used to view help information for the kwbase CLI tool.

Command Syntax

./kwbase help

Parameters

None

Examples

./kwbase help
KwDB command-line interface and server.

Usage:
  kwbase [command]

Available Commands:
  start                start a node in a multi-node cluster
  start-single-replica start a single-replica node in a multi-node cluster
  start-single-node    start a single-node cluster
  init                 initialize a cluster
  cert                 create ca, node, and client certs
  sql                  open a sql shell
  statement-diag       commands for managing statement diagnostics bundles
  auth-session         log in and out of HTTP sessions
  node                 list, inspect, drain or remove nodes
  nodelocal            upload and delete nodelocal files
  demo                 open a demo sql shell (not suitable for time-series scenario)
  gen                  generate auxiliary files
  version              output version information
  debug                debugging commands
  sqlfmt               format SQL statements
  workload             generators for data and query loads
  systembench          Run systembench
  help                 Help about any command

Flags:
  -h, --help                             help for kwbase
      --logtostderr Severity[=DEFAULT]   logs at or above this threshold go to stderr (default NONE)
      --no-color                         disable standard error log colorization
      --vmodule moduleSpec               comma-separated list of pattern=N settings for file-filtered logging (significantly hurts performance)

Use "kwbase [command] --help" for more information about a command.

kwbase start​

Description​

Command Syntax​

Parameters​

Examples​

kwbase start-single-replica​

Description​

Command Syntax​

Parameters​

Examples​

kwbase start-single-node​

Description​

Command Syntax​

Parameters​

Examples​

kwbase init​

Description​

Command Syntax​

Parameters​

Examples​

kwbase cert​

Description​

Command Syntax​

Subcommands​

Parameters​

Examples​

kwbase sql​

Description​

Command Syntax​

Parameters​

Examples​

kwbase auth-session​

Description​

Required Permissions​

Command Syntax​

Subcommands​

Parameters​

Return Fields Description​

auth-session login​

auth-session logout​

auth-session list​

kwbase node​

Description​

Command Syntax​

Subcommands​

Parameters​

kwbase gen​

Description​

Command Syntax​

Subcommands​

Parameters​

kwbase version​

Description​

Command Syntax​

Parameters​

Examples​

kwbase help​

Description​

Command Syntax​

Parameters​

Examples​

kwbase start

Description

Command Syntax

Parameters

Examples

kwbase start-single-replica

Description

Command Syntax

Parameters

Examples

kwbase start-single-node

Description

Command Syntax

Parameters

Examples

kwbase init

Description

Command Syntax

Parameters

Examples

kwbase cert

Description

Command Syntax

Subcommands

Parameters

Examples

kwbase sql

Description

Command Syntax

Parameters

Examples

kwbase auth-session

Description

Required Permissions

Command Syntax

Subcommands

Parameters

Return Fields Description

auth-session login

auth-session logout

auth-session list

kwbase node

Description

Command Syntax

Subcommands

Parameters

kwbase gen

Description

Command Syntax

Subcommands

Parameters

kwbase version

Description

Command Syntax

Parameters

Examples

kwbase help

Description

Command Syntax

Parameters

Examples