Merge pull request #3281 from taniabogatsch/block-size

Configurable block size

docs/configuration/pragmas.md

@@ -561,3 +561,23 @@ Disable force parallel query processing:
 ```sql
 PRAGMA disable_verify_parallelism;
 ```
+
+## Block Sizes
+
+When persisting a database to disk, DuckDB writes to a dedicated file containing a list of blocks holding the data.
+In the case of a file that only holds very little data, e.g., a small table, the default block size of 256KB might not be ideal.
+Therefore, DuckDB's storage format supports different block sizes.
+
+There are a few constraints on possible block size values.
+
+* Must be a power of two.
+* Must be greater or equal to 16384 (16 KB).
+* Must be lesser or equal to 262144 (256 KB).
+
+You can set the default block size for all new DuckDB files created by an instance like so:
+
+```sql
+SET default_block_size = '16384';
+```
+
+It is also possible to set the block size on a per-file basis, see [`ATTACH`]({% link docs/sql/statements/attach.md %}) for details.

docs/sql/statements/attach.md

@@ -26,6 +26,12 @@ Attach the database `file.db` in read only mode:
 ATTACH 'file.db' (READ_ONLY);
 ```
 
+Attach the database `file.db` with a block size of 16KB:
+
+```sql
+ATTACH 'file.db' (BLOCK SIZE 16384);
+```
+
 Attach a SQLite database for reading and writing (see the [`sqlite` extension]({% link docs/extensions/sqlite.md %}) for more information):
 
 ```sql
@@ -113,6 +119,16 @@ USE memory_db;
 
 <div id="rrdiagram2"></div>
 
+## Options
+
+<div class="narrow_table"></div>
+
+| Name                        | Description                                                                                                                 | Type      | Default value |
+|-----------------------------|-----------------------------------------------------------------------------------------------------------------------------|-----------|---------------|
+| `access_mode`               | Access mode of the database (**AUTOMATIC**, **READ_ONLY**, or **READ_WRITE**)                                               | `VARCHAR` | `automatic`   |
+| `type`                      | The file type (**DUCKDB** or **SQLITE**), or deduced from the input string literal (MySQL, PostgreSQL).                     | `VARCHAR` | `DUCKDB`      |
+| `block_size`                | The block size of a new database file. Must be a power of two and within [16384, 262144]. Cannot be set for existing files. | `UBIGINT` | `262144`      |
+
 ## Name Qualification
 
 The fully qualified name of catalog objects contains the *catalog*, the *schema* and the *name* of the object. For example: