> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft SQL Server

> Ready-to-run Microsoft SQL Server container template you can run directly or inherit to integrate a relational database into your stack.

## Overview

This template provides a production‑ready Microsoft SQL Server instance as a Monk runnable. You can:

* Run it directly to get a managed SQL Server container with sensible defaults
* Inherit it in your own runnable to seamlessly add a relational database to your stack

It exposes SQL Server on port 1433, persists data to a host volume, and includes SA (system administrator) authentication.

## What this template manages

* SQL Server container (`mcr.microsoft.com/mssql/server` image, configurable tag)
* Network service on port 1433
* Persistent volumes for data storage
* SA authentication and EULA acceptance

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run SQL Server with defaults

```bash theme={null}
monk run mssql/db
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `mssql.yml`, then `monk load MANIFEST` and run.

Once started, connect to `localhost:1433` (or the runnable hostname inside Monk networks) using the configured SA credentials.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  monk_mssql_accept_eula: "Y"          # EULA acceptance (required, env: ACCEPT_EULA)
  monk_mssql_sa_password: "P@ssw0rd"   # SA password (env: SA_PASSWORD)
```

**Note:** The default SA password is `P@ssw0rd`. Always change this in production environments.

Data is persisted under `${monk-volume-path}/mssql` on the host, mapped to `/var/opt/mssql` in the container.

## Use by inheritance (recommended for apps)

Inherit the SQL Server runnable in your application and declare a connection. Example:

```yaml theme={null}
namespace: myapp
db:
  defines: runnable
  inherits: mssql/db
  variables:
    monk_mssql_sa_password:
      value: <- secret("mssql-sa-password")
api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    database:
      runnable: db
      service: mssql-svc
  variables:
    database-host:
      value: <- connection-hostname("database")
    database-user:
      value: "sa"
    database-password:
      value: <- secret("mssql-sa-password")
```

Then set the secrets once and run your app group:

```bash theme={null}
monk secrets add -g mssql-sa-password="STRONG_SA_PASSWORD"
monk run myapp/api
```

## Ports and connectivity

* Service: `mssql-svc` on TCP port `1433`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the DB host.

## Persistence and configuration

* Data path: `${monk-volume-path}/mssql:/var/opt/mssql`
* This volume contains all SQL Server data files, logs, and system databases.

## Features

* Full T-SQL support
* ACID transactions
* Stored procedures and triggers
* Full-text search
* Replication and high availability
* Integration with Azure
* Business intelligence capabilities

## Related templates

* See other templates in this repository for complementary services
* Combine with monitoring tools for observability
* Integrate with your application stack as needed

## Troubleshooting

* If you changed `monk_mssql_sa_password` but the container has existing data, authentication may fail. Either reset the data volume or update the password inside the DB to match.
* Ensure the host volumes are writable by the container user.
* The SA password must meet Microsoft's complexity requirements (uppercase, lowercase, numbers, and special characters).
* Check logs:

```bash theme={null}
monk logs -l 500 -f mssql/db
```