feat: add sqlite init docs (#75)

tconbeer · Apr 25, 2024 · 0c33c6a · 0c33c6a
1 parent 0010453
commit 0c33c6a
Show file tree

Hide file tree

Showing 3 changed files with 42 additions and 1 deletion.
diff --git a/src/docs/adapters.md b/src/docs/adapters.md
@@ -18,7 +18,7 @@ Each adapter has its own configuration options, detailed in their own section in
 Core adapters are created and maintained by the maintainers of Harlequin.
 
 - [DuckDB](duckdb/index)
-- [SQLite](sqlite)
+- [SQLite](sqlite/index)
 - [Postgres](postgres/index) (also supports Redshift)
 - [MySQL](mysql/index)
 - [ODBC](odbc/index) (supports MS SQL Server, Oracle, and others)

diff --git a/src/docs/sqlite.md → src/docs/sqlite/index.md b/src/docs/sqlite.md → src/docs/sqlite/index.md
diff --git a/src/docs/sqlite/initialization.md b/src/docs/sqlite/initialization.md
@@ -0,0 +1,41 @@
+---
+title: Initialization Scripts
+menuOrder: 31
+---
+
+Each time you start Harlequin, it will execute commands from a SQLite [initialization script](https://sqlite.org/cli.html). Such a script can contain both SQL and SQLite CLI [dot commands](https://sqlite.org/cli.html#special_commands_to_sqlite3_dot_commands_). For example:
+
+```sql
+.open './my-database.sqlite'
+create table foo as
+    select 1;
+```
+
+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 `~/.sqliterc`. However, you can provide a different path using the `--init-path` option (aliased to `-i` or `-init`):
+
+```bash
+harlequin -a sqlite --init-path path/to/my/script.sql
+```
+
+## Disabling Initialization
+
+If you would like to open Harlequin without running the script you have at `~/.sqliterc`, you can either pass a nonexistent path (or `/dev/null`) to the option above, or start Harlequin with the `--no-init` option:
+
+```bash
+harlequin -a sqlite --no-init
+```
+
+## Supported Dot Commands
+
+Most SQLite 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 an `attach ...` statement.
+- `.load` is rewritten to a `select load_extension(...)` statement.
+
+To request additional dot command support in Harlequin, [open an issue](https://github.com/tconbeer/harlequin/issues/new/choose).