On-disk files managed by Kuzu

Database files

Note

Before version 0.11.0, Kuzu required the database path to be a directory, and created multiple files within that directory. This section only describes Kuzu versions starting from 0.11.0, when it switched to a single-file format.

Kuzu uses a single-file format for persisting the data to disk. That is, the database is stored in a single file rather than a directory of files. The single-file format is also used by other popular embedded databases such as DuckDB and SQLite.

When opening a Kuzu database in the “on-disk” read-write mode, Kuzu creates the database file at the specified path if it doesn’t already exist. It can also create other temporary files at runtime. These files are automatically cleaned up when the database is closed.

The following table lists the different types of files that are created and managed by Kuzu. The database file is the only necessary file to open a database. The rest of the files are created in the same directory as the database file.

File Type	Example
Database file	example.kuzu
Lock file	example.kuzu.lock
Write-ahead log file	example.kuzu.wal
Shadow file	example.kuzu.shadow
Temporary file	example.kuzu.tmp

Database file

This is a persistent file that stores all data valid as of the last checkpoint. It is only created when the database is opened in the read-write on-disk mode.

Lock file

This is a temporary file created by a Kuzu process to ensure that a second Kuzu process cannot open the same database file simultaneously in the read-write mode.

For more details, see the documentation on concurrency.

Write-ahead log (WAL) file

This is a temporary file that records all database updates since the last checkpoint. It is only created when write transactions are committed in the database and is removed when a checkpoint succeeds.

Shadow file

This is a temporary file that is created to help run checkpoint operations. It is only created during a checkpoint, and is removed when the checkpoint succeeds.

Temporary file

This is a general-purpose temporary file used to spill intermediate memory data during query execution. It is only created under high memory pressure, i.e., when the size of the data being processed is larger than the available memory. In such a scenario, intermediate data is spilled to disk. The file is automatically removed when a query finishes its execution.

Official extension downloads

When you install an official extension by executing INSTALL <extension_name>, Kuzu downloads the extension libraries from the official repo into your home directory at ~/.kuzu/extensions. When loading an extension using LOAD <extension_name>, Kuzu looks for the extension in the same directory.

HTTPS local cache

For the httpfs extension, when its local cache is enabled using the command CALL HTTP_CACHE_FILE=TRUE, Kuzu saves the cached files under .cache in the extension’s local directory inside ~/.kuzu/extensions. The cached files are always removed when the transaction commits or rolls back.

History file

The Kuzu CLI records the history of executed Cypher queries in a persistent history.txt file. By default, the file is stored in the current working directory from where the CLI is started. You can configure a different location for the history file using the --path_history or -p flags. See kuzu --help for more details.