SQL Integration

Prerequisites

Install the MW Agent on the machine that will collect metrics. For setup instructions, refer to the Installation Guide.

Configuration

You can configure the receiver in two ways: Setting-Based (form in the UI) or User-Based (create a dedicated SQL user with minimal rights).

Setting-Based Authentication

Fill the integration form with these fields:

• Host: Machine name or IP where SQL Server runs
• Username / Password: SQL auth credentials
• Server: Server IP (e.g., 0.0.0.0 for all interfaces)
• Port: Default 1433
• Instance Name (optional): Named instance, if used
• Collection Interval (optional): Defaults to 10s
• Computer Name (optional): Host label for display

User-Based Authentication

This path uses Docker to run SQL Server and sqlcmd to create a constrained login (mw_user) with the exact permissions the docs specify.

MSSQL Docker configuration

Save the compose file:

1# Create a docker-compose.yml file with the following configuration:
2version: '3.1'
3services:
4  mssql:
5    container_name: mssql-db
6    hostname: mssql-db-host
7    image: mcr.microsoft.com/mssql/server:2022-latest
8    environment:
9      ACCEPT_EULA: "Y"
10      MSSQL_SA_PASSWORD: "<YourSecurePassword>"
11      MSSQL_PID: 'Developer'
12      MSSQL_AGENT_ENABLED: "true"
13      MSSQL_TCP_PORT: 1433
14      MSSQL_ENABLE_HADR: "1"
15    ports:
16      - "1433:1433"
17    volumes:
18      - mssql_data:/var/opt/mssql
19    networks:
20      - mssql-network
21
22networks:
23  mssql-network:
24
25volumes:
26  mssql_data:
27    driver: local

Start the container:

1docker-compose up -d

If SQL Server fails to start due to insufficient async I/O contexts, raise the kernel limit and retry:

1sudo sysctl -w fs.aio-max-nr=1048576

User Authentication Setup

Open a shell in the container:

1docker exec -it --user root mssql-db bash

1. Create the login and user (runs as sa):

1/opt/mssql-tools18/bin/sqlcmd -S mssql-db -U sa -P '<YourSecurePassword>' \
2-Q "USE master; CREATE LOGIN mw_user WITH PASSWORD = '<YourSecurePassword>'; CREATE USER mw_user FOR LOGIN mw_user;" -b -C

Give it a quick connectivity check:

1/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P '<YourSecurePassword>' -Q "SELECT 1" -C -b

You should see 1as an output indicating successful steps:

11

2. Grant the required permissions:

1/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P '<YourSecurePassword>' \
2-Q "USE master; GRANT VIEW SERVER STATE TO mw_user;" -C -b
3
4/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P '<YourSecurePassword>' \
5-Q "USE master; GRANT SELECT ON sys.dm_exec_requests TO mw_user;" -C -b

3. Confirm the user can read from DMVs:

1/opt/mssql-tools18/bin/sqlcmd -S localhost -U mw_user -P '<YourSecurePassword>' \
2-Q "USE master; SELECT * FROM sys.dm_exec_requests;" -C -b

Access Integrations

1 Access SQL Server Integration

Open Installations → All Integrations → SQL Server.

2 Configure the SQL Server Integration

Enter the server the following details and then hit the save button:

• Collection Interval (Optional): Specify the interval at which telemetry data is collected. In this configuration, two intervals are defined: 10s and 5s.
• Computer Name (Optional): Set the computer name for the SQL Server instance. Here, it is CustomServer.
• Instance Name (Optional): Define the specific SQL Server instance. Here, it is CustomInstance.
• Authentication: Provide authentication details (username and password). In this case, the username is sqlserver and the password is sqlserver.
• Server Address: Specify the server IP or hostname. Here, it is 0.0.0.0.
• Port: Define the port used by SQL Server. The default port is 1433

Visualize Analytics

Once the SQL Server integration setup is complete, a new SQL Server-specific dashboard will appear in the Dashboard Builder. This default dashboard serves as a jumping off point for visualizing and analyzing SQL Server data.

Create SQL Server Widget

You can add SQL Server data to dashboards as a custom widget. Follow these steps to configure your widget:

1. Select Widget Dashboard. Navigate to the Create Widget screen.

2. Configure Widget Profile On the Widget Profile screen, define the widget name and description.

3. Set Up Configuration In the Widget Configuration screen, customize data settings, apply filters, and finalize widget preferences.

Alerts

Alerts can be configured for any SQL Server metrics. When creating a new rule, select the Database detection method and SQL Server database type for available metrics to appear in the Metrics dropdown list. Select the desired metric and continue configuring the alert conditions.

Metrics Collected

Troubleshooting

Missing Integrations Menu:

• If you don’t see Integrations in Middleware, your role is missing the Installation permission. Ask an admin to grant it in Settings.

MSSQL container doesn’t start:

• Raise async I/O contexts and start again:

  1sudo sysctl -w fs.aio-max-nr=1048576
  2docker-compose up -d

sqlcmd SSL certificate verify failed

• Include -C with sqlcmd (as shown in the docs) to trust the server certificate in test setups.

User can’t read metrics:

• Re-run the two GRANTs from above and test with:

  1/opt/mssql-tools18/bin/sqlcmd -S localhost -U mw_user -P '<YourSecurePassword>' \
  2-Q "USE master; SELECT * FROM sys.dm_exec_requests;" -C -b