[mssql] Document MsSql persister

Author: nltgpeterskoglund

site/guides/07_persistence/1_an_intro_to_persistence.md

@@ -55,6 +55,7 @@ is available.
 | ElectricSqlPersister       | Electric SQL, via [electric](https://github.com/electric-sql/electric)                                           |
 | LibSqlPersister            | LibSQL for Turso, via [libsql-client](https://github.com/tursodatabase/libsql-client-ts)                         |
 | PowerSyncPersister         | PowerSync, via [powersync-sdk](https://github.com/powersync-ja/powersync-js)                                     |
+| MsSqlPersister             | SQL Server and Azure SQL, via [mssql](https://github.com/tediousjs/node-mssql)                                   |
 | PgPersister                | PostgreSQL, via [pg](https://github.com/brianc/node-postgres)                                                    |
 | PostgresPersister          | PostgreSQL, via [postgres](https://github.com/porsager/postgres)                                                 |
 | PglitePersister            | PostgreSQL, via [PGlite](https://github.com/electric-sql/pglite)                                                 |

site/guides/07_persistence/2_database_persistence.md

@@ -3,8 +3,8 @@
 Since v4.0, there are various options for persisting Store data to and from
 SQLite databases, via a range of third-party modules.
 
-There are currently twelve SQLite-based persistence options, and four for
-PostgreSQL:
+There are currently twelve SQLite-based persistence options, four for
+PostgreSQL, and one for SQL Server:
 
 | Persister                  | Storage                                                                                                          |
 | -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
@@ -20,6 +20,7 @@ PostgreSQL:
 | ElectricSqlPersister       | Electric SQL, via [electric](https://github.com/electric-sql/electric)                                           |
 | LibSqlPersister            | LibSQL for Turso, via [libsql-client](https://github.com/tursodatabase/libsql-client-ts)                         |
 | PowerSyncPersister         | PowerSync, via [powersync-sdk](https://github.com/powersync-ja/powersync-js)                                     |
+| MsSqlPersister             | SQL Server and Azure SQL, via [mssql](https://github.com/tediousjs/node-mssql)                                   |
 | PgPersister                | PostgreSQL, via [pg](https://github.com/brianc/node-postgres)                                                    |
 | PostgresPersister          | PostgreSQL, via [postgres](https://github.com/porsager/postgres)                                                 |
 | PglitePersister            | PostgreSQL, via [PGlite](https://github.com/electric-sql/pglite)                                                 |
@@ -39,6 +40,21 @@ and `Client` objects can be passed straight to the createPgPersister function,
 which means you can persist a Store to PostgreSQL from an edge runtime that
 cannot open a regular TCP connection.
 
+The MsSqlPersister covers the SQL Server family, and since Azure SQL Database
+and Azure SQL Managed Instance both speak the same protocol, the same
+createMsSqlPersister function works against all three. It takes a `mssql`
+connection pool that you have configured yourself, so the passwordless
+authentication that Microsoft recommends for applications hosted in Azure is a
+matter of how you build that pool rather than anything TinyBase needs to know
+about. Only the JSON mode described below is available to it so far.
+
+It also differs in how it notices changes made by other writers. The PostgreSQL
+Persisters use LISTEN and NOTIFY, which has no equivalent that works across
+every flavor of SQL Server, so the MsSqlPersister adds a `rowversion` column to
+its table and polls that instead. SQL Server maintains that column itself on
+every insert and update, which keeps external changes detectable without
+requiring Service Broker, Change Tracking, or triggers.
+
 The SupabasePersister is the odd one out, since it talks to Supabase's REST API
 rather than to the database directly. That means it runs in a browser or edge
 runtime, that row-level security policies apply to what it reads and writes,

site/guides/08_synchronization/1_using_a_mergeablestore.md

@@ -126,6 +126,7 @@ MergeableStore, but _only_ in the 'JSON-serialization' mode:
 | ExpoSqlitePersister        | SQLite in React Native, via [expo-sqlite](https://github.com/expo/expo/tree/main/packages/expo-sqlite)           |
 | ReactNativeSqlitePersister | SQLite in React Native, via [react-native-sqlite-storage](https://github.com/andpor/react-native-sqlite-storage) |
 | CapacitorSqlitePersister   | SQLite in Capacitor, via [capacitor-sqlite](https://github.com/capacitor-community/sqlite)                       |
+| MsSqlPersister             | SQL Server and Azure SQL, via [mssql](https://github.com/tediousjs/node-mssql)                                   |
 | PgPersister                | PostgreSQL, via [pg](https://github.com/brianc/node-postgres)                                                    |
 | PostgresPersister          | PostgreSQL, via [postgres](https://github.com/porsager/postgres)                                                 |
 | PglitePersister            | PostgreSQL, via [PGlite](https://github.com/electric-sql/pglite)                                                 |

site/guides/20_releases.md

@@ -5,6 +5,58 @@ highlighted features.
 
 ---
 
+# v9.8
+
+## SQL Server and Azure SQL, via `mssql`
+
+The new persister-mssql module provides the MsSqlPersister, which binds to a
+SQL Server database with the
+[`mssql`](https://github.com/tediousjs/node-mssql) module. Since Azure SQL
+Database and Azure SQL Managed Instance speak the same protocol, the same
+Persister works against all three:
+
+```js
+import {connect} from 'mssql';
+import {createStore} from 'tinybase';
+import {createMsSqlPersister} from 'tinybase/persisters/persister-mssql';
+
+const msSqlPool = await connect(process.env.TINYBASE_MSSQL);
+const msSqlStore = createStore().setTables({pets: {fido: {species: 'dog'}}});
+const msSqlPersister = await createMsSqlPersister(
+  msSqlStore,
+  msSqlPool,
+  'my_tinybase',
+);
+
+await msSqlPersister.save();
+console.log(
+  (await msSqlPool.request().query('SELECT * FROM my_tinybase;')).recordset,
+);
+// -> [{_id: '_', store: '[{"pets":{"fido":{"species":"dog"}}},{}]'}]
+
+await msSqlPersister.destroy();
+await msSqlPool.request().query('DROP TABLE IF EXISTS my_tinybase;');
+await msSqlPool.close();
+```
+
+The Persister takes a connection pool that you have already configured, so it
+stays out of the way of how you authenticate. That matters most on Azure, where
+Microsoft recommends passwordless access for hosted applications: build the
+pool with an `azure-active-directory-default` authentication type and the
+Persister needs to know nothing about it.
+
+This release supports the JSON serialization mode, for both a Store and a
+MergeableStore. Tabular mapping may follow.
+
+Automatic loading works differently here than it does for PostgreSQL. There is
+no equivalent of LISTEN and NOTIFY that is available on every flavor of SQL
+Server, so the Persister adds a `rowversion` column to its table and polls it.
+SQL Server maintains that column itself on every insert and update, so changes
+made by other writers are still picked up, without needing Service Broker,
+Change Tracking, or triggers.
+
+---
+
 # v9.7
 
 ## SQLite, via `node:sqlite`