MSSQL targets

View as Markdown

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 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.

Image loading...

Click New target and select MSSQL 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 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.

Info

Fields like Host, Username, Password, and Database can use custom variables 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.

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 below.

Using the MSSQL target in YAML pipelines

Reference the target by ID in an MSSQL CLI action:

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 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 on your firewall, or route the connection through a proxy SSH 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.