CockroachDB automatically creates an emergency ballast file at startup time. The cockroach debug ballast
command is still available but deprecated. For more information about how automatic ballast file creation works, see automatic ballast files.
The cockroach debug ballast
command creates a large, unused file that you can place in a node's storage directory. In the case that a node runs out of disk space and shuts down, you can delete the ballast file to free up enough space to be able to restart the node.
- Do not run
cockroach debug ballast
with a unixroot
user. Doing so brings the risk of mistakenly affecting system directories or files. -
cockroach debug ballast
now refuses to overwrite the target ballast file if it already exists. This change is intended to prevent mistaken uses of theballast
command. Consider adding anrm
command to scripts that integratecockroach debug ballast
, or provide a new file name every time and then remove the old file. - In addition to placing a ballast file in each node's storage directory, it is important to actively monitor remaining disk space.
- Ballast files may be created in many ways, including the standard
dd
command.cockroach debug ballast
uses thefallocate
system call when available, so it will be faster thandd
.
Subcommands
While the cockroach debug
command has a few subcommands, users are expected to use only the zip
, encryption-active-key
, merge-logs
, list-files
, tsdump
, and ballast
subcommands.
We recommend using the encryption-decrypt
and job-trace
subcommands only when directed by the Cockroach Labs support team.
The other debug
subcommands are useful only to Cockroach Labs. Output of debug
commands may contain sensitive or secret information.
Synopsis
Create a ballast file:
$ cockroach debug ballast [path to ballast file] [flags]
View help:
$ cockroach debug ballast --help
Flags
Flag | Description |
---|---|
--size -z |
The amount of space to fill, or to leave available, in a node's storage directory via a ballast file. Positive values equal the size of the ballast file. Negative values equal the amount of space to leave after creating the ballast file. This can be a percentage (notated as a decimal or with %) or any bytes-based unit, for example:--size=1000000000 ----> 1000000000 bytes --size=1GiB ----> 1073741824 bytes --size=5% ----> 5% of available space --size=0.05 ----> 5% of available space --size=.05 ----> 5% of available space Default: 1GB |
Examples
Create a 1GB ballast file (default)
$ cockroach debug ballast cockroach-data/ballast.txt
Create a ballast file of a different size
$ cockroach debug ballast cockroach-data/ballast.txt --size=2GB