# MSSQL — Microsoft SQL Server

> Konnektor für Microsoft SQL Server. Lesen wird unterstützt — Schreiben nicht.

---

Site [llms.txt](/llms.txt)

---

> **Preview**
>
> Der MSSQL-Konnektor ist als **Vorabversion** eingestuft. Lesen ist funktionsfähig,
> Schreiben wird nicht unterstützt. Vor einem produktiven Einsatz bitte WYSA kontaktieren.



Der MSSQL-Konnektor ermöglicht das Lesen von Daten aus **Microsoft SQL Server**-Datenbanken
(OnPremise und Azure SQL) und deren Übertragung in andere Systeme.

| Eigenschaft | Wert |
|---|---|
| Lesen | ⚠️ Preview |
| Schreiben | — nicht unterstützt |
| Job-Filter | ✅ wird als `WHERE`-Klausel übernommen |
| Status | Preview |

Wie die übrigen drei SQL-Konnektoren wertet MSSQL den Filter des Jobs aus und erzeugt
gültiges Paging für sein Datenbanksystem.

> **Schreiben wird nicht unterstützt**
>
> Ein MSSQL-System als `TargetConnection` führt zur Laufzeit zu einem Abbruch. Der
> Konnektor ist ausschließlich als Quellsystem einsetzbar. Auch das Löschen von Datensätzen
> ist nicht implementiert.



---

## Verbindungsparameter

```json
{
  "connectionstring": "<ADO.NET Connection String>"
}
```

Beispiel (SQL Server Authentication):

```
Server=<server>;Database=<db>;User Id=<user>;Password=<password>;TrustServerCertificate=True;
```

Beispiel (Windows Authentication / Integrated Security):

```
Server=<server>;Database=<db>;Integrated Security=True;TrustServerCertificate=True;
```

### Optionale Parameter

| Parameter | Standardwert | Beschreibung |
|---|---|---|
| `commandTimeOut` | `30` | Zeitlimit für einzelne SQL-Befehle in Sekunden. Bei großen Tabellen oder langsamen Abfragen zu erhöhen. |
| `maxPageSize` | `5000` | Anzahl Datensätze je Seite. Steuert `TOP` bzw. `OFFSET`/`FETCH NEXT` der erzeugten Abfrage. |
| `language` | `de-DE` | Kultur, in der gelesene Zahlen- und Datumswerte formatiert werden |
| `keyVaultUrl` | *(leer)* | Key-Vault-Secret-URL; ersetzt sämtliche übrigen Parameter |

---

## Tabellen- und Feldnamen

| Einstellung | Wert |
|---|---|
| SourceTable | Tabellenname, ggf. mit Schema-Präfix (z. B. `Customers`, `dbo.Orders`) |
| SourceField | Spaltenname. Wird automatisch in eckige Klammern gesetzt (ab v2.3; bis v2.2 nur bei Namen mit Leerzeichen). |

Der Wert aus `SourceTable` wird unverändert hinter `FROM` eingesetzt.

> **Spaltennamen ohne Klammern angeben**
>
> `SourceField` und `WatermarkField` müssen exakt dem Spaltennamen in der Tabelle entsprechen,
> **ohne** eckige Klammern, Tabellen-Alias, Schema-Präfix oder Ausdruck. Die DataBridge setzt
> die Klammern selbst. Der Wert wird anschließend über diesen Namen aus dem Ergebnis gelesen;
> `[Spalte]`, `t.Spalte` oder `UPPER(Spalte)` werden dort nicht gefunden und führen zum Abbruch.



---

## Änderungserkennung (Watermark)

Die Erkennung basiert auf einer Zeitstempel-Spalte in der SQL-Tabelle. Diese Spalte muss
beim Einfügen oder Ändern eines Datensatzes automatisch aktualisiert werden.

| Eigenschaft | Wert |
|---|---|
| WatermarkType | `date` oder `datetime` |
| WatermarkField | Name der Zeitstempel-Spalte (z. B. `ModifiedAt`, `UpdatedDate`); wird wie `SourceField` in eckige Klammern gesetzt |

Die Spalte aus `WatermarkField` wird zusätzlich zu den gemappten Feldern abgefragt und für
die Sortierung (`ORDER BY … ASC`) verwendet.

> **Empfehlung: echtes Datum als Watermark-Spalte**
>
> Spalten vom Typ `datetime`, `datetime2`, `smalldatetime` oder `date` sind vorgesehen und
> werden als ISO-Zeitstempel weitergereicht. Eine Spalte anderen Typs — etwa `rowversion`,
> `timestamp` oder `bigint` — führt nicht mehr zu einem Abbruch, wird aber unverändert über
> `ToString()` weitergegeben; die Sortierung (`ORDER BY … ASC`) erfolgt weiterhin nach dem
> Spaltentyp der Datenbank, nicht nach dem Textwert.



---

## Filter — die WHERE-Klausel kommt aus dem Job

> **Die WHERE-Klausel wird nicht erzeugt, sondern übernommen**
>
> Die DataBridge baut **keine** Bedingung aus `WatermarkField` und Watermark zusammen. Der
> Inhalt des Feldes `Filter` am Job wird — nach Ersetzung des Platzhalters `%watermark%` —
> wörtlich hinter `WHERE` eingesetzt.
> 
> Daraus folgt:
> 
> - **Ohne Eintrag im Feld `Filter` entsteht keine `WHERE`-Klausel.** Der Job liest bei
>   jedem Lauf die vollständige Tabelle.
> - Der Ausdruck muss **gültiges T-SQL** sein. Ein Syntaxfehler im Filter führt zu einer
>   fehlgeschlagenen Abfrage.
> - Es findet **keine Parametrisierung** statt. Der Filtertext wird als Zeichenkette in die
>   Abfrage eingesetzt; der Zugriff auf die `jobs`-Tabelle ist entsprechend zu beschränken.



Ein typischer Filter für eine MSSQL-Quelle:

```
{{ModifiedAt > '%watermark%'}}
```

Die Klammerung `{{ … }}` sorgt dafür, dass der Block bei leerer Watermark vollständig
entfällt — der Erstlauf liest dann den gesamten Bestand. Die vollständigen Regeln stehen
unter [Jobs → Filter-Syntax](../../konfiguration/jobs/).

---

## Datentypen — gelesene Werte

Da Schreiben nicht unterstützt wird, ist beim MSSQL-Konnektor allein der Lesepfad
relevant. Der Typ ergibt sich aus dem ADO.NET-Spaltentyp; der so ermittelte Typname wird
zusammen mit dem formatierten Wert an den Zielkonnektor weitergereicht und dort für die
Auswahl der Umwandlung verwendet.

| ADO.NET-Spaltentyp | Weitergegebener Typ | Formatierung des Wertes |
|---|---|---|
| `Int32` | `int32` | Wird als Ganzzahl gelesen und in der Kultur aus `language` ausgegeben |
| `Decimal` | `decimal` | Wird als Dezimalzahl gelesen und in der Kultur aus `language` ausgegeben |
| `Double` | `double` | Wie `Decimal` — Umwandlung über einen Dezimalwert |
| `DateTime` | `datetime` | Format `u`, also `yyyy-MM-dd HH:mm:ssZ` |
| alle übrigen | Name des .NET-Typs (z. B. `string`, `boolean`, `guid`) | Unveränderte Textdarstellung |

> **`language` wirkt auf Zahlenwerte**
>
> Zahlen werden in der Kultur der **Quellverbindung** formatiert. Steht dort der Vorgabewert
> `de-DE`, wird ein Komma als Dezimaltrennzeichen ausgegeben. Zielkonnektoren, die einen
> Textwert zwingend als `en-US` lesen — etwa die String-zu-Decimal-Umwandlung ab v2.1 —
> interpretieren das falsch. In gemischten Szenarien ist `language` an der Quellverbindung
> entsprechend zu setzen.



Welche Quelltypen ein Zielsystem akzeptiert, steht auf der jeweiligen Zielkonnektor-Seite:
[D365BC](../d365bc/), [D365CE](../d365ce/), [D365NAV](../d365nav/).