## Q: How can I specify the version of a component?
A: You can add the version declaration to the deployment configuration file. For example, you can specify the version of OceanBase-CE V3.1.0 in the deployment configuration file in the following format:
```yaml
oceanbase-ce:
version:3.1.0
```
## Q: How can I use a component of a specific version?
A: You can add the package_hash or tag declaration to the deployment configuration file.
For example, if you have tagged your compiled OceanBase-CE, you can specify it by tag. For example:
```yaml
oceanbase-ce:
tag:my-oceanbase
```
You can also use package_hash to specify a specific version. When you run an `obd mirror` command, OBD will return an MD5 value of the component. The MD5 value is the value of package_hash.
## Q: How can I modify the startup process after I modify the code of OceanBase-CE?
A: You can modify the startup plug-ins in the `~/.obd/plugins/oceanbase-ce/` directory. For example, after you add a new startup configuration item for OceanBase-CE V3.1.0, you can modify the `start.py` file in the `~/.obd/plugins/oceanbase-ce/3.1.0` directory.
## Q：How to update OBD?
A：You can use the `obd update` command to update OBD. When you are done with the update, use the `obd --version` command to confirm the version of OBD.
To start an OceanBase cluster, follow these steps:
### Step 1: Select a configuration file
Select a configuration file based on your resource configurations:
#### Small-scale deployment mode
This deployment mode applies to personal devices with at least 8 GB of memory.
-[Sample configuration file for local single-node deployment](../../../example/mini-local-example.yaml)
-[Sample configuration file for single-node deployment](../../../example/mini-single-example.yaml)
-[Sample configuration file for three-node deployment](../../../example/mini-distributed-example.yaml)
-[Sample configuration file for single-node deployment with ODP](../../../example/mini-single-with-obproxy-example.yaml)
-[Sample configuration file for three-node deployment with ODP](../../../example/mini-distributed-with-obproxy-example.yaml)
#### Professional deployment mode
This deployment mode applies to advanced Elastic Compute Service (ECS) instances or physical servers with at least 16 CPU cores and 64 GB of memory.
-[Sample configuration file for local single-node deployment](../../../example/local-example.yaml)
-[Sample configuration file for single-node deployment](../../../example/single-example.yaml)
-[Sample configuration file for three-node deployment](../../../example/distributed-example.yaml)
-[Sample configuration file for single-node deployment with ODP](../../../example/single-with-obproxy-example.yaml)
-[Sample configuration file for three-node deployment with ODP](../../../example/distributed-with-obproxy-example.yaml)
-[Sample configuration file for three-node deployment with ODP and obagent](../../../example/obagent/distributed-with-obproxy-and-obagent-example.yaml)
This section describes how to start a local single-node OceanBase cluster by using the [sample configuration file for local single-node deployment in the small-scale deployment mode](../../../example/mini-local-example.yaml).
```shell
# Modify the working directory of the OceanBase cluster: home_path.
# Modify the SQL service protocol port of the OceanBase cluster: mysql_port. This port will be used to connect to the cluster later.
# Modify the internal communication port of the OceanBase cluster: rpc_port.
vi ./example/mini-local-example.yaml
```
If the target server to run the OceanBase cluster is not the logged-in server, do not use the `sample configuration file for local single-node deployment`. Use another configuration file.
Do not forget to change the user password at the beginning of the configuration file.
```yaml
user:
username:<Your account name.>
password:<Your logon password.>
key_file:<The path of your private key.>
```
`username` specifies the username used to log on to the target server. Make sure that your username has the write permission on the `home_path` directory. `password` and `key_file` are used to authenticate the user. Generally, only one of them is required.
> **NOTE:** After you specify the path of the key, add an annotation to the `password` field or delete it if your key does not require a password. Otherwise, `password` will be deemed as the password of the key and used for login, leading to a logon verification failure.
### Step 2: Deploy and start a cluster
```shell
# The following command checks whether the home_path and data_dir directories are empty.
# If not, an error is returned. In this case, you can add the -f option to forcibly clear the directories.
obd cluster deploy lo -c local-example.yaml
# The following command checks whether the value of the fs.aio-max-nr parameter is no less than 1048576.
# Generally, you do not need to modify the fs.aio-max-nr parameter when you start one node on a server.
# However, you must modify the fs.aio-max-nr parameter when you start four or more nodes on a server.
obd cluster start lo
```
### Step 3: View the cluster status
```shell
# View clusters managed by OBD.
obd cluster list
# View the status of the lo cluster.
obd cluster display lo
```
### Step 4: Modify configurations
OceanBase Database has hundreds of configuration items and some of them are coupled. We recommend that you do not modify the configurations in the sample configuration file unless you are familiar with OceanBase Database. The following example shows how to modify the configurations and make them take effect.
```shell
# Run the edit-config command to enter the editing mode and modify the cluster configurations.
obd cluster edit-config lo
# Set the value of sys_bkgd_migration_retry_num to 5.
# Note that the minimum value of sys_bkgd_migration_retry_num is 3.
# Save the settings and exit. OBD will tell you how to make the modification take effect.
# To make the modification take effect, you only need to run the reload command.
obd cluster reload lo
```
### Step 5: Stop the cluster
You can run the `stop` command to stop a running cluster. If the `start` command fails but some processes are still running, run the `destroy` command to destroy the cluster.
```shell
obd cluster stop lo
```
### Step 6: Destroy the cluster
To destroy the cluster, run this command:
```shell
# When the start command fails, some processes may still be running.
# In this case, use the -f option to forcibly stop and destroy the cluster.
After you install OBD, you can run these commands as the root user to start a local single-node OceanBase cluster.
Before you run the commands, make sure that these conditions are met:
- You have logged on as the root user.
- Ports `2882` and `2883` are available.
- Your server has at least 8 GB of memory.
- Your server has at least 2 CPU cores.
> **NOTE:** If the preceding conditions are not met, see [Use OBD to start an OceanBase cluster](./start-OceanBase-cluster-with-obd.md).
> **NOTE:** For the convenience of using root here, OBD and OceanBase database do not have any restrictions on running users. We do not recommend that you use root in production.
OBD provides multiple-level commands. You can use the`-h/--help` option to view the help information of sub-commands.
A deployment configuration is the minimum unit for OBD cluster commands. A deployment configuration is a `yaml` file. It contains all configuration information of a deployment, including the server login information, component information, component configuration information, and component server list.
To start a cluster by using OBD, you must register the deployment configuration of your cluster to OBD. You can run the `obd cluster edit-config` command to create an empty deployment configuration or run the `obd cluster deploy -c config` command to import a deployment configuration.
## `obd cluster autodeploy`
When you pass a simple configuration file to OBD, OBD will automatically generate a complete configuration file with the maximum specifications based on the resources of the target server, and then deploy and start a cluster on the target server.
`deploy name` specifies the name of the deployment configuration file.
The following table describes the corresponding options.
| Option | Required | Data type | Default value | Description |
--- | --- | --- |--- |---
| -c/--config | Yes | string | None | Specifies the yaml file used for deployment and registers the deployment configuration to OBD. <br>When the `deploy name` already exists, OBD will check the status of the existing deployment configuration. If the existing deployment configuration has not been applied, it will be overwritten. If the existing deployment configuration is in use, an error will be returned. |
| -f/--force | No | bool | false | Specifies whether to forcibly clear the working directory. <br>When the component requires an empty working directory but this option is disabled, an error will be returned if the working directory is not empty. |
| -U/--ulp/--unuselibrepo | No | bool | false | Specifies whether to prevent OBD from automatically taking actions when dependencies are missing. If this option is disabled and OBD detects that some dependencies are missing, OBD will automatically search for the corresponding libs mirrors and install them. If this option is enabled, the **unuse_lib_repository: true** field will be added to the corresponding configuration file. You can also add the **unuse_lib_repository: true** field to the configuration file to enable this option. |
| -A/--act/--auto-create-tenant | No | bool | false | Specifies whether to enable OBD to create the `test` tenant during the bootstrap by using all available resources of the cluster. If this option is enabled, the **auto_create_tenant: true** field will be added to the corresponding configuration file. You can also add the **auto_create_tenant: true** field to the configuration file to enable this option. |
| -s/--strict-check | No | bool | false | Some components will do relevant checks before starting. It will issue an alarm when the check fails, but it will not force the process to stop. Using this option can return an error and directly exit the process when the component pre-check fails. We recommend that you enable this option to avoid startup failures due to insufficient resources. |
## `obd cluster edit-config`
Modifies a deployment configuration or creates one when the specified deployment configuration does not exist.
```shell
obd cluster edit-config <deploy name>
```
`deploy name` specifies the name for the deployment configuration file.
## `obd cluster deploy`
Deploys a cluster based on the deployment configuration file. Based on the deployment configuration file, this command finds the matching mirror, then installs the mirror in a local repository. This process is called local installation.
Then, OBD distributes the components of the required version in the local repository to the target server. This process is called remote installation.
During both local and remote installation, OBD checks whether the server stores dependencies required for running the components.
This command allows you to deploy a cluster based on a deployment configuration that has been registered to OBD or by passing a `yaml` file.
`deploy name` specifies the name of the deployment configuration file.
The following table describes the corresponding options.
| Option | Required | Data type | Default value | Description |
--- | --- | --- |--- |---
| -c/--config | No | string | None | Specifies the yaml file used for deployment and registers the deployment configuration to OBD. <br>If this option is enabled and a deployment configuration of the specified `deploy name` already exists, the existing deployment configuration will be overwritten. <br>If this option is not enabled, OBD will search for the registered deployment configuration of the specified `deploy name`. |
| -f/--force | No | bool | false | Specifies whether to forcibly clear the working directory. <br>When the component requires an empty working directory but this option is disabled, an error will be returned if the working directory is not empty. |
| -U/--ulp/--unuselibrepo | No | bool | false | Specifies whether to prevent OBD from automatically taking actions when dependencies are missing. If this option is disabled and OBD detects that some dependencies are missing, OBD will automatically search for the corresponding libs mirrors and install them. If this option is enabled, the **unuse_lib_repository: true** field will be added to the corresponding configuration file. You can also add the **unuse_lib_repository: true** field to the configuration file to enable this option. |
| -A/--act/--auto-create-tenant | No | bool | false | Specifies whether to enable OBD to create the `test` tenant during the bootstrap by using all available resources of the cluster. If this option is enabled, the **auto_create_tenant: true** field will be added to the corresponding configuration file. You can also add the **auto_create_tenant: true** field to the configuration file to enable this option. |
## `obd cluster start`
Starts a deployed cluster. If the cluster is started, OBD will return its status.
```shell
obd cluster start <deploy name> [flags]
```
`deploy name` specifies the name of the deployment configuration file.
This table describes the corresponding options.
| Option | Required | Data type | Default value | Description |
--- | --- | --- |--- | ---
| -s/--servers | No | string | | A list of machines, separated by `,`. Be used for specifying the start-up machines. If this option is disabled, all machines under the component will start without executing bootstrap. |
| -c/--components | No | string | | A list of components, separated by `,`. Be used for specifying the start-up components. If this option is disabled, all machines under the component will start without entering the running state. |
| --wop/--without-parameter | No | bool | false | Start without parameters. The node does not respond to this option when this node is starting for the first time. |
| -S/--strict-check | No | bool | false | Some components will do relevant checks before starting. OBD will throw an error when the check fails, but OBD will not force the process to stop. Using this option can return an error and directly exit the process when the component pre-check fails. We recommend that you enable this option to avoid startup failures due to insufficient resources. |
## `obd cluster list`
Shows the status of all clusters that have been registered to OBD. The cluster names are specified by the deploy name parameter.
```shell
obd cluster list
```
## `obd cluster display`
Shows the status of the specified cluster.
```shell
obd cluster display <deploy name>
```
`deploy name` specifies the name of the deployment configuration file.
## `obd cluster reload`
Reloads a running cluster. After you modify the configuration information of a running cluster by using the `edit-config` command, you can run the `reload` command to let your modification take effect.
> **NOTE:** Some configuration items may not take effect after you run the `reload` command. You need to restart or even redeploy the cluster for these configuration items to take effect. Do operations based on the result returned by the `edit-config` command.
```shell
obd cluster reload <deploy name>
```
`deploy name` specifies the name of the deployment configuration file.
## `obd cluster restart`
Restarts a running cluster. After you run the edit-config command to modify the configuration information of a running cluster, you can run the `restart` command for the modification to take effect.
> **NOTE:** Some configuration items may not take effect after you run the `restart` command. You even need to redeploy the cluster for some configuration items to take effect. Perform operations based on the result returned by the edit-config command.
```shell
obd cluster restart <deploy name>
```
`deploy name` specifies the name of the deployment configuration file.
This table describes the corresponding options.
| Option | Required | Data type | Default value | Description |
--- | --- | --- |--- | ---
| -s/--servers | No | string | | A list of machines, separated by `,`. |
| -c/--components | No | string | | A list of components, separated by `,`. Be used for specifying the start-up components. If this option is disabled, all machines under the component will start without entering the running state. |
| --wop/--without-parameter | No | bool | false | Start without parameters. It is without parameters when starting. The node does not respond to this option when it is starting for the first time. |
## `obd cluster redeploy`
Redeploys a running cluster. After you run the `edit-config` command to modify the configuration information of a running cluster, you can run the `redeploy` command to let your modification take effect.
> **NOTE:** This command destroys the cluster and redeploys it. Data in the cluster will be lost. Please back up the data before you run this command.
```shell
obd cluster redeploy <deploy name>
```
`deploy name` specifies the name of the deployment configuration file.
## `obd cluster stop`
Stops a running cluster.
```shell
obd cluster stop <deploy name>
```
`deploy name` specifies the name of the deployment configuration file.
This table describes the corresponding options.
| Option | Required | Data type | Default value | Description |
--- | --- | --- |--- | ---
| -s/--servers | No | string | | A list of machines, separated by `,`. Be used for specifying the start-up machines. |
| -c/--components | No | string | | A list of components, separated by `,`. Be used for specifying the start-up components. If not all components under the configuration start, this configuration will not enter the stopped state. |
## `obd cluster destroy`
Destroys a deployed cluster. If the cluster is running state, this command will first try to execute `stop` and then `destroy` after success.
```shell
obd cluster destroy <deploy name> [-f]
```
`deploy name` specifies the name of the deployment configuration file.
`-f` is `--force-kill`. This option specifies whether to forcibly stop running processes in the working directory. Before OBD destroys the cluster, it will check for running processes. These processes may result from the failure of the **start** command. They may also belong to other clusters when configurations of this cluster overlap with those of other clusters. If an ongoing process is found in the working directory, OBD will stop the **destroy** command. However, if this option is enabled, OBD will forcibly stop the ongoing processes and run the **destroy** command. `-f` is optional. Its data type is `bool`. This option is disabled by default.
## `obd cluster tenant create`
Creates a tenant. This command applies only to an OceanBase cluster. This command automatically creates resource units and resource pools.
`deploy name` specifies the name of the deployment configuration file.
This table describes the corresponding options.
| Option | Required | Data type | Default value | Description |
--- | --- | --- |--- | ---
| -n/--tenant-name | No | string | test | The tenant name. OBD will automatically generate resource units and resource pools with unique names based on the tenant name. |
| --max-cpu | No | float | 0 | The maximum number of CPU cores available for the tenant. When this option is set to 0, all available CPU cores of the cluster can be used by the tenant. |
| --min-cpu | No | float | 0 | The minimum number of CPU cores available for the tenant. When this option is set to 0, the minimum number of CPU cores is the same as the maximum number of CPU cores. |
| --max-memory | No | int | 0 | The maximum memory capacity available for the tenant. When this option is set to 0, all available memory capacity of the cluster can be used by the tenant. When the actual value is less than 1 GB, an error is returned. |
| --min-memory | No | int | 0 | The minimum memory capacity available for the tenant. When this option is set to 0, the minimum memory capacity is the same as the maximum memory capacity. |
| --max-disk-size | No | int | 0 | The maximum disk space available for the tenant. When this option is set to 0, all available disk space of the cluster can be used by the tenant. If the actual value is less than 512 MB, an error is returned. |
| --max-iops | No | int | 128 | The maximum IOPS for the tenant. Value range: [128, +∞). |
| --min-iops | No | int | 0 | The minimum IOPS for the tenant. Value range: [128, +∞). When this option is set to 0, the minimum IOPS is the same as the maximum IOPS. |
| --max-session-num | No | int | 64 | The maximum number of sessions allowed for the tenant. Value range: [64, +∞). |
| --unit-num | No | int | 0 | The number of units to be created in a zone. It must be less than the number of OBServers in the zone. When this option is set to 0, the maximum value is used. |
| -z/--zone-list | No | string | | Specifies the list of zones of the tenant. Separate multiple zones with commas (,). If this option is not specified, all zones of the cluster are included. |
| --primary-zone | No | string | RANDOM | The primary zone of the tenant. |
| --charset | No | string | | The character set of the tenant. |
| --collate | No | string | | The collation of the tenant. |
| --replica-num | No | int | 0 | The number of replicas of the tenant. When this option is set to 0, the number of replicas is the same as that of zones. |
| --logonly-replica-num | No | string | 0 | The number of log replicas of the tenant. When this option is set to 0, the number of log replicas is the same as that of replicas. |
| --tablegroup | No | string | | The default table group of the tenant. |
| --locality | No | string | | The distribution status of replicas across zones. For example, F@z1,F@z2,F@z3,R@z4 means that z1, z2, and z3 are full-featured replicas and z4 is a read-only replica. |
| -s/--variables | No | string | ob_tcp_invited_nodes='%' | The system variables of the tenant. |
## `obd cluster tenant drop`
Deletes a tenant. This command applies only to an OceanBase cluster. This command automatically deletes the corresponding resource units and resource pools.
```shell
obd cluster tenant drop <deploy name> [-n <tenant name>]
```
`deploy name` specifies the name of the deployment configuration file.
`-n` is `--tenant-name`. This option specifies the name of the tenant to be deleted. This option is required.
OBD provides multiple-level commands. You can use the`-h/--help` option to view the help information of sub-commands.
## `obd mirror clone`
Copy an RPM package to the local mirror repository. You can run the corresponding OBD cluster command to start the mirror.
```shell
obd mirror clone <path> [-f]
```
`path` specifies the path of the RPM package.
The `-f` option is `--force`. `-f` is optional. This option is disabled by default. If it is enabled and a mirror of the same name exists in the repository, the copied mirror will forcibly overwrite the existing one.
## `obd mirror create`
Creates a mirror based on the local directory. When OBD starts a user-compiled open-source OceanBase software, you can run this command to add the compilation output to the local repository. Then, you can run the corresponding `obd cluster` command to start the mirror.
For example, you can [compile an OceanBase cluster based on the source code](https://open.oceanbase.com/docs/community/oceanbase-database/V3.1.1/get-the-oceanbase-database-by-using-source-code). Then, you can run the `make DESTDIR=./ install && obd mirror create -n oceanbase-ce -V 3.1.0 -p ./usr/local` command to add the compilation output to the local repository of OBD.
This table describes the corresponding options.
| Option | Required | Data type | Description |
--- | --- | --- |---
| -n/--name | Yes | string | The component name. If you want to compile an OceanBase cluster, set this option to oceanbase-ce. If you want to compile ODP, set this option to obproxy. |
| -p/--path | Yes | string | The directory that stores the compilation output. OBD will automatically retrieve files required by the component from this directory. |
| -t/--tag | No | string | The mirror tags. You can define one or more tags for the created mirror. Separate multiple tags with commas (,). |
| -f/--force | No | bool | Specifies whether to forcibly overwrite an existing mirror or tag. This option is disabled by default. |
## `obd mirror list`
Shows the mirror repository or mirror list.
```shell
obd mirror list [mirror repo name]
```
`mirror repo name` specifies the mirror repository name. This parameter is optional. When it is not specified, all mirror repositories will be returned. When it is specified, only the specified mirror repository will be returned.
## `obd mirror update`
Synchronizes the information of all remote mirror repositories.
OBD provides multiple-level commands. You can use the`-h/--help` option to view the help information of sub-commands.
## `obd test mysqltest`
Runs the mysqltest on the specified node of an OcecanBase cluster or ODP. To run the mysqltest, you must install OBClient.
```shell
obd test mysqltest <deploy name> [--test-set <test-set>] [flags]
```
`deploy name` specifies the name of the deployment configuration file.
This table describes the corresponding options.
| Option | Required | Data type | Default value | Description |
--- | --- | --- |--- | ---
| -c/--component | No | string | | The name of the component to be tested. Valid values: `oceanbase-ce`, `oceanbase`, `obproxy-ce` and `obproxy`. If you do not specify a value, the existence of `obproxy`, `obproxy-ce`, `oceanbase`, `oceanbase-ce` is checked sequentially. The traversal stops when a component is found, and the component is then tested. |
| --test-server | No | string | The first node of the specified component. | It must be the name of a node of the specified component. |
| --user | No | string | root | The username for running the test. |
| --password | No | string | | The password for running the test. |
| --mysqltest-bin | No | string | mysqltest | The path of the mysqltest binary file. |
| --obclient-bin | No | string | obclient | The path of the OBClient binary file. |
| --test-dir | No | string | ./mysql_test/t | The directory that stores the test file required for the mysqltest. If no test file is found in the directory, OBD will search for a built-in test file. |
| --result-dir | No | string | ./mysql_test/r | The directory that stores the result file required for the mysqltest. If no result file is found in the directory, OBD will search for a built-in result file. |
| --tmp-dir | No | string | ./tmp | The mysqltest tmpdir option. |
| --var-dir | No | string | ./var | The directory to create the log directory. The log directory will be added to the mysqltest command as the logdir option. |
| --test-set | No | string | None | The test case array. Separate multiple test cases with commas (,). |
| --test-pattern | No | string | None | The regular expression for matching test file names. Test cases matching the regular expression will overwrite the values of the test-set option. |
| --suite | No | string | None | The suite array. A suite contains multiple tests. Separate multiple tests with commas (,). If this option is enabled, the --test-pattern and --test-set options will become invalid. |
| --suite-dir | No | string | ./mysql_test/test_suite | The directory that stores the suite directory. If no suite directory is found in the directory, OBD will search for a built-in suite directory. |
| --all | No | bool | false | Specifies whether to run all test cases in the directory specified for the --suite-dir option. The --suite-dir option specifies the directory that stores the suite directory. |
| --need-init | No | bool | false | Specifies whether to run the init sql files. Before OBD runs the mysqltest on a new cluster, it may run some initialization files. For example, it may create some accounts or tenants required for running the test cases. The --suite-dir option specifies the directory that stores the suite directory. This option is disabled by default. |
| --init-sql-dir | No | string | ../ | The directory that stores the init sql files. If no init sql file is found in the directory, OBD will search for built-in init sql files. |
| --init-sql-files | No | string | | The init sql files to be run when initialization is required. Separate multiple init sql files with commas (,). If this option is not specified but initialization is required, OBD will run the built-in init files based on the cluster configurations. |
| --auto-retry | No | bool | false | Specifies whether to automatically redeploy the cluster for a retry after a test fails. |
## `obd test sysbench`
Runs the Sysbench test on the specified node of an OcecanBase cluster or ODP. To run the Sysbench test, you must install OBClient and ob-sysbench.
```shell
obd test sysbench <deploy name> [flags]
```
`deploy name` specifies the name of the deployment configuration file.
| Option | Required | Data type | Default value | Description |
--- | --- | --- |--- | ---
| -c/--component | No | string | | The name of the component to be tested. Valid values: `oceanbase-ce`, `oceanbase`, `obproxy-ce` and `obproxy`. If you do not specify a value, the existence of `obproxy`, `obproxy-ce`, `oceanbase`, `oceanbase-ce` is checked sequentially. The traversal stops when a component is found, and the component is then tested. |
| --test-server | No | string | The first node of the specified component. | It must be the name of a node of the specified component. |
| --user | No | string | root | The username for running the test. |
| --password | No | string | | The password for running the test. |
| --tenant | No | string | test | The tenant name for running the test. |
| --database | No | string | test | The database for performing the test. |
| --obclient-bin | No | string | obclient | The path of the OBClient binary file. |
| --sysbench-bin | No | string | sysbench | The path of the Sysbench binary file. |
| --script-name | No | string | point_select.lua | The name of the Sysbench script to be run. |
| --sysbench-script-dir | No | string | /usr/sysbench/share/sysbench | The directory that stores the Sysbench script. |
| --tables | No | int | 30 | The number of tables to be initialized. |
| --table-size | No | int | 20000 | The data size of each table to be initialized. |
| --threads | No | int | 16 | The number of threads to be started. |
| --time | No | int | 60 | The running duration. When this option is set to 0, the running duration is not limited. |
| --interval | No | int | 10 | The logging interval, in seconds. |
| --events | No | int | 0 | The maximum number of requests. If this option is specified, the --time option is not needed. |
| --rand-type | No | string | | The random number generation function used for data access. Valid values: special, uniform, gaussian, and pareto. Default value: special, early value: uniform. |
| ---skip-trx | No | string | | Specifies whether to enable or disable a transaction in a read-only test. |
| -O/--optimization | No | int | 1 | Auto tuning level. Off when 0. |
## `obd test tpch`
This section describes how to run the TPC-H test on the specified node of an OcecanBase cluster or ODP. To run the TPC-H test, you must install OBClient and obtpch.
TPC-H needs to specify an OceanBase target server as the execution target. Before executing the TPC-H test, OBD will transfer the data files required for the test to the specified directory of the specified machine. Please make sure that you have enough disk space on this machine because these files may be relatively large.
Of course, you can prepare the data files on the target machine in advance and then turn off the transfer by using the `-dt/--disable-transfer` option.
```shell
obd test tpch <deploy name> [flags]
```
`deploy name` specifies the name of the deployment configuration file.
| Option | Required | Data type | Default value | Description |
--- | --- | --- |--- | ---
| --test-server | No | string | The first node of the specified component. | It must be the name of a node of the specified component. |
| --user | No | string | root | The username for running the test. |
| --password | No | string | | The password for running the test. |
| --tenant | No | string | test | The tenant name for running the test. |
| --database | No | string | test | The database for performing the test. |
| --obclient-bin | No | string | obclient | The path of the OBClient binary file. |
| --dbgen-bin | No | string | /usr/local/tpc-h-tools/bin/dbgen | The path of the dbgen binary file. |
| --dss-config | No | string | /usr/local/tpc-h-tools/ | The directory that stores the dists.dss files. |
| -s/--scale-factor | No | int | 1 | Automatically generate the scale of test data, the data is measured in Gigabytes. |
| --tmp-dir | No | string | ./tmp | Temporary directory when executing tpch. When enabled, this option will automatically generate test data, auto-tuned SQL files, log files for executing test SQL, and so on. |
| --ddl-path | No | string | | The path or directory of the ddl file. If it is empty, OBD will use the ddl file that comes with it. |
| --tbl-path | No | string | | The path or directory of the tbl file. If it is empty, use dbgen to generate test data. |
| --sql-path | No | string | | The path or directory of the sql file. If it is empty, OBD will use the sql file that comes with it. |
| --remote-tbl-dir | No | string | | The directory where the tbl is stored on the target observer, it is the absolute path. Please make sure that you have the read and write permissions to this directory when you start the server. This option is required when `--test-only` is not enabled. |
| --test-only | No | bool | false | When you enable this option, initialization will not be done, only the test SQL is exectued. |
| --dt/--disable-transfer | No | bool | false | Disable transfer. When you enable this option, OBD will not transfer the local tbl to the remote remote-tbl-dir, and OBD will directly use the tbl file under the target machine remote-tbl-dir. |
| -O/--optimization | No | int | 1 | Auto tuning level. Off when 0. |
## obd test tpcc
You can run this command to perform a TPC-C test on a specified node of an OceanBase cluster or an OceanBase Database Proxy (ODP) component.
Make sure that you have installed OBClient and obtpcc, which are required to perform a TPC-C test.
```shell
obd test tpcc <deploy name> [flags]
```
The `deploy name` parameter specifies the name of the deployed cluster. You can consider it as an alias for the configuration file.
The following table describes details about the available options.
| Option | Required | Data type | Default value | Description |
--- | --- | --- |--- | ---
| --component | No | string | Empty | The name of the component to be tested. Valid values: `oceanbase-ce`, `oceanbase`, `obproxy-ce` and `obproxy`. If you do not specify a value, the existence of `obproxy`, `obproxy-ce`, `oceanbase`, `oceanbase-ce` is checked sequentially. The traversal stops when a component is found, and the component is then tested. |
| --test-server | No | string | The name of the first node under the specified component. | The name of the node to be tested under the specified component. |
| --user | No | string | root | The username used to perform the test. |
| --password | No | string | Empty | The user password used to perform the test. |
| --tenant | No | string | test | The tenant name used to perform the test. |
| --database | No | string | test | The database where the test is to be performed. |
| --obclient-bin | No | string | obclient | The path to the directory where the binary files of OBClient are stored. |
| --java-bin | No | string | java | The path to the directory where the Java binary files are stored. |
| --tmp-dir | No | string | ./tmp | The temporary directory to be used for the TPC-C test. Automatically generated configuration files, auto-tuned SQL files, and test output files will be stored in this directory. |
| --bmsql-dir | No | string | Empty | The installation directory of BenchmarkSQL. You need to specify this option only if you manually compile and install BenchmarkSQL. If you use obtpcc, this option is not required. |
| --bmsql-jar | No | string | Empty | The path to the directory where the JAR file of BenchmarkSQL is stored. If you do not specify the path, and the BenchmarkSQL directory is not specified, the default installation directory generated by obtpcc is used. If the BenchmarkSQL directory is specified, the JAR file in the `<bmsql-dir>/dist` directory is used. |
| --bmsql-libs | No | string | Empty | If the BenchmarkSQL directory is specified, the JAR files in the `<bmsql-dir>/lib` and `<bmsql-dir>/lib/oceanbase` directories are used. If you use obtpcc, this option is not required. |
| --bmsql-sql-dir | No | string | Empty | The path to the directory where the SQL files for the TPC-C test are stored. If you do not specify the path, OceanBase Deployer (OBD) uses the SQL files that are automatically generated. |
| --warehouses | No | int | Empty | The number of warehouses for the TPC-C test data set. If you do not specify a value, the assigned value is 20 times the number of CPU cores allocated to the OceanBase cluster. |
| --load-workers | No | int | Empty | The number of concurrent worker threads for building the test data set. If you do not specify a value, the number of CPU cores per server or the size of tenant memory (GB)/2, whichever is smaller, is used. |
| --terminals | No | int | Empty | The number of virtual terminals to be used for the TPC-C test. If you do not specify a value, the number of CPU cores for the OceanBase cluster × 15 or the number of warehouses × 10, whichever is smaller, is used. |
| --run-mins | No | int | 10 | The amount of time allocated for the execution of the TPC-C test. |
| --test-only | No | bool | false | Specifies that the test is performed without data construction. |
| -O/--optimization | No | int | 1 | The degree of auto-tuning. Valid values: `0`, `1`, and `2`. `0` indicates that auto-tuning is disabled. `1` indicates that the auto-tuning parameters that take effect without a cluster restart are modified. `2` indicates that all auto-tuning parameters are modified. If necessary, the cluster is restarted to make all parameters take effect. |
