From f36f75e4147b0f2523564f83119518b698e5e7e7 Mon Sep 17 00:00:00 2001 From: TimelordUK Date: Sun, 11 Oct 2026 14:20:16 +0100 Subject: [PATCH] docs: point new users at the msnodesqlv8-api-tour app Adds the API tour (one runnable file covering the whole driver API) as the headline sample: a 'start here' section on every release page and the first row of its sample apps table, plus a pointer in the README quick start and the standalone example apps table. Co-Authored-By: Claude Opus 5.5 (1M context) --- .github/RELEASE_TEMPLATE.md | 17 +++++++++++++++++ README.md | 3 +++ 2 files changed, 20 insertions(+) diff --git a/.github/RELEASE_TEMPLATE.md b/.github/RELEASE_TEMPLATE.md index 87aa7e77..ec783599 100644 --- a/.github/RELEASE_TEMPLATE.md +++ b/.github/RELEASE_TEMPLATE.md @@ -42,6 +42,22 @@ npm install msnodesqlv8 --- +## New to msnodesqlv8? Start with the API tour + +[**msnodesqlv8-api-tour**](https://github.com/TimelordUK/msnodesqlv8-api-tour) +is one file that walks through the whole API, one copyable section per area: +connections and parameters, streaming with pause / resume, multiple result +sets, prepared statements, stored procedures with output params, transactions, +the table manager's bulk insert / update / delete, BCP, TVPs, geography, +print and error handling, cancel and timeouts, and the connection pool. It +cleans up after itself, so it is safe to re-run and hack on. + +```sh +git clone https://github.com/TimelordUK/msnodesqlv8-api-tour && cd msnodesqlv8-api-tour +npm install +CONNECTION_STRING="Driver={ODBC Driver 18 for SQL Server};Server=localhost,1433;Database=tempdb;UID=sa;PWD=...;TrustServerCertificate=yes;" node api-tour.js +``` + ## Prebuilt binaries ship inside the npm package Since **5.5.0** the per-platform N-API binary is bundled in the published @@ -106,6 +122,7 @@ ways to place one, in increasing order of scope: | description | link | |---|---| +| **start here**: the whole API in one runnable file | [msnodesqlv8-api-tour](https://github.com/TimelordUK/msnodesqlv8-api-tour) | | next js example, note cant run driver on UI thread. | [todo-with-nextjs_msnodesqlv8](https://github.com/TimelordUK/todo-with-nextjs_msnodesqlv8) | | next js example using app router, note cant run driver on UI thread. | [todo-with-nextjs-app-router_msnodesqlv8](https://github.com/TimelordUK/todo-with-nextjs-app-router_msnodesqlv8) | | using vite + express | [msnodesqlv8-vite](https://github.com/TimelordUK/msnodesqlv8-vite) | diff --git a/README.md b/README.md index 51498b23..71e82240 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,8 @@ await table.promises.insert(rows) // array-bind, ~130k rows/s // table.setUseBcp(true) // opt-in to native BCP protocol ``` +**New here? Start with the [API tour](https://github.com/TimelordUK/msnodesqlv8-api-tour)**: one runnable file covering the whole API (pool, procs, bulk / BCP, TVP, geography, cancel, print and error handling) that cleans up after itself. + See [samples/javascript/](samples/javascript/) for runnable versions of every snippet below. --- @@ -106,6 +108,7 @@ Full runnable projects in their own repos, showing `msnodesqlv8` wired into real | Stack | Repo | | ----------------------------- | ---- | +| **Start here: the whole API in one file** | [msnodesqlv8-api-tour](https://github.com/TimelordUK/msnodesqlv8-api-tour) | | Next.js (pages router) | [todo-with-nextjs_msnodesqlv8](https://github.com/TimelordUK/todo-with-nextjs_msnodesqlv8) | | Next.js (app router) | [todo-with-nextjs-app-router_msnodesqlv8](https://github.com/TimelordUK/todo-with-nextjs-app-router_msnodesqlv8) | | Vite + Express | [msnodesqlv8-vite](https://github.com/TimelordUK/msnodesqlv8-vite) |