Configure automatic scale-out of disk space for data files|V4.2.5| docs|Distributed Database

Configure automatic scale-out of disk space for data files

Last Updated：2025-11-26 14:12:55 Updated

OceanBase Database supports automatic scale-out of disk space available for data files based on the actual situation.

Background information

In OceanBase Database, the files used to store data are named block_file. These block_file files are located in the /store/sstable directory under the installation directory of OBServer nodes. They are created after each OBServer node is started. The size of the block_file files is specified by the datafile_size or datafile_disk_percentage parameter. For more information about the directory of data files on OBServer nodes, see Structure of the OBServer installation directory.

Prior to OceanBase Database V4.2.0, the system adopted a pre-allocation approach where a portion of disk space was reserved for data files. This ensured that the data files occupied a contiguous section of the disk space, preventing insufficient disk resources caused by other applications preempting the disk. However, this pre-allocation method occupied a significant amount of disk space, and even if the disk space was not being used, it could not be released.

To address this issue, OceanBase Database introduced several parameters for progressive disk space utilization for data files since V4.2.0. The system first pre-allocates a reasonable disk size for the data files and then automatically scales out based on the actual disk usage and user configuration.

OceanBase Database automatically scales out the disk space available for the data file on an OBServer node based on the following parameters:

datafile_size: the size of disk space available for the data file. The default value is 0M.
datafile_disk_percentage: the percentage of disk space that can be occupied by the data file. The default value is 0.
datafile_next: the automatic scale-out step for the disk space for the data file. The default value is 0M, which indicates that automatic scale-out is disabled. To enable automatic scale-out, you need to set the parameter to a nonzero value.
datafile_maxsize: the maximum size of disk space allowed for automatic scale-out for the data file. The default value is 0M, which indicates that automatic scale-out is disabled.

Take note of the following rules when you set the preceding parameters:

You can use either datafile_size or datafile_disk_percentage to configure the disk space available for the data file.
- If you set both datafile_size and datafile_disk_percentage to nonzero values, the value of datafile_size prevails.
- If datafile_size is set to 0M and datafile_disk_percentage is set to 0, the system automatically calculates the percentage of disk space available for the data file based on whether logs and data are stored on the same disk.
  - If logs and data are stored on the same disk, the percentage of disk space available for the data file is 60%.
  - If logs and data are stored on different disks, the percentage of disk space available for the data file is 90%.
When you set datafile_maxsize, make sure that its value is greater than the current size of disk space available for the data file, which is specified by datafile_size or datafile_disk_percentage. Otherwise, automatic scale-out is not triggered.
If the value of datafile_maxsize exceeds the maximum available space of the current disk, the actual size of available space is used as the maximum value.
For datafile_next, note that:
- If datafile_next is set to a value smaller than or equal to 1G, the actual value of datafile_next is calculated by using the min(1G, datafile_maxsize × 10%) formula.
- If datafile_next is set to a value greater than 1G, the actual value of datafile_next is calculated by using the min(datafile_next, Remaining disk space) formula.

Considerations and limitations

When you configure automatic scale-out of disk space for the data file, we recommend that you set the initial value of datafile_next to 20% of the value of datafile_maxsize, to avoid frequent scale-out.
After you enable automatic scale-out of disk space for data files, you must make a proper capacity plan for other applications deployed on the same server, and make sure that the maximum size of disk space available for scale-out is no smaller than the value of datafile_maxsize.
At present, automatic scale-in of disk space for data files is not supported.
If you do not want to enable automatic scale-out, you can set datafile_next or datafile_maxsize to 0M, or retain the default value 0M. Then, the system will reserve a part of the disk space for the data file based on the original pre-allocation method.

Enable automatic scale-out of disk space for data files

Step 1: View the current parameter values

Before you configure dynamic disk space scale-out for data files, you must first view the current parameter values.

Execute the following statements to view parameter values:

SHOW PARAMETERS LIKE 'datafile_size';

SHOW PARAMETERS LIKE 'datafile_disk_percentage';

SHOW PARAMETERS LIKE 'datafile_next';

SHOW PARAMETERS LIKE 'datafile_maxsize';

Step 2: Configure dynamic disk space scale-out for data files

You can modify the parameter values for automatic disk space scale-out for data files based on the actual situation.

datafile_size (or datafile_disk_percentage), datafile_next, and datafile_maxsize are set when your cluster is started

If you set datafile_size (or datafile_disk_percentage), datafile_next, and datafile_maxsize to nonzero values when you deploy OceanBase Database and start your OceanBase cluster:

If the value of datafile_maxsize is greater than that of datafile_size, or greater than the disk space size calculated based on datafile_disk_percentage, automatic scale-out takes effect after the cluster is started.
If the value of datafile_maxsize is smaller than that of datafile_size, or smaller than the disk space size calculated based on datafile_disk_percentage, you must first change the value of datafile_maxsize to a value greater than that of datafile_size before you enable automatic disk space scale-out for data files.

Only datafile_size or datafile_disk_percentage is set when the cluster is started

If you set only datafile_size or datafile_disk_percentage when you deploy OceanBase Database and start your OceanBase cluster, you need to manually set only datafile_maxsize and datafile_next and make sure that the value of datafile_maxsize is greater than that of datafile_size, or greater than the disk space size calculated based on datafile_disk_percentage.

datafile_size (or datafile_disk_percentage), datafile_next, and datafile_maxsize are not set when the cluster is started

If you do not set datafile_size (or datafile_disk_percentage), datafile_next, or datafile_maxsize when you deploy OceanBase Database and start your OceanBase cluster, you can enable automatic disk space scale-out for data files by referring to the following procedure.

Notice

Whether datafile_size or datafile_disk_percentage is set when the cluster is started for the first time affects the initial size of disk space available for data files.

To do so, perform the following steps:

Log in to the sys tenant of the cluster as the root user.
Execute the following statement to query the size of the pre-allocated disk space:
```
SELECT data_disk_allocated/1024/1024/1024 AS datafile_G FROM oceanbase.GV$OB_SERVERS;
```
A sample query result is as follows:
```
+-------------------+
| datafile_G        |
+-------------------+
| 1770.000000000000 |
+-------------------+
1 row in set
```
The query result shows that the size of the disk space pre-allocated to the data file is 1,770 GB, which is about 1.7 TB.
Set datafile_maxsize to a value greater than that of data_disk_allocated, and set datafile_next to a nonzero value.

Here are some examples:
```
ALTER SYSTEM SET datafile_maxsize='4TB';
```
```
ALTER SYSTEM SET datafile_next='1TB';
```
Execute the following statement to verify whether the automatic scale-out settings take effect:
```
SELECT data_disk_allocated/1024/1024/1024 AS datafile_G, data_disk_capacity/1024/1024/1024 AS datafile_max_G FROM oceanbase.GV$OB_SERVERS;
```
A sample query result is as follows:
```
+-------------------+-------------------+
| datafile_G        | datafile_max_G    |
+-------------------+-------------------+
| 1770.000000000000 | 4096.000000000000 |
+-------------------+-------------------+
1 row in set
```
The query result shows that the maximum capacity (data_disk_capacity) for automatic disk space scale-out for the data file is the value of datafile_maxsize, and the value of data_disk_capacity is greater than that of data_disk_allocated. This indicates that the automatic scale-out settings take effect.

What to do next

After the configuration, the system automatically scales out the disk space for data files based on the actual situation and the values of datafile_next and datafile_maxsize.

References

Modify cluster-level parameters