Installation

Mit Docker in einer Minute, oder direkt auf dem Rechner als Dienst, der mit dem System startet: unter Linux mit systemd, unter macOS mit launchd, unter Windows als Windows-Dienst. Jeder Weg führt Schritt für Schritt hin, die Dienstdateien liegen fertig bereit.

Der Server als Einzeldatei, gestartet von launchd beim Systemstart - noch bevor sich jemand anmeldet - und nach einem Absturz neu. Er läuft unter Ihrem Konto; Daten und Protokoll liegen unter /usr/local/var.

Die Einzeldatei

Aus der Auslieferung (osx-arm64 oder osx-x64) - oder aus dem Quellstand gebaut, mit dem .NET 10 SDK und PowerShell 7. Die .NET-Laufzeit ist darin enthalten, auf dem Zielrechner muss nichts installiert sein. Die folgenden Schritte laufen im Ordner mit der Einzeldatei und den Dateien unten.
bash
```
pwsh dist/einzeldatei-bauen.ps1 -Plattform osx-arm64
cd einzeldatei/osx-arm64
```

Programm, Daten und Protokoll

Das Programm gehört root, Daten und Protokoll Ihrem Konto.

bash

sudo install -d -m 755 /usr/local/kuonensql /usr/local/var/log
sudo install -m 755 Kuonen.Data.KuonenSql.Server /usr/local/kuonensql/
sudo install -d -o "$(whoami)" -m 700 /usr/local/var/kuonensql
sudo touch /usr/local/var/log/kuonensql.log && sudo chown "$(whoami)" /usr/local/var/log/kuonensql.log

Dienstdatei

Setzt Ihr Konto ein; die Datei kann nur root lesen - das sa-Kennwort steht darin. Kennwort unter KUONENSQL_SA_PASSWORD eintragen, wenn gewünscht weitere Ports.

bash

sed "s/BENUTZER/$(whoami)/" kuonensql.plist | sudo tee /Library/LaunchDaemons/kuonensql.plist > /dev/null
sudo chown root:wheel /Library/LaunchDaemons/kuonensql.plist
sudo chmod 600 /Library/LaunchDaemons/kuonensql.plist
sudo nano /Library/LaunchDaemons/kuonensql.plist

Starten

Ab jetzt startet launchd den Server auch bei jedem Systemstart.
bash
```
sudo launchctl bootstrap system /Library/LaunchDaemons/kuonensql.plist
```

Prüfen

„state = running“ und im Protokoll „TDS-Server lauscht auf [::]:1433“.

bash

sudo launchctl print system/kuonensql | grep -E 'state|pid'
tail -n 20 /usr/local/var/log/kuonensql.log

Die Dateien

`kuonensql.plist`

Gehört nach /Library/LaunchDaemons/kuonensql.plist. Im Quellstand: dist/dienst/macos/kuonensql.plist.

kuonensql.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<!--
  KuonenSQL als launchd-Dienst (U19.10). Ablage: /Library/LaunchDaemons/kuonensql.plist, Besitzer root:wheel, Rechte 600
  (das sa-Kennwort steht hier). Den Platzhalter unter UserName ersetzt der Installationsschritt durch das Konto, unter dem der
  Server läuft - die Schritte stehen im Prüfstand unter Installation → macOS.
-->
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>kuonensql</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/kuonensql/Kuonen.Data.KuonenSql.Server</string>
        <string>1433</string>
        <string>6379</string>
    </array>
    <key>UserName</key>
    <string>BENUTZER</string>
    <key>WorkingDirectory</key>
    <string>/usr/local/var/kuonensql</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>KUONENSQL_DATEN_PFAD</key>
        <string>/usr/local/var/kuonensql</string>
        <!-- Die Einzeldatei entpackt ihre nativen Bibliotheken hierhin (ohne die Angabe unter $HOME/.net). -->
        <key>DOTNET_BUNDLE_EXTRACT_BASE_DIR</key>
        <string>/usr/local/var/kuonensql/.net</string>
        <!-- Kennwort von sa: gilt ab dem Start und bleibt als Hash im Datenordner; danach darf der Eintrag wieder leer werden. -->
        <key>KUONENSQL_SA_PASSWORD</key>
        <string></string>
        <!-- KSQL: TDS mit dem Kern als Sprache und ehrlicher Kennung (K33.1); leer = aus. -->
        <key>KUONENSQL_KSQL_PORT</key>
        <string>1333</string>
        <!-- Weitere Zugänge auf dieselbe Ablage; leer = aus. -->
        <key>KUONENSQL_MYSQL_PORT</key>
        <string></string>
        <key>KUONENSQL_POSTGRESQL_PORT</key>
        <string></string>
        <key>KUONENSQL_GRAPHQL_PORT</key>
        <string></string>
    </dict>
    <key>RunAtLoad</key>
    <true/>
    <!-- Nach einem Absturz neu starten, nach einem gewollten Ende (launchctl bootout) nicht. -->
    <key>KeepAlive</key>
    <dict>
        <key>SuccessfulExit</key>
        <false/>
    </dict>
    <!-- launchd beendet mit SIGTERM; so lange darf der Server seinen Kontrollpunkt schreiben. -->
    <key>ExitTimeOut</key>
    <integer>60</integer>
    <key>SoftResourceLimits</key>
    <dict>
        <key>NumberOfFiles</key>
        <integer>65536</integer>
    </dict>
    <key>StandardOutPath</key>
    <string>/usr/local/var/log/kuonensql.log</string>
    <key>StandardErrorPath</key>
    <string>/usr/local/var/log/kuonensql.log</string>
</dict>
</plist>

Im Betrieb

Protokoll laufend ansehen

bash

tail -f /usr/local/var/log/kuonensql.log

Neu starten

bash

sudo launchctl kickstart -k system/kuonensql

Auf eine neue Fassung

bash

sudo launchctl bootout system/kuonensql
sudo install -m 755 Kuonen.Data.KuonenSql.Server /usr/local/kuonensql/
sudo launchctl bootstrap system /Library/LaunchDaemons/kuonensql.plist

Entfernen (die Daten in /usr/local/var/kuonensql bleiben)

bash

sudo launchctl bootout system/kuonensql
sudo rm /Library/LaunchDaemons/kuonensql.plist

Gut zu wissen

Eine heruntergeladene Einzeldatei hält Gatekeeper zurück: vor dem Kopieren xattr -d com.apple.quarantine Kuonen.Data.KuonenSql.Server.
Unter Windows oder Linux für macOS gebaut, fehlt die Signatur: codesign --force --sign - Kuonen.Data.KuonenSql.Server.
Ist die Firewall von macOS an, Zugriffe von anderen Rechnern erlauben: sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/local/kuonensql/Kuonen.Data.KuonenSql.Server.
launchd beendet den Dienst mit SIGTERM und wartet bis zu 60 Sekunden (ExitTimeOut); der Server schreibt in der Zeit seinen Kontrollpunkt.

Verbinden

Mit SSMS: Servername localhost,1433, SQL Server-Authentifizierung, Anmeldung sa, unter „Verbindungssicherheit“ Serverzertifikat vertrauen. Aus einer Anwendung:

Verbindungszeichenfolge

Server=localhost,1433;User Id=sa;Password=<Ihr-Kennwort>;TrustServerCertificate=True

Alle Zugänge mit ihren Werkzeugen stehen unter Zugriff.

Anmelden beim ersten Start

Das Kennwort von sa setzt KUONENSQL_SA_PASSWORD beim Start — wie MSSQL_SA_PASSWORD bei SQL Server. Es bleibt als Hash im Datenordner. Ohne jedes Kennwort ist sa offen, und der Start warnt. Später ändert es:

T-SQL

ALTER LOGIN sa WITH PASSWORD = 'Ein-Starkes-Kennwort!2026';

Umgebungsvariablen

Name	Bedeutung	Vorgabe
`KUONENSQL_DATEIFREIGABE`	Welche Ordner der Server nach außen zeigt (sys.dm_os_enumerate_filesystem/-file_exists, der Durchsuchen-Dialog von SSMS): Keine, Daten, Protokoll, Sicherung, Serverordner, Alles - mehrere mit Komma verbunden.	Serverordner
`KUONENSQL_SORTIERUNG`	Die Sortierung von master/tempdb und jeder neuen Datenbank ohne eigenes COLLATE. Jeder Name aus sys.fn_helpcollations(); ein unbekannter Name wird übergangen.	SQL_Latin1_General_CP1_CI_AS
`KUONENSQL_RESTZIELE`	Die Zielliste für den Ruf nach draußen (S12.5, z. B. externe KI-Modelle) - ohne sie geht kein Byte hinaus.	leer
`KUONENSQL_KSQL_PORT`	Der KSQL-Port: derselbe TDS-Draht, aber die Sitzung spricht den Kern ohne die Beschränkungen anderer Systeme und nennt die echte Fassung und das echte Wirtssystem. Ohne diese Variable bleibt er AUS; die Dienstvorlagen setzen 1333.	aus
`KUONENSQL_MARIADB_PORT`	Der MariaDB-Port. Ohne diese Variable (oder ein drittes Startargument) bleibt der MariaDB-Draht AUS - eine zweite Tür geht nur auf, wer sie will.	aus
`KUONENSQL_GRAPHQL_PORT`	Der HTTP-Port für GraphQL (/graphql) und SPARQL (/sparql). Ohne ihn (oder ein viertes Startargument) bleiben beide AUS; angemeldet wird nur mit Kennwort.	aus
`KUONENSQL_MARIADB_ANMELDUNG`	Das MariaDB-Anmeldeverfahren (mysql_native_password, caching_sha2_password, client_ed25519).	—
`KUONENSQL_TLS_CERT_PATH`	Pfad zu einem PFX-Serverzertifikat. Ohne Angabe erzeugt der Server beim ersten Verbindungsaufbau - wie SQL Server - ein selbstsigniertes Zertifikat (CN=KuonenSQL).	—
`KUONENSQL_TLS_CERT_PASSWORD`	Das Kennwort des PFX-Zertifikats.	—
`KUONENSQL_FORCE_ENCRYPTION`	Verschlüsselung erzwingen - auch ein Client mit Encrypt=False bekommt dann die volle Verbindung verschlüsselt.	false
`KUONENSQL_VERSIONSTEXT`	Ersetzt den Text von @@VERSION am T-SQL-Zugang, etwa durch "Kuonen SQL Server 2026 17.0". Die Produktversion bleibt 17.0; ob ein Werkzeug den Text liest, zeigt nur der Versuch.	Ansage als SQL Server 2025
`KUONENSQL_TLS_DISABLED`	Keine Verschlüsselung anbieten; ein Client mit Encrypt=True wird abgewiesen.	false
`KUONENSQL_DATEN_PFAD`	Der persistente Datenpfad auf dem Host (Bind-Mount nach /app/data).	./Daten/kuonensql
`KUONENSQL_PORT`	Der TDS-Port des Containers nach außen.	1433
`KUONENSQL_REDIS_PORT`	Der Redis-Port des Containers nach außen.	6379

Verschlüsselung (TLS)

Ohne eigenes Zertifikat erzeugt der Server beim ersten Verbindungsaufbau — wie SQL Server — ein selbstsigniertes Zertifikat (CN=KuonenSQL). Clients brauchen dann TrustServerCertificate=True (in SSMS: „Serverzertifikat vertrauen“). Ein eigenes PFX-Zertifikat binden KUONENSQL_TLS_CERT_PATH und KUONENSQL_TLS_CERT_PASSWORD ein.

Lizenz

Das Docker-Abbild ist der geschützte Auslieferungsbau (dist/build-protected.sh): signiert, verschleiert und mit Lizenzprüfung vor dem Start. Der gewöhnliche Entwicklungsbau — auch die selbst gebaute Einzeldatei — prüft keine Lizenz.

Für Entwickler: aus dem Quellstand

Das Abbild selbst bauen: Die Befehle laufen im Ordner KuonenSQL des Repos Kuonen, der Bau-Kontext ist dessen Wurzel; docker-compose.yml, .env.beispiel und das mehrstufige Dockerfile liegen unter KuonenSQL/docker/ (siehe KuonenSQL/docker/README.md).

Zweck	Befehl
Bauen und im Hintergrund starten	`docker-compose --project-directory . --env-file docker/.env -f docker/docker-compose.yml up -d --build`
Protokolle ansehen	`docker-compose --project-directory . --env-file docker/.env -f docker/docker-compose.yml logs -f`
Stoppen	`docker-compose --project-directory . --env-file docker/.env -f docker/docker-compose.yml down`
Veröffentlichtes Abbild ziehen, statt selbst zu bauen	`docker pull kuomar/kuonensql:latest`
Ohne Compose, mit den Vorgabeports 1433/6379	`docker run -d --name kuonensql-server -p 1433:1433 -p 6379:6379 -e KUONENSQL_SORTIERUNG=SQL_Latin1_General_CP1_CI_AS -v kuonensql-daten:/app/data kuomar/kuonensql:latest`
Bauen (Windows x64, Vorgabe)	`powershell -ExecutionPolicy Bypass -File dist\einzeldatei-bauen.ps1`
Bauen für eine andere Plattform	`powershell -ExecutionPolicy Bypass -File dist\einzeldatei-bauen.ps1 -Plattform linux-x64`
Starten	`Kuonen.Data.KuonenSql.Server 1433 6379`

Die Einzeldatei bringt die .NET-Laufzeit mit, verzichtet aber noch nicht auf den JIT (Native AOT, Roadmap L6.3). Für macOS ist sie unkomprimiert: Unter .NET 10.0.6 stürzt eine komprimierte Einzeldatei dort beim Annehmen von Verbindungen ab.

Installation

Die Einzeldatei

Programm, Daten und Protokoll

Dienstdatei

Starten

Prüfen

Die Dateien

kuonensql.plist

Im Betrieb

Protokoll laufend ansehen

Neu starten

Auf eine neue Fassung

Entfernen (die Daten in /usr/local/var/kuonensql bleiben)

Gut zu wissen

Verbinden

Anmelden beim ersten Start

Umgebungsvariablen

Verschlüsselung (TLS)

Lizenz

Für Entwickler: aus dem Quellstand

`kuonensql.plist`