docs: add page on init scripts

tconbeer · tconbeer · Oct 3, 2023 · Oct 2, 2023 · Oct 2, 2023 · Oct 2, 2023
commit d11b9d4cee50b4dbd12aa5e78fdadabefd137373
diff --git a/src/docs/extensions.md b/src/docs/extensions.md
@@ -1,6 +1,6 @@
 ---
 title: Loading Extensions
-menuOrder: 30
+menuOrder: 20
 ---
 
 You can install and load [DuckDB extensions](https://duckdb.org/docs/extensions/overview.html) when starting Harlequin, by passing the `-e` or `--extension` flag one or more times:
@@ -21,3 +21,5 @@ You can also install extensions from custom repos, using the `--custom-extension
 ```bash
 harlequin -u -e prql --custom-extension-repo welsch.lu/duckdb/prql/latest
 ```
+
+Alternatively, you can use DuckDB's SQL API for loading and installing extensions, either in Harlequin's Query Editor or in an [initialization script](initialization).
diff --git a/src/docs/getting-started.md b/src/docs/getting-started.md
@@ -15,7 +15,7 @@ After installing Python 3.8 or above, install Harlequin using `pip` or `pipx` wi
 pipx install harlequin
 ```
 
-**Note:** Harlequin depends on DuckDB, and installing it in an isolated environment (e.g., using `pipx` or in a fresh virtual environment) will cause it to install DuckDB. If you have DuckDB installed elsewhere (e.g., if you already installed DuckDB with `pipx` or Homebrew), you may want to pin the version of DuckDB that Harlequin uses. For more info, see the [Troubleshooting](troubleshooting#duckdb-version-mismatch) page.
+If you want to control the version of DuckDB that Harlequin uses, see the [Troubleshooting](troubleshooting#duckdb-version-mismatch) page.
 
 ## Using Harlequin
 
@@ -42,7 +42,7 @@ harlequin -r "path/to/duck.db"
 To view all command-line options for Harlequin, after installation, simply type:
 
 ```bash
-harlequin -h
+harlequin --help
 ```
 
 To view a list of all key bindings (keyboard shortcuts) within the app, press <Key>F1</Key>. You can also view this list outside the app [here](bindings).
diff --git a/src/docs/initialization.md b/src/docs/initialization.md
@@ -0,0 +1,41 @@
+---
+title: Initialization Scripts
+menuOrder: 5
+---
+
+Each time you start Harlequin, it will execute commands from a DuckDB [initialization script](https://duckdb.org/docs/api/cli#configuring-the-cli). Such a script can contain both SQL and DuckDB CLI [dot commands](https://duckdb.org/docs/api/cli#special-commands-dot-commands). For example:
+
+```sql
+INSTALL httpfs;
+LOAD httpfs;
+SET s3_region='us-west-2';
+.open './my-database.db'
+```
+
+Multi-line SQL is allowed, but must be terminated by a semicolon. Dot commands must be newline-terminated.
+
+## Configuring the Script Location
+
+By default, Harlequin will execute the script found at `~/.duckdbrc`. However, you can provide a different path using the `--init-path` option (aliased to `-i` or `-init`):
+
+```bash
+harlequin --init-path path/to/my/script.sql
+```
+
+## Disabling Initialization
+
+If you would like to open Harlequin without running the script you have at `~/.duckdbrc`, you can either pass a nonexistent path to the option above, or start Harlequin with the `--no-init` option:
+
+```bash
+harlequin --no-init
+```
+
+## Supported Dot Commands
+
+Most DuckDB CLI dot commands affect the behavior of the CLI, like the format of its output. Since these are irrelevant to Harlequin, they are ignored.
+
+Currently Harlequin rewrites the following dot commands to SQL and executes the SQL:
+
+- `.open` is rewritten to `attach` and `use` statements.
+
+To request additional dot command support in Harlequin, [open an issue](https://github.com/tconbeer/harlequin/issues/new/choose).
diff --git a/src/docs/motherduck.md b/src/docs/motherduck.md
@@ -17,9 +17,9 @@ harlequin "md:" "local_duck.db"
 
 ## Authentication Options
 
-1. **Web browser:** Run `harlequin "md:"`, and Harlequin will attempt to open a web browser where you can log in.
-2. **Environment variable:** Set the `motherduck_token` variable before running `harlequin "md:"`, and Harlequin will authenticate with MotherDuck using your service token.
-3. **CLI option:** You can pass a service token to Harlequin with `harlequin "md:" --md_token <my token>`
+1. Web browser: Run `harlequin "md:"`, and Harlequin will attempt to open a web browser where you can log in.
+2. Environment variable: Set the `motherduck_token` variable before running `harlequin "md:"`, and Harlequin will authenticate with MotherDuck using your service token.
+3. CLI option: You can pass a service token to Harlequin with `harlequin "md:" --md_token <my token>`
 
 ## SaaS Mode
 

diff --git a/src/docs/troubleshooting.md b/src/docs/troubleshooting.md
@@ -68,6 +68,7 @@ There are two mechanisms for Harlequin to receive clipboard data when you initia
     - Copy some text outside of Harlequin.
     - Focus on the Harlequin query editor, then press <Key>ctrl+u</Key> (`u`, not `v` for this step!).
     - If Harlequin does not paste anything, or if it pastes something different from what you just copied, Harlequin cannot access the system clipboard. You can work around this by pasting using your terminal's built-in paste functionality, or by fixing its access to the system clipboard (keep reading).
+    - Starting in Harlequin v1.1, you should see a notification pop-up if Harlequin cannot access your system clipboard.
 
 2.  Harlequin receives a native `Paste` message from the terminal. To trigger a `Paste` message, you want to use the same keys that you would to paste into your shell. This might be <Key>ctrl+v</Key>, <Key>shift+insert</Key>, or a right click of your mouse. When Harlequin receives a `Paste` message, it will insert the contents of that message into the query editor. Since this doesn't rely on the clipboard, this should work on nearly any terminal, whether Harlequin and the terminal share a host or not. Many terminals allow you to configure the key or mouse bindings for `Paste`.