Add files managed by Kuzu page

astro.config.mjs

@@ -227,6 +227,7 @@ export default defineConfig({
                         { label: 'Performance debugging', link: '/developer-guide/performance-debugging' },
                         { label: 'Testing framework', link: '/developer-guide/testing-framework' },
                         { label: 'Join order hints', link: '/developer-guide/join-order-hint' },
+                        { label: 'Files', link: '/developer-guide/files' },
                         {
                             label: 'Database internals',
                             items: [

src/content/docs/developer-guide/files.mdx

@@ -0,0 +1,79 @@
+---
+title: Files managed by Kuzu
+description: All the files that are created and managed by Kuzu.
+---
+
+## Database files
+
+:::note[Note]
+Prior to version 0.11.0, Kuzu required the database path to be a directory and automatically created and
+managed multiple files within that directory. The information in this section is only relevant for
+Kuzu versions beginning from 0.11.0, where we switched to a single-file format.
+:::
+
+Kuzu uses a single-file format for persisting the data to disk -- i.e., the database is stored in a file rather than a directory.
+The single-file format has also been adopted by other embedded databases, such as DuckDB and SQLite.
+
+When opening a Kuzu database in "on-disk" read-write mode, Kuzu creates the database file at the specified
+path if it doesn't exist. Additionally, temporary files might be created during runtime.
+
+Below, we list all types of files that are created and managed by Kuzu.
+
+| File Type | Example |
+| --- | --- |
+| Database file | `db_file` |
+| Lock file | `db_file.lock` |
+| WAL file | `db_file.wal`  |
+| Shadow file | `db_file.shadow` |
+| Tmp file | `db_file.tmp` |
+| Extension files | `~/.kuzu/extensions/0.11.0/osx_arm64/json/libjson.kuzu_extension` |
+
+#### Database file
+
+This is a **persistent file** (if the database is opened in read-write, on-disk mode) that persists
+all the data (since the last checkpoint) to disk.
+
+#### Lock file
+
+This is a **temporary file** that is created to ensure that no two Kuzu `Database` processes can open
+the same database file simultaneously when one of them is in the read-write mode.
+The lock file is removed when the Kuzu process exits.
+
+For more details, please see [this page](https://docs.kuzudb.com/concurrency/#limitations-of-creating-multiple-database-objects)
+on the limitations of creating multiple database objects due to Kuzu being an embedded, in-process database.
+
+#### WAL file
+
+This is a **temporary file** that records all transaction changes since the last checkpoint.
+The file 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 during the checkpoint phase.
+It is only created when the database starts a checkpoint, and is removed when the Kuzu process exits.
+
+#### Tmp file
+
+This is a **temporary file** for spilling in-memory intermediate data during query execution.
+It is only created when the database's memory pressure is high and the data being handled is larger-than-memory.
+In these cases, intermediate data is spilled to disk. Once created, this file is removed when the query
+finishes executing and the database exits.
+
+## Extension binaries
+
+Whenever you install an extension by executing `INSTALL <extension_name>`, Kuzu downloads the extension's
+binaries from the official repo into your local directory, for e.g., `~/.kuzu/extensions`.
+When loading the extension via `LOAD <extension_name>`, Kuzu reads from the local extension directory `~/.kuzu/extensions` by default.
+
+### HTTPS local cache
+
+For the `httpfs` extension, when its [local cache](https://docs.kuzudb.com/extensions/httpfs/#local-cache)
+is enabled via the command `CALL HTTP_CACHE_FILE=TRUE`, Kuzu saves the locally cached files under `.cache`
+in the extension's local directory.
+
+The locally cached files are always removed when the transaction commits or rolls back.
+
+## History file
+
+The `history.txt` file is a **persistent file** created by the Kuzu CLI or Kuzu Explorer in the local
+directory where it's opened. The file records a history of Cypher queries executed within the CLI or Kuzu Explorer.