# MSSQL targets

Connect Buddy CI/CD to Microsoft SQL Server with an MSSQL target. Reuse the connection across pipelines to run queries, schema migrations, and database deployments.

Microsoft SQL Server (MSSQL) targets in Buddy let you store the connection to a SQL Server instance once and reuse it across every pipeline that runs queries, schema migrations, or full database deployments. The target is consumed by the [MSSQL CLI action](/docs/yaml/yaml-actions/mssql-cli.md) and can be referenced by name, by tag, or inline in YAML. It also supports AWS RDS for MSSQL, including SSL modes `DISABLE`, `REQUIRE`, and `VERIFY_FULL`.

## How to add an MSSQL target in Buddy

Navigate to the **Targets** tab where all globally defined connections are listed.

![](/docs/targets/target-add.png 640x369)

Click **New target** and select <u>MSSQL</u> from the dropdown menu.

## MSSQL connection settings

Required fields:

- **Name** - human-readable target name; the unique ID is generated automatically and can be edited.
- **Scope** - defines which pipelines have [access](/docs/targets/target-scope.md) to the target.
- **Host** - hostname or IP of the MSSQL server (e.g. `mssql.example.com` or `192.168.1.10`).
- **Port** - MSSQL server port. Default: `1433`.
- **Database** - default database name.
- **Username & Password** - MSSQL authentication credentials.

Optional fields:

- **SSL mode** - one of:
  - `DISABLE` - no encryption.
  - `REQUIRE` (default) - encrypted, server certificate is **not** validated (vulnerable to MITM).
  - `VERIFY_FULL` - encrypted with full server certificate validation; requires `ca_certificate`.
- **CA certificate** - PEM-encoded CA certificate (required when SSL mode is `VERIFY_FULL`).
- **Proxy** - an SSH target used to tunnel traffic to a private MSSQL server.
- **Tags** - labels used to group and match targets.

<Hint type="info">

Fields like `Host`, `Username`, `Password`, and `Database` can use [custom variables](/docs/pipelines/variables.md) defined at the workspace, project, or pipeline level. This keeps secrets out of YAML and lets you switch between environments by overriding the variable set.

</Hint>

## Testing the MSSQL connection

Before saving, use **Test connection** to verify the credentials and network access. The test connects from a Buddy runner to the host and port you provided, performs the SSL handshake (if enabled), and authenticates with the supplied credentials. If the test fails, see [Troubleshooting](#troubleshooting-mssql-connection-errors) below.

## Using the MSSQL target in YAML pipelines

Reference the target by ID in an [MSSQL CLI action](/docs/yaml/yaml-actions/mssql-cli.md):

```yaml
- pipeline: "Run MSSQL migration"
  trigger_mode: ON_EVERY_PUSH
  actions:
    - action: "Apply schema changes"
      type: "MSSQL_CLI"
      target: "mssql-prod"
      execute_commands:
        - "SELECT @@VERSION;"
      execute_files:
        - "migrations/2026_05_19_add_index.sql"
```

You can also define the target inline if you do not want to manage it in the UI:

```yaml
- action: "Smoke query"
  type: "MSSQL_CLI"
  targets:
    - target: "mssql-prod"
      type: "MSSQL"
      host: "mssql.example.com"
      port: 1433
      database: "$MSSQL_DB"
      username: "$MSSQL_USER"
      password: "$MSSQL_PASSWORD"
      ssl_mode: "REQUIRE"
  execute_commands:
    - "SELECT TOP 10 * FROM dbo.audit_log ORDER BY created_at DESC;"
```

See the [MSSQL CLI YAML reference](/docs/yaml/yaml-actions/mssql-cli.md) for the full field list.

## Troubleshooting MSSQL connection errors

Most failures fall into one of the categories below.

- **Connection timeout / host unreachable** - the database is not exposed to Buddy runners. Whitelist the [Buddy IP addresses](/docs/troubleshooting/ip-whitelist.md) on your firewall, or route the connection through a [proxy SSH target](/docs/targets/ssh.md#proxy-target).
- **SSL handshake failed** - the server uses a certificate that does not match the requested SSL mode. Switch to `REQUIRE` (no verification) to confirm it is a certificate issue, then upload the correct CA in `VERIFY_FULL` mode.
- **Login failed for user** - credentials are rejected. Re-check the username, password, and that the user has access to the target database. SQL Server differentiates between Windows auth and SQL auth - the target uses SQL authentication.
- **Cannot open database "..." requested by the login** - the named database does not exist on the server or the user has no access. Verify with `sqlcmd` from outside Buddy and grant `db_datareader`/`db_datawriter` (or whatever role the pipeline needs).
- **Port closed** - the default `1433` is sometimes remapped or blocked. Confirm the port from the DBA and update the target.

## See also

- [MSSQL CLI action - YAML reference](/docs/yaml/yaml-actions/mssql-cli.md)
- [Other database targets: MongoDB](/docs/targets/mongodb.md), [MySQL](/docs/targets/mysql.md), [PostgreSQL](/docs/targets/postgresql.md)
- [Targets - REST API](/docs/api/targets.md)
- [Custom variables in pipelines](/docs/pipelines/variables.md)


---
Original source: https://buddy.works/docs/targets/mssql