Init Script (#23)

* docs: add troubleshooting for duckdb version * docs: add page on init scripts
tconbeer · Oct 3, 2023 · 599504b · 599504b
1 parent ba45bab
commit 599504b
Show file tree

Hide file tree

Showing 7 changed files with 113 additions and 9 deletions.
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,6 +15,8 @@ After installing Python 3.8 or above, install Harlequin using `pip` or `pipx` wi
 pipx install harlequin
 ```
 
+If you want to control the version of DuckDB that Harlequin uses, see the [Troubleshooting](troubleshooting#duckdb-version-mismatch) page.
+
 ## Using Harlequin
 
 From any shell, to open one or more DuckDB database files:
@@ -40,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
@@ -17,6 +17,7 @@ Sorry to see you here. Terminals can be finicky. Please see below for solutions
 1. [Copy-Paste](#copying-and-pasting)
 1. [Colors](#colors)
 1. [Fonts](#fonts)
+1. [DuckDB Version Mismatch](#duckdb-version-mismatch)
 
 ## Key Bindings
 
@@ -50,7 +51,7 @@ Otherwise, you can press <Key>F1</Key> to open the command palette, then type an
 
 ## Copying and Pasting
 
-<span class="text-purple italic font-bold">Note: Currently copying and pasting is only supported by the query editor, not the other widgets.</span>
+**Note: Currently copying and pasting is only supported by the query editor, not the other widgets.**
 
 Harlequin's query editor supports cut, copy, and paste. However, this is more complex than it seems. If these features are not working for you, there could be a number of root causes. This section walks through how copy-paste works in Harlequin, and offers some solutions for common problems.
 
@@ -67,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`.
 
@@ -126,11 +128,11 @@ Modern terminals can display different fonts. Harlequin looks great in a number
 
 To use a different font with Harlequin, download and install the font, and then configure your terminal to use that font.
 
-<span class="text-purple italic font-bold">Note for Mac Terminal.app Users:</span>
+**Note for Mac Terminal.app Users:**
 
 Only some fonts render right with the default Terminal app. You may need to adjust your line spacing. [See here](https://textual.textualize.io/FAQ/#why-doesnt-textual-look-good-on-macos) for instructions.
 
-<span class="text-purple italic font-bold">Note for WSL2 and Windows Terminal users:</span>
+**Note for WSL2 and Windows Terminal users:**
 
 Windows Terminal runs in Windows and attaches your Linux shell over the WSL network. You need to install your font in **Windows** for this to work.
 
@@ -141,3 +143,58 @@ If you are using the default Mac Terminal or Windows Command Prompt, you may wan
 - Windows (native or WSL2): [Windows Terminal](https://apps.microsoft.com/store/detail/windows-terminal/9N0DX20HK701)
 - Mac: [iTerm2](https://iterm2.com/)
 - Linux: [Gnome](https://help.gnome.org/users/gnome-terminal/stable/), [Alacritty](https://snapcraft.io/alacritty)
+
+## DuckDB Version Mismatch
+
+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 example, attempting to open a DuckDB database file with different versions of DuckDB will result in an error that looks like this:
+
+```
+IO Error: Trying to read a database file with version number 64, but we can
+only read version 51.
+The database file was created with an newer version of DuckDB.
+
+The storage of DuckDB is not yet stable; newer versions of DuckDB cannot
+read old database files and vice versa.
+The storage will be stabilized when version 1.0 releases.
+
+For now, we recommend that you load the database file in a supported version
+of DuckDB, and use the EXPORT DATABASE command followed by IMPORT DATABASE
+on the current version of DuckDB.
+
+See the storage page for more information:
+https://duckdb.org/internals/storage
+```
+
+### Determining the Version of the DuckDB CLI on your Path
+
+First, determine what version of DuckDB you are running outside of Harlequin, and how it was installed. You can find the path to the executable with `which duckdb` on Unix systems, or `get-command duckdb` in Windows Powershell. This path should give you a hint about how it was installed; you could also try `pipx list` or `brew list` to see if DuckDB was installed by either of those tools.
+
+Next, run `duckdb --version`, which should display the version number and commit SHA, like `v0.9.0 0d84ccf478`.
+
+Alternatively, the [storage page](https://duckdb.org/internals/storage) linked to in the error message provides a mapping of storage versions to DuckDB versions (e.g., we can see that storage version 64 maps to DuckDB 0.9.0, and 51 maps to DuckDB 0.8.0).
+
+### Determining the Version of DuckDB Used by Harlequin
+
+Open Harlequin, then in the query editor, type or paste `select version()`. In the Results Viewer, the version number should be displayed.
+
+### Changing the Version of DuckDB Used by Harlequin
+
+**Note:** Harlequin requires DuckDB >= 0.8.0 due to changes in the Python API in that version.
+
+You can add an explicit pin to a DuckDB version alongside Harlequin's installation. The following examples assume you would like to pin the version to `0.9.0`.
+
+#### With pipx
+
+You must "inject" the pinned dependency into the Harlequin installation with: `pipx inject harlequin duckdb==0.9.0`.
+
+#### With pip
+
+With your venv activated, simply install the pinned version with `pip install duckdb==0.9.0`, or add `duckdb==0.9.0` to your `requirements.txt`.
+
+#### With pipenv
+
+Run `pipenv add duckdb==0.9.0`.
+
+#### With Poetry
+
+Run `poetry add duckdb==0.9.0`.
diff --git a/src/mdsvex/components/strong.svelte b/src/mdsvex/components/strong.svelte
@@ -0,0 +1 @@
+<strong class="font-bold italic text-purple"><slot /></strong>
diff --git a/src/mdsvex/docs.svelte b/src/mdsvex/docs.svelte
@@ -9,8 +9,9 @@
   import ol from "./components/ol.svelte";
   import p from "./components/p.svelte";
   import pre from "./components/pre.svelte";
+  import strong from "./components/strong.svelte";
   import ul from "./components/ul.svelte";
-  export { a, code, h2, h3, h4, li, img, ol, p, pre, ul };
+  export { a, code, h2, h3, h4, li, img, ol, p, pre, strong, ul };
 </script>
 
 <!-- pre component styles might get pruned, since the pre component is
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		<strong class="font-bold italic text-purple"><slot /></strong>