SQL Server (alpha) support (#296)

* Add references (with placeholder)

* Scripts from self-host-example

* Additional reading links

* Limitations placeholder

* Simplify

* cleanup

* update diagram

* Don't need to mention Azure SQL explicitly

* Added SQLServer <-> SQLite type mapping

* Small fixes

* Updated database setup instructions for SQL Server

* Tweak mssql database-setup instructions.

* Reworked mssql database setup instructions

* Next channel

* Update feature status

* Additional details and limitations section added for sql server

* service version

* service version

* v1.18.1 instead

* update self-host-architecture-diagram

* add demo app for mssql

* format node-mssql

* Restructured limitations

* Some more tweaks to scripts

* Apply suggestion from @benitav

* Apply suggestion from @benitav

---------

Co-authored-by: Roland Teichert <roland@journeyapps.com>

Author: benitav

README.md

@@ -64,6 +64,7 @@ We use the following icons for supported backend databases and SDKs:
 - Postgres: `icon="elephant"`
 - MongoDB: `icon="leaf"`
 - MySQL: `icon="dolphin"`
+- SQL Server: `icon="server"`
 - Flutter: `icon="flutter"`
 - React Native: `icon="react"`
 - Web: `icon="js"`

architecture/architecture-overview.mdx

@@ -10,33 +10,23 @@ description: "The core components of PowerSync are the service and client SDKs"
 The [PowerSync Service](/architecture/powersync-service) and client SDK operate in unison to keep client-side SQLite databases in sync with a backend database. Learn about their architecture:
 
 <CardGroup cols="2">
-  <Card title="PowerSync Service" icon="server" horizontal href="/architecture/powersync-service">
-    
-  </Card>
-  <Card title="Client Architecture" icon="microchip" horizontal href="/architecture/client-architecture">
-    
-  </Card>
+  <Card title="PowerSync Service" icon="server" horizontal href="/architecture/powersync-service" />
+  <Card title="Client Architecture" icon="microchip" horizontal href="/architecture/client-architecture" />
 </CardGroup>
 
 ### Protocol
 
 Learn about the sync protocol used between PowerSync clients and a [PowerSync Service](/architecture/powersync-service):
 
 <CardGroup cols="2">
-  <Card title="PowerSync Protocol" icon="network-wired" horizontal href="/architecture/powersync-protocol">
-    
-  </Card>
-  <Card title="Consistency" icon="scale-balanced" horizontal href="/architecture/consistency">
-    
-  </Card>
+  <Card title="PowerSync Protocol" icon="network-wired" horizontal href="/architecture/powersync-protocol" />
+  <Card title="Consistency" icon="scale-balanced" horizontal href="/architecture/consistency" />
 </CardGroup>
 
 ### Self-Hosted Architecture
 
 For more details on typical architecture of a production self-hosted deployment, see here:
 
 <CardGroup cols="2">
-  <Card title="Installation" icon="download" horizontal href="/self-hosting/installation">
-    
-  </Card>
+  <Card title="Installation" icon="download" horizontal href="/self-hosting/installation" />
 </CardGroup>

architecture/powersync-protocol.mdx

@@ -67,4 +67,4 @@ Write checkpoints are used to ensure clients have synced their own changes back
 
 Creating a write checkpoint is a separate operation, which is performed by the client after all data has been uploaded. It is important that this happens after the data has been written to the backend source database.
 
-The server then keeps track of the current CDC stream position on the database (LSN in Postgres, resume token in MongoDB, or GTID + Binlog Position in MySQL), and notifies the client when the data has been replicated, as part of checkpoint data in the normal data stream.
+The server then keeps track of the current CDC stream position on the database (LSN in Postgres and SQL Server, resume token in MongoDB and GTID+Binlog Position in MySQL), and notifies the client when the data has been replicated, as part of checkpoint data in the normal data stream.

images/architecture/powersync-docs-diagram-architecture-overview.png

@@ -7,7 +7,7 @@ PowerSync generally assumes that you have some kind of "backend application" as
 
 When you integrate PowerSync into your app project, PowerSync relies on that "backend application" for a few purposes:
 
-1. **Allowing client-side write operations to be uploaded** and [applied](/installation/app-backend-setup/writing-client-changes) to the backend database (Postgres, MongoDB or MySQL). When you write to the client-side SQLite database provided by PowerSync, those writes are also placed into an upload queue. The PowerSync Client SDK manages uploading of those writes to your backend using the `uploadData()` function that you defined in the [Client-Side Setup](/installation/client-side-setup/integrating-with-your-backend) part of the implementation. That `uploadData()` function should call your backend application API to apply the writes to your backend database. The reason why we designed PowerSync this way is to give you full control over things like data validation and authorization of writes, while PowerSync itself requires minimal permissions.
+1. **Allowing client-side write operations to be uploaded** and [applied](/installation/app-backend-setup/writing-client-changes) to the backend database (Postgres, MongoDB, MySQL, or SQL Server). When you write to the client-side SQLite database provided by PowerSync, those writes are also placed into an upload queue. The PowerSync Client SDK manages uploading of those writes to your backend using the `uploadData()` function that you defined in the [Client-Side Setup](/installation/client-side-setup/integrating-with-your-backend) part of the implementation. That `uploadData()` function should call your backend application API to apply the writes to your backend database. The reason why we designed PowerSync this way is to give you full control over things like data validation and authorization of writes, while PowerSync itself requires minimal permissions.
 2. **Authentication integration:** Your backend is responsible for securely generating the [JWTs](/installation/authentication-setup) used by the PowerSync Client SDK to authenticate with the [PowerSync Service](/architecture/powersync-service).
 
 <Frame caption="An overview of how PowerSync interacts with your backend application.">

images/self-hosting/powersync-architecture-diagram-self-host.png

@@ -17,13 +17,13 @@ Since you get to define the client-side `uploadData()` function as you wish, you
 You can also use any API style you want — e.g. REST, GraphQL, gRPC, etc.
 
 <Warning>
-It's important that your API endpoint be blocking/synchronous with underlying writes to the backend database (Postgres, MongoDB or MySQL).
+It's important that your API endpoint be blocking/synchronous with underlying writes to the backend database (Postgres, MongoDB, MySQL, or SQL Server).
 
 In other words, don't place writes into something like a queue for processing later — process them immediately. For more details, see the explainer below.
 </Warning>
 
 <Accordion title="Why must my write endpoint be synchronous?">
-PowerSync uses a server-authoritative architecture with a checkpoint system for conflict resolution and [consistency](/architecture/consistency). The client advances to a new write checkpoint after uploads have been processed, so if the client believes that the server has written changes into your backend database (Postgres, MongoDB or MySQL), but the next checkpoint does not contain your uploaded changes, those changes will be removed from the client. This could manifest as UI glitches for your end-users, where the changes disappear from the device for a few seconds and then re-appear.
+PowerSync uses a server-authoritative architecture with a checkpoint system for conflict resolution and [consistency](/architecture/consistency). The client advances to a new write checkpoint after uploads have been processed, so if the client believes that the server has written changes into your backend database (Postgres, MongoDB, MySQL, or SQL Server), but the next checkpoint does not contain your uploaded changes, those changes will be removed from the client. This could manifest as UI glitches for your end-users, where the changes disappear from the device for a few seconds and then re-appear.
 </Accordion>
 
 ### Write operations recorded on the client

installation/app-backend-setup.mdx

@@ -7,7 +7,7 @@ After you've [instantiated](/installation/client-side-setup/instantiate-powersyn
 
 | Purpose | Description |
 |---------|-------------|
-| **Uploading writes to your backend:** | Writes that are made to the client-side SQLite database are uploaded to your backend application, where you control how they're applied to your backend database (Postgres, MongoDB or MySQL). This is how PowerSync achieves bi-directional syncing of data. |
+| **Uploading writes to your backend:** | Writes that are made to the client-side SQLite database are uploaded to your backend application, where you control how they're applied to your backend database (Postgres, MongoDB, MySQL, or SQL Server). This is how PowerSync achieves bi-directional syncing of data. |
 | **Authentication integration:** | PowerSync uses JWTs for authentication between the Client SDK and PowerSync Service. Your backend application should be able to generate JWTs that the PowerSync Client SDK can retrieve and use for authentication against your [PowerSync Service](/architecture/powersync-service) instance. |
 
 Accordingly, you must pass a _backend connector_ as an argument when you call `connect()` on the client-side PowerSync database. You must define that backend connector, and it must implement two functions/methods:

installation/app-backend-setup/writing-client-changes.mdx

@@ -228,3 +228,30 @@ For other providers and self-hosted databases:
     Make sure that your MySQL database allows access to PowerSync's IPs — see [Security and IP Filtering](/installation/database-setup/security-and-ip-filtering)
 </Info>
 
+## <Icon icon="server" iconType="solid" size={32}/> SQL Server (Alpha) Specifics
+
+<Check>
+   SQL Server support was introduced in version 1.18.1 of the PowerSync Service, which is currently available in the [**Next** channel](resources/feature-status#powersync-cloud).
+</Check>
+
+1. In the [PowerSync Dashboard](https://dashboard.powersync.com/), select your project and instance and go to the **Database Connections** view.
+2. Click **Connect to Source Database** and ensure the **"SQL Server"** tab is selected.
+3. Fill in your SQL Server connection details:
+   1. "**Name**", "**Host**", "**Port**", "**Database name**", "**Username**", "**Password**" are required.
+   2. "**Name**" can be any name for the connection.
+   3. "**Host**" is the endpoint for your SQL Server instance.
+   4. "**Port**" is typically 1433 for SQL Server (default port).
+   5. "**Database name**" is the database where CDC is enabled.
+   6. "**Username**" and "**Password**" maps to the database user created in [Source Database Setup](/installation/database-setup#sql-server-alpha) (e.g., `powersync_user`).
+4. Click **Test Connection** and fix any errors.
+5. Click **Save Connection**.
+
+PowerSync deploys and configures an isolated cloud environment for you, which can take a few minutes to complete.
+
+<Info>
+    Make sure that your SQL Server database allows access to PowerSync's IPs — see [Security and IP Filtering](/installation/database-setup/security-and-ip-filtering)
+</Info>
+
+Also see:
+- [SQL Server Setup](/installation/database-setup#sql-server-alpha)
+