1.1.0

Author: mbostock

docs/databases.html

@@ -31,11 +31,11 @@
     **If query results are saved, how do I update them?** In Observable Desktop, you can re-run a SQL cell by clicking the **Play** button, by hitting <span style="font-family: var(--sans-serif);">**shift-return**</span>, or by clicking on the query age in the cell toolbar. In Observable Notebook Kit, delete the corresponding file from the `.observable/cache` directory; you can also use continuous deployment, such as GitHub Actions, to refresh data automatically.
   </script>
   <script id="28" type="text/markdown">
-    **How do I configure my database?** When using DuckDB or (localhost) Postgres with the default settings, no configuration is required; simply specify `duckdb`, `postgres`, or a `.duckdb` (or `.db`) file as the **database** in the SQL cell. Note: you must save your notebook before running queries, since where you save the notebook determines which databases are accessible and where query results are saved. To configure databases, edit the <code>.observable/<wbr>databases.json</code> file alongside your notebook; see below for details. For example, if your notebooks are stored in `docs`,
+    **How do I configure my database?** When using DuckDB, SQLite, or (localhost) Postgres with the default settings, no configuration is required; simply specify `duckdb`, `sqlite`, `postgres`, or a `.duckdb` or `.db` file as the **database** in the SQL cell. Note: you must save your notebook before running queries, since where you save the notebook determines which databases are accessible and where query results are saved. To configure databases, edit the <code>.observable/<wbr>databases.json</code> file alongside your notebook; see below for details. For example, if your notebooks are stored in `docs`,
     then a notebook `docs/example.html` can access any database configured in <code>docs/<wbr>.observable/<wbr>databases.json</code>. In the future, Observable Desktop will provide a built-in UI for configuring databases.
   </script>
   <script id="15" type="text/markdown">
-    **Which databases are supported?** Currently DuckDB, Snowflake, and Postgres (PostgreSQL). The Postgres driver should also work with Postgres-compatible databases such as ClickHouse, Amazon Redshift, and Google Cloud SQL. We plan on adding more data connectors soon, notably Google BigQuery and Databricks. Our data connectors are [open-source](https://github.com/observablehq/notebook-kit/tree/main/src/databases) and we welcome contributions of additional database drivers! While you can query OLTP databases, we recommend OLAP databases because fast _ad hoc_ queries greatly accelerate analysis.
+    **Which databases are supported?** Currently DuckDB, SQLite, Snowflake, and Postgres (PostgreSQL). The Postgres driver should also work with Postgres-compatible databases such as ClickHouse, Amazon Redshift, and Google Cloud SQL. We plan on adding more data connectors soon, notably Google BigQuery and Databricks. Our data connectors are [open-source](https://github.com/observablehq/notebook-kit/tree/main/src/databases) and we welcome contributions of additional database drivers! While you can query OLTP databases, we recommend OLAP databases because fast _ad hoc_ queries greatly accelerate analysis.
   </script>
   <script id="35" type="text/markdown">
     **How do I query my database?** Insert a new cell, say by clicking the <b>+</b> button between cells. Convert the new cell to SQL by hitting down or <span style="font-family: var(--sans-serif);">⌘4</span>. By default, SQL cells query the default `duckdb` in-memory database. To query a different database, edit the **database** in the cell toolbar, then click ↩︎ or hit <span style="font-family: var(--sans-serif);">return</span>. Then refocus the SQL cell, edit your query, and hit <span style="font-family: var(--sans-serif);">shift-return</span> to run it.
@@ -151,7 +151,7 @@
     **What about custom database clients and DuckDB-Wasm?** If you specify a SQL's database using `var:` (such as `var:db`), you can then provide a custom database client of the given name (such as `db`) that runs in the browser. This feature is most often used with `DuckDBClient` (DuckDB-Wasm), but you can provide any object that exposes a `sql` tagged template literal.
   </script>
   <script id="10" type="text/markdown">
-    **How do I use databases with Notebook Kit?** Database drivers come bundled with Observable Desktop, but are not installed by default with Notebook Kit. Database drivers are instead marked as optional peer dependencies, and you must install them yourself.
+    **How do I use databases with Notebook Kit?** Database drivers come bundled with Observable Desktop, but with the exception of SQLite are not installed by default with Notebook Kit. Database drivers are instead marked as optional peer dependencies, and you must install them yourself.
 
     To install the DuckDB driver:
 
@@ -202,6 +202,18 @@
 
     The **path** option stores the relative path to the DuckDB (`.duckdb`) database file; if not specified, the database will be in-memory (`:memory:`). The **options** object contains any [DuckDB configuration options](https://duckdb.org/docs/stable/configuration/overview.html).
   </script>
+  <script id="64" type="text/markdown">
+    **How do I configure SQLite?** The following options are supported:
+
+    ```ts
+    type SQLiteConfig = {
+      type: "sqlite";
+      path?: string;
+    }
+    ```
+
+    The **path** option stores the relative path to the SQLite (`.db`) database file; if not specified, the database will be in-memory (`:memory:`).
+  </script>
   <script id="52" type="text/markdown">
     **How do I configure Postgres?** The following options are supported:
 

docs/index.html

@@ -181,7 +181,7 @@
     ```json
     {
       "dependencies": {
-        "@observablehq/notebook-kit": "^1.0.1"
+        "@observablehq/notebook-kit": "^%VITE_VERSION%"
       },
       "scripts": {
         "docs:preview": "notebooks preview --root docs",
@@ -201,7 +201,7 @@
     This generates a `.observable/dist` folder containing the built site, which you can then deploy to your preferred static site hosting service, such as GitHub Pages, Vercel, or Netlify.
   </script>
   <script id="46" type="text/markdown">
-    When building notebooks, we use static generation for Markdown and HTML cells: static content is statically rendered. This improves the user experience by accelerating the first contentful paint, and by reducing reflow during page load --- your page appears instantly. It's good for SEO, too, because static content is now readable by search engines without JavaScript.
+    When building notebooks, we use static generation for Markdown and HTML cells: static content is statically rendered. We "bake" the results of static [database queries](./databases), too. Static generation improves the user experience by accelerating the first contentful paint, and by reducing reflow during page load --- your page appears instantly. It's good for SEO, too, because static content is now readable by search engines without JavaScript.
   </script>
   <script id="19" type="text/markdown">
     <aside>You can also use the new Vite plugin directly if you want to integrate notebooks into your existing Vite-based application.</aside>

docs/kit.html

@@ -10,7 +10,7 @@
     **Observable Notebook Kit** is an [open-source command-line tool](https://github.com/observablehq/notebook-kit) for building static sites from Observable Notebooks based on an open file format. Notebook Kit also includes a Vite plugin and a low-level JavaScript interface for deep integration of Observable Notebooks with custom web applications.
   </script>
   <script id="43" type="text/markdown">
-    Notebook Kit is available as part of [**Notebooks 2.0 Technology Preview**](./), which includes **Observable Desktop**, a macOS application for editing notebooks.
+    Notebook Kit is available as part of [**Notebooks 2.0 Technology Preview**](./), which includes [Observable Desktop](./desktop), a macOS application for editing notebooks.
   </script>
   <script id="46" type="text/markdown">
     For more on authoring notebooks, see the [Notebooks system guide](./system-guide).
@@ -32,7 +32,25 @@
     pnpm add @observablehq/notebook-kit @fontsource/inter @fontsource/source-serif-4 @fontsource/spline-sans-mono
     ```
 
-    Notebook Kit requires [Node.js](https://nodejs.org/en) 20.19+ or 22.12+.
+    If you plan on using [database connectors](./databases), you must also install the drivers for the databases you wish to use. To install the DuckDB driver:
+
+    ```sh
+    npm add @duckdb/node-api
+    ```
+
+    To install the Postgres driver:
+
+    ```sh
+    npm add postgres
+    ```
+
+    To install the Snowflake driver:
+
+    ```sh
+    npm add snowflake-sdk
+    ```
+
+    Notebook Kit requires [Node.js](https://nodejs.org/en) 20.19+ or 22.12+. To use the SQLite database connector, you must use Node.js 24+. [Bun](https://bun.com/) 1.2+ should also work, but is not officially supported.
   </script>
   <script id="47" type="text/markdown">
     ---
@@ -123,7 +141,7 @@ <h1>Hello, <i>world</i>!</h1>
     A SQL (`application/sql`) cell:
 
     ```html
-    <script type="application/sql" database="reporting">
+    <script type="application/sql" database="reporting" output="customers">
       SELECT * FROM customers
     <\/script>
     ```
@@ -227,15 +245,15 @@ <h1>Hello, <i>world</i>!</h1>
 
     ## Command-line interface
 
-    Notebook Kit's CLI supports three commands: `preview` for a live preview of notebooks, `build` for building a static site, and `download` for downloading Observable Notebooks as HTML.
+    Notebook Kit's CLI supports four commands: `preview` for a live preview of notebooks, `build` for building a static site, `download` for downloading Observable Notebooks as HTML, and `query` for saving the results of database queries.
   </script>
   <script id="71" type="text/markdown">
     We recommend that you install Notebook Kit locally to a project using a package manager such as npm, and then add preview and build scripts to your `package.json`.
 
     ```json
     {
       "dependencies": {
-        "@observablehq/notebook-kit": "^1.0.1"
+        "@observablehq/notebook-kit": "^%VITE_VERSION%"
       },
       "scripts": {
         "docs:preview": "notebooks preview --root docs",
@@ -283,6 +301,15 @@ <h1>Hello, <i>world</i>!</h1>
     notebooks download https://observablehq.com/@d3/bar-chart > docs/bar-chart.html
     ```
   </script>
+  <script id="76" type="text/markdown">
+    ### Query
+
+    Run the `query` command to save the result of a [database query](./databases). (This is typically done automatically, but can be used to prepare or refresh queries manually.) Pass positional arguments to interpolate JSON-encoded values into the query.
+
+    ```sh
+    notebooks query --database duckdb 'SELECT 1 + ' '2'
+    ```
+  </script>
   <script id="6" type="text/markdown">
     ---
 
@@ -296,14 +323,14 @@ <h1>Hello, <i>world</i>!</h1>
     The Vite plugin is recommended for Vite-based applications.
   </script>
   <script id="42" type="text/markdown">
-    #### <code class="language-ts">observable({template?: string}): PluginOption</code>
+    #### <code class="language-ts">observable({template?: string, transformTemplate?: (template: string) => string | Promise&lt;string&gt;, transformNotebook?: (notebook: Notebook) => Notebook | Promise&lt;Notebook&gt;}, window?: Window, parser?: DOMParser): PluginOption</code>
 
     Returns a Vite plugin for rendering notebook HTML as vanilla HTML. Markdown and HTML cells are rendered statically (without any interpolated dynamic values), and then, if needed, replaced with dynamic content when the page loads. Other cell modes are exclusively dynamic. Pinned cells display their source code statically rendered below any output. Supported languages are syntax-highlighted using Lezer.
   </script>
   <script id="41" type="text/markdown">
     #### <code class="language-ts">config(): UserConfig</code>
 
-    Returns the base Vite config needed to use the `observable()` Vite plugin; this enables top-level await and adds resolvers for `npm:`, `jsr:`, and `observable:` import protocols.
+    Returns the base Vite config needed to use the `observable()` Vite plugin; this enables top-level await, multi-page application behavior, and adds resolvers for `npm:`, `jsr:`, and `observable:` import protocols.
   </script>
   <script id="17" type="text/markdown">
     ### Build API
@@ -326,19 +353,19 @@ <h1>Hello, <i>world</i>!</h1>
     Parses the specified template cell source code (such as the contents of a Markdown or SQL cell), returning the resulting AST as a `TemplateLiteral`. (This method is called internally by `transpile`.)
   </script>
   <script id="22" type="text/markdown">
-    #### <code class="language-ts">transpile(input: string, mode: Cell[\"mode\"], options?: TranspileOptions): TranspiledJavaScript</code>
+    #### <code class="language-ts">transpile(input: Cell, options?: TranspileOptions): TranspiledJavaScript</code>
 
-    Transpiles the specified cell source code, given the cell's `mode`. The transpiled source is returned as a `body` function suitable for use with [`variable.define`](https://github.com/observablehq/runtime/blob/main/README.md#variabledefinename-inputs-definition) from the Observable Runtime, along with any named `inputs` (unbound references) and `outputs` (top-level declarations).
+    Transpiles the specified cell. The transpiled source is returned as a `body` function suitable for use with [`variable.define`](https://github.com/observablehq/runtime/blob/main/README.md#variabledefinename-inputs-definition) from the Observable Runtime, along with any named `inputs` (unbound references) and `outputs` (top-level declarations).
   </script>
   <script id="23" type="text/markdown">
     #### <code class="language-ts">transpileJavaScript(input: string, options?: TranspileOptions): TranspiledJavaScript</code>
 
     Transpiles the specified JavaScript cell source code. The transpiled source is returned as a `body` function suitable for use with [`variable.define`](https://github.com/observablehq/runtime/blob/main/README.md#variabledefinename-inputs-definition) from the Observable Runtime, along with any named `inputs` (unbound references) and `outputs` (top-level declarations).
   </script>
   <script id="21" type="text/markdown">
-    #### <code class="language-ts">transpileTemplate(input: string, tag = \"\", raw = false): string</code>
+    #### <code class="language-ts">transpileTemplate(input: Cell): string</code>
 
-    Transpiles the specified template cell source code (such as the contents of a Markdown or SQL cell), returning the corresponding JavaScript source code consisting of a single template literal expression; the given `tag` is the source code of the template literal tag, if any (such as `md` for Markdown), and the given `raw` flag indicates whether the template literal is raw. (This method is called internally by `transpile`, and the result is passed to `transpileJavaScript`.)
+    Transpiles the specified template cell, such as a Markdown or SQL cell, returning the corresponding JavaScript source code consisting of a single template literal expression. (This method is called internally by `transpile`, and the result is passed to `transpileJavaScript`.)
   </script>
   <script id="45" type="text/markdown">
     ### Utility API
@@ -360,11 +387,26 @@ <h1>Hello, <i>world</i>!</h1>
 
     Returns the default `pinned` value for the given cell `mode`.
   </script>
+  <script id="84" type="text/markdown">
+    #### <code class="language-ts">serialize(notebook: Notebook, {document?: Document} = {}): string</code>
+
+    Serializes the specified notebook to HTML.
+  </script>
+  <script id="85" type="text/markdown">
+    #### <code class="language-ts">deserialize(html: string, {parser?: DOMParser} = {}): Notebook</code>
+
+    Deserializes the specified HTML to a notebook.
+  </script>
   <script id="15" type="text/markdown">
     ### Runtime API
 
     The Runtime API provides some additional logic on top of the [Observable Runtime](https://github.com/observablehq/runtime) to run the notebook, allowing cells to be redefined at runtime, and implementing the notebook standard library, including the `display` and `view` functions which are scoped per-cell.
   </script>
+  <script id="77" type="text/markdown">
+    #### <code class="language-ts">constructor NotebookRuntime(builtins?: Record<string, unknown>)</code>
+
+    Instantiates a new notebook runtime, given the specified built-ins, which defaults to (the standard) `library`. The returned instance exposes a `runtime`, `main`, and `define` methods which are equivalent to those below, but scoped to this specific instance. This constructor allows multiple notebooks to be instantiated concurrently.
+  </script>
   <script id="28" type="text/markdown">
     #### <code class="language-ts">define(state: DefineState, definition: Definition, observe?: () => Observer): void</code>
 
@@ -420,4 +462,24 @@ <h1>Hello, <i>world</i>!</h1>
 
     The built-ins provided to the runtime; the notebook standard library. This object includes the definitions for various built-ins, such as `now`, `width`, `Generators`, and `Mutable`.
   </script>
+  <script id="78" type="text/markdown">
+    ### Database API
+
+    The Database API provides a low-level API for running [database queries](./databases).
+  </script>
+  <script id="81" type="text/markdown">
+    #### <code class="language-ts"> getDatabaseConfig(sourcePath: string, databaseName: string): Promise&lt;DatabaseConfig&gt;</code>
+
+    Loads the database config given a path to a notebook source file and the name of a database.
+  </script>
+  <script id="82" type="text/markdown">
+    #### <code class="language-ts"> getDatabase(config: DatabaseConfig): Promise&lt;QueryTemplateFunction&gt;</code>
+
+    Returns the query template function (equivalent to the `sql` tagged template literal) for running a query against the given database.
+  </script>
+  <script id="83" type="text/markdown">
+    #### <code class="language-ts">getQueryCachePath(sourcePath: string, databaseName: string, strings: readonly string[], ...params: unknown[]): Promise&lt;string&gt;</code>
+
+    Returns the path to the query results cache file, given a path to a notebook source file, the name of a database, and query template parts.
+  </script>
 </notebook>

docs/observable.tmpl

@@ -117,10 +117,10 @@
               <div>Desktop user guide</div>
               <div style="opacity: 0.8; font-weight: normal; font-size: 14px;">A visual guide to editing notebooks with Observable Desktop</div>
             </a>
-            <!-- a href="/notebook-kit/databases" style="color: inherit;">
+            <a href="/notebook-kit/databases" style="color: inherit;">
               <div>Database connectors</div>
               <div style="opacity: 0.8; font-weight: normal; font-size: 14px;">Query SQL databases and data warehouses from notebooks</div>
-            </a -->
+            </a>
           </div>
         </div>
       </div>

package.json

@@ -5,7 +5,7 @@
     "type": "git",
     "url": "git+https://github.com/observablehq/notebook-kit.git"
   },
-  "version": "1.1.0-rc.17",
+  "version": "1.1.0",
   "type": "module",
   "scripts": {
     "test": "vitest",

src/databases/index.ts

@@ -5,8 +5,6 @@ import {isEnoent} from "../lib/error.js";
 import {hash as getQueryHash, nameHash as getNameHash} from "../lib/hash.js";
 import type {ColumnSchema, QueryParam} from "../runtime/index.js";
 
-export {hash as getQueryHash, nameHash as getNameHash} from "../lib/hash.js";
-
 export type DatabaseConfig = DuckDBConfig | SQLiteConfig | SnowflakeConfig | PostgresConfig;
 
 export type DuckDBConfig = {