Skip to content

Commit db94084

Browse files
danielgerlagCopilot
danielgerlag
and
Copilot
authored
Add SQL Server (MSSQL) source and bootstrap documentation (#213)
* Add SQL Server (MSSQL) source and bootstrap documentation Add documentation for the SQL Server source and bootstrap provider: - drasi-lib: Add SQL Server card to sources reference page - drasi-server: Add Configure SQL Server Source how-to guide - drasi-server: Add Configure SQL Server Bootstrap Provider how-to guide - Update source and bootstrap index pages with SQL Server cards Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix spellcheck: add TDS, LSN, authMode to dictionary Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 398d9ba commit db94084

6 files changed

Lines changed: 422 additions & 0 deletions

File tree

‎.github/config/en-drasi.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ ApplySource
1212
ApplySources
1313
AttachQuery
1414
autocomplete
15+
authMode
1516
autocompletion
1617
backticks
1718
Balancers
@@ -122,6 +123,7 @@ listMax
122123
listMin
123124
LiveDashboard
124125
localhost
126+
LSN
125127
macOS
126128
maxInterval
127129
mcp
@@ -222,6 +224,7 @@ Streamable
222224
supportability
223225
SyncDaprStateStore
224226
tableKeys
227+
TDS
225228
tenantId
226229
trueFor
227230
trueLater

‎docs/content/drasi-lib/reference/sources.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,15 @@ Sources ingest data from external systems or your application and emit graph ele
7878
</div>
7979
</div>
8080
</a>
81+
<a href="https://crates.io/crates/drasi-source-mssql" target="_blank" rel="noopener">
82+
<div class="unified-card unified-card--reference">
83+
<div class="unified-card-icon"><i class="fas fa-database"></i></div>
84+
<div class="unified-card-content">
85+
<h3 class="unified-card-title">SQL Server</h3>
86+
<p class="unified-card-summary">Stream changes from SQL Server using Change Data Capture (CDC)</p>
87+
</div>
88+
</div>
89+
</a>
8190
</div>
8291

8392
## Building Custom Sources

‎docs/content/drasi-server/how-to-guides/configuration/configure-bootstrap-providers/_index.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,15 @@ description: "Load initial data before streaming begins"
4141
</div>
4242
</div>
4343
</a>
44+
<a href="configure-mssql-bootstrap-provider/">
45+
<div class="unified-card unified-card--howto">
46+
<div class="unified-card-icon"><i class="fas fa-database"></i></div>
47+
<div class="unified-card-content">
48+
<h3 class="unified-card-title">SQL Server</h3>
49+
<p class="unified-card-summary">Bootstrap from a SQL Server snapshot (SQL Server sources only)</p>
50+
</div>
51+
</div>
52+
</a>
4453
<a href="configure-scriptfile-bootstrap-provider/">
4554
<div class="unified-card unified-card--howto">
4655
<div class="unified-card-icon"><i class="fas fa-file-alt"></i></div>

‎docs/content/drasi-server/how-to-guides/configuration/configure-bootstrap-providers/configure-mssql-bootstrap-provider/_index.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
type: "docs"
3+
title: "Configure SQL Server Bootstrap Provider"
4+
linkTitle: "SQL Server"
5+
weight: 50
6+
description: "Bootstrap queries from a SQL Server snapshot"
7+
related:
8+
howto:
9+
- title: "Configure Sources"
10+
url: "/drasi-server/how-to-guides/configuration/configure-sources/"
11+
- title: "Configure SQL Server Source"
12+
url: "/drasi-server/how-to-guides/configuration/configure-sources/configure-mssql-source/"
13+
- title: "Configure Bootstrap Providers"
14+
url: "/drasi-server/how-to-guides/configuration/configure-bootstrap-providers/"
15+
---
16+
17+
The **SQL Server bootstrap provider** loads initial state from a Microsoft SQL Server database so queries start with a complete snapshot before streaming begins.
18+
19+
## When to use SQL Server bootstrap
20+
21+
- You need historical/current state from SQL Server when a query starts.
22+
- Your query depends on existing rows (aggregations, joins, thresholds).
23+
- You want snapshot + CDC streaming from the same database.
24+
25+
## Prerequisites
26+
27+
- Use with a **SQL Server source** (`sources[].kind: mssql`).
28+
- The configured user must have SELECT permission on the monitored tables.
29+
30+
## Quick example (Drasi Server config)
31+
32+
In Drasi Server config, bootstrap provider keys are **camelCase**, and the discriminator field is `bootstrapProvider.kind`.
33+
34+
```yaml
35+
sources:
36+
- kind: mssql
37+
id: orders-db
38+
autoStart: true
39+
40+
host: ${MSSQL_HOST:-localhost}
41+
port: ${MSSQL_PORT:-1433}
42+
database: ${MSSQL_DATABASE:-MyDatabase}
43+
user: ${MSSQL_USER:-drasi_user}
44+
password: ${MSSQL_PASSWORD}
45+
46+
tables:
47+
- orders
48+
- customers
49+
50+
bootstrapProvider:
51+
kind: mssql
52+
```
53+
54+
When `bootstrapProvider.kind` is `mssql` with no additional fields, the bootstrap provider inherits the connection details from the parent source configuration.
55+
56+
You can also override the connection details if the bootstrap should connect to a different server or use different credentials:
57+
58+
```yaml
59+
bootstrapProvider:
60+
kind: mssql
61+
host: ${BOOTSTRAP_HOST:-localhost}
62+
port: 1433
63+
database: ${BOOTSTRAP_DB:-MyDatabase}
64+
user: ${BOOTSTRAP_USER:-drasi_reader}
65+
password: ${BOOTSTRAP_PASSWORD}
66+
authMode: sqlserver
67+
encryption: notsupported
68+
trustServerCertificate: false
69+
tables:
70+
- orders
71+
- customers
72+
tableKeys:
73+
- table: order_items
74+
keyColumns: [order_id, product_id]
75+
```
76+
77+
## Configuration reference
78+
79+
| Field | Type | Default | Description |
80+
|---|---:|---:|---|
81+
| `kind` | string | required | Must be `mssql`. |
82+
| `host` | string | from source | SQL Server hostname. |
83+
| `port` | integer | from source | SQL Server port. |
84+
| `database` | string | from source | Database name. |
85+
| `user` | string | from source | Database user. |
86+
| `password` | string | from source | Password. |
87+
| `authMode` | string | from source | Authentication mode: `sqlserver`, `windows`, or `azuread`. |
88+
| `tables` | string[] | from source | Tables to bootstrap. |
89+
| `encryption` | string | from source | TDS encryption mode: `off`, `on`, or `notsupported`. |
90+
| `trustServerCertificate` | boolean | from source | Whether to trust the server certificate without validation. |
91+
| `tableKeys` | array | from source | Override key columns per table for element ID generation. |
92+
93+
Fields support Drasi Server config references like `${ENV_VAR}` / `${ENV_VAR:-default}`.
94+
95+
## Notes
96+
97+
- Drasi Server only allows `kind: mssql` when the source is also `kind: mssql`.
98+
- When no additional fields are provided, connection details are inherited from the parent source configuration.
99+
- The bootstrap reads current table state via `SELECT` queries—it does not use CDC.
100+
101+
## Documentation resources
102+
103+
<div class="card-grid card-grid--2">
104+
<a href="https://github.com/drasi-project/drasi-core/tree/main/components/bootstrappers/mssql" target="_blank" rel="noopener">
105+
<div class="unified-card unified-card--tutorials">
106+
<div class="unified-card-icon"><i class="fab fa-github"></i></div>
107+
<div class="unified-card-content">
108+
<h3 class="unified-card-title">SQL Server Bootstrap Source</h3>
109+
<p class="unified-card-summary">Implementation notes and behavior details</p>
110+
</div>
111+
</div>
112+
</a>
113+
<a href="https://crates.io/crates/drasi-bootstrap-mssql" target="_blank" rel="noopener">
114+
<div class="unified-card unified-card--howto">
115+
<div class="unified-card-icon"><i class="fas fa-box"></i></div>
116+
<div class="unified-card-content">
117+
<h3 class="unified-card-title">drasi-bootstrap-mssql on crates.io</h3>
118+
<p class="unified-card-summary">Package info and release history</p>
119+
</div>
120+
</div>
121+
</a>
122+
</div>

‎docs/content/drasi-server/how-to-guides/configuration/configure-sources/_index.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,4 +57,13 @@ description: "Connect Drasi Server to databases, APIs, and data streams"
5757
</div>
5858
</div>
5959
</a>
60+
<a href="configure-mssql-source/">
61+
<div class="unified-card unified-card--howto">
62+
<div class="unified-card-icon"><i class="fas fa-database"></i></div>
63+
<div class="unified-card-content">
64+
<h3 class="unified-card-title">SQL Server</h3>
65+
<p class="unified-card-summary">Stream changes from SQL Server using Change Data Capture (CDC)</p>
66+
</div>
67+
</div>
68+
</a>
6069
</div>

0 commit comments

Comments
 (0)