- 10 minutes to read

Manually Install or Update Nodinite Monitoring Agent Databases

Easily install or update Nodinite Monitoring Agent databases to ensure optimal monitoring, performance, and long-term statistics. This guide empowers you to:

  • ✅ Follow step-by-step instructions for manual installation and updates
  • ✅ Meet all prerequisites and required permissions for a smooth process
  • ✅ Use SqlPackage or DACPAC files for flexible deployment
  • ✅ Ensure secure, compliant, and high-performing monitoring environments

Info

On this page, you will learn how to manually install and update Nodinite Monitoring Databases for Agents.

Important

You must use SqlPackage version 170 or later! Make sure the Nodinite SqlPackageExecutable System Parameter matches accordingly.

The following Monitoring Agents use a Monitoring Database to improve performance and/or provide long-term statistics:

Use the account for the Nodinite Monitoring Agent to perform database installation and updates. If you are not performing the steps in this guide with that service account, you must at least have the DB_Creator, DiskAdmin, and Security Admin rights, or the sysadmin right on the SQL Server instance to install or update the monitoring database.

For the complete policy rationale, operational impact, and mitigation paths when sysadmin is not assigned, see SQL Server Sysadmin Requirements.

Installation model and database update behavior

How Monitoring Databases are updated depends on where the agent is installed.

flowchart TD Start["fa:fa-hard-drive Monitoring Agent with a Monitoring Database"] --> Where{"Where is the agent installed?"} Where -->|"From the Portal package, on any server in the Environment"| CLI["fa:fa-terminal CLI install or update
elevated PowerShell 7"] Where -->|"With an MSI, for example on a BizTalk server"| Manual["fa:fa-screwdriver-wrench MSI, installer exe, or DACPAC
this page"] CLI --> Auto["fa:fa-database Monitoring Database deployed or updated by the CLI"] Manual --> Start2["fa:fa-play Agent updates the schema on each start
when it has db_owner"] style CLI fill:#2678BD style Auto fill:#93d16d style Manual fill:#E47528 style Start2 fill:#3F827B

Diagram: the two ways a Monitoring Database is installed and updated. Blue is the CLI workflow in the generated Nodinite Portal package; orange is the manual path on this page; in both cases the Monitoring Agent also updates its own schema on start when it has the SQL rights.

Agent placement Typical install model Database update behavior
Agent installed from the Portal package, on any server in the Environment CLI package deployment (default v7 pattern), see Updating Nodinite v7 Set the connection string in the Portal; the CLI deploys and updates the Monitoring Database
Agent installed with an MSI (for example many BizTalk host deployments) MSI/manual host deployment Use the MSI/manual approach documented on this page

Important

If the Azure Logic Apps and/or BizTalk Server agent components are installed on the Nodinite application server, the CLI flow will try to update their Monitoring Databases.

Verified Topic
Software Requirements
Windows rights
Database rights
Firewall

Software Requirements

This functionality requires that the Microsoft Data-tier Applications SqlPackage.exe is installed on the server hosting the Monitoring Agent. Download it from either our download page or directly from Microsoft.

Product
Windows Server Windows Server Windows version as determined by the Monitoring Agent
.NET .NET Framework 4.8 or .NET 10 The BizTalk Server, Dynamics 365, and IBM DataPower agents run on .NET Framework 4.8; the Azure Logic Apps agent runs on .NET 10
SQLPackage.exe Data-tier Applications No license required

What Windows rights does the installation and update process require?

The Monitoring Agent runs as a Windows Service and is responsible for updating existing databases (runs on each start). The Service account (may be different for different Monitoring Agents) must have local rights on the Windows Server. In addition, the Service account must also have the proper SQL Rights on the SQL instance with the Monitoring Database; see the next section.

All Monitoring Agents require the privileges described on the 'Windows Service Account' page.

What SQL Rights does the installation and update process require?

On each startup, the Nodinite Monitoring Agent updates the Monitoring Database if a new version of the model exists. The identity for the Windows account running the Service is the one in use for the update operation.

graph LR subgraph "SQL Server" roDatabase(fal:fa-database Monitoring database) end subgraph "Application Server" roMA(fal:fa-hard-drive Monitoring Agent) --- roDatabase end

Diagram: the Monitoring Agents that need one connect to their own Monitoring Database on SQL Server, configured through Remote Configuration with a connection string that the SQL firewall rules must allow.

Required SQL Server rights

On the SQL Server instance with the Monitoring Database, the account must have the following User Mapping (assign manually after installing the database):

  • db_owner - Required for both installation/updates and runtime operations. This permission allows:
    • Installation: Creating database objects, tables, stored procedures, and initial schema
    • Automatic Updates: Applying schema changes when newer versions of the Monitoring Agent start
    • Runtime Operations: Reading and writing monitoring data, statistics, and performance metrics

Important

The db_owner role is required during both installation/update AND normal runtime operation. The Monitoring Agent automatically updates the database schema on each startup if a newer version is detected, which requires db_owner permissions.

What Firewall settings are required by the installation and update process?

The Monitoring Agent opens the same kinds of connections to the SQL Server instance with the Monitoring Database as the Core Services open to the Configuration Database: SQL Server, MSDTC and RPC, and the domain controller for DNS and Kerberos. The source host is the server where the agent runs. The ports live in one place, the SQL Server Firewall Configuration guide:

The agent's own ports, between the Monitoring Service and the agent, are on the Prerequisites page of each agent.

Set the Agent Database in the Portal

For agents in the Portal package, the database settings are part of the agent card in Step 5: Agents. Every agent with its own database shows the same fields:

Azure Logic Apps agent card with Server, Port, Service account, Database type, Agent database connection string, and the prompt toggle (7.12)
Example of the Azure Logic Apps agent card. The agent database fields are at the bottom.

  • Database type: Standalone (a single SQL Server instance), AlwaysOn (an availability group, see Always On Availability Groups), or Managed Instance (Azure SQL Managed Instance).
  • Agent database connection string: the connection string for the agent's own database. The database name defaults to Nodinite_<Environment>_Agent_<Type>.
  • Prompt for connection string during install: leave the string out of the package, and supply it when the CLI prompts, or with --agent-connection-string (see Common CLI commands).

To move the database, change these fields and run the update again.

How do I install a Monitoring Database?

Note

For CLI-managed agents installed on the Nodinite application server, manual installation is usually not required because deployment and updates are handled by the CLI flow.

There are two ways of installing a new Monitoring Database:

  1. Executing the database installer (.exe) manually

    Important

    You must have set a proper configuration for the database in the configuration file before launching the installer.

  2. Manually install the monitoring database using the %NAME%.DACPAC file

1. Executing the database installer manually using the Database Installer (.exe)

Any update requires the Microsoft DACFRAMEWORK binaries to be installed; please review the SQL Server Package (DACPAC) user guide

Before you execute the installer, you must provide information about the SQL Server instance and the name of the monitoring database. This connectivity information is set using the MonitorAgentConnectionString property either using Remote Configuration or directly editing the configuration file.

Use Notepad++, or run notepad with elevated privileges:

Note

The steps below apply to agents installed with an MSI and use their Settings.json file. For agents from the Portal package, set the connection string in the Portal instead, see Set the Agent Database in the Portal.

  1. Open the Settings.json file

  2. Set the SSL options to use by the Agent connecting with the target SQL Server.

    Connect without encryption: /SourceEncryptConnection=False or /TargetEncryptConnection=False
    Trust server certificate: /SourceTrustServerCertificate=True or /TargetTrustServerCertificate=True

    The following are the Nodinite default values in use by the SQL Server Package (DACPAC) to install or update the Monitoring database:

    ...
"SourceEncryptConnection": true,
"SourceTrustServerCertificate": false,
"TargetEncryptConnection": true,
...
"TargetTrustServerCertificate": true,
...

  3. Set the appropriate MonitorAgentConnectionString using Microsoft.Data.SqlClient with modern TLS defaults.

    ...
"MonitorAgentConnectionString": "Server=localhost;Database=Nodinite_MonitorAgent_%AgentName%_Test;Integrated Security=True;Connection Timeout=60;TrustServerCertificate=True",
...

    Tip

    Need help with connection strings? See the comprehensive SQL Server Connection Strings guide for certificate validation, AOAG configuration, troubleshooting, and security best practices. [!NOTE] Named instances must be JSON formatted (use two backslashes for configuration \\), for example, Server=localhost\\instancename

  4. Run the Nodinite.Installer.MonitorAgent.%AgentName%Database.exe using an account that has SQL rights to create new databases.
    Agent database install
    Manual installation of a Monitoring Agent database using the installer

  5. Set SQL database rights as described on this page.

2. Manually installing the monitoring database using the .DACPAC file

Follow the guide below to manually install the monitoring database using the .DACPAC file:

  1. Copy the %NAME%.DACPAC file from the Monitoring Agent installation folder to a local disk on the SQL Server instance.
  2. From SSMS on the SQL Server instance, choose "Deploy Data Tier Application".
    • Follow the steps in the Deploy Data-tier Wizard...

    If you host multiple monitoring databases on the same SQL Server instance, make sure to provide a uniquely identifiable name for each database.

  3. Set SQL database rights as described on this page.

How do I update a Monitoring Database manually?

Important

If the agent is installed on the Nodinite application server through the v7 CLI package flow, database updates are normally performed automatically by the CLI deployment/lifecycle flow.

Note

For agents installed with MSI on non-Nodinite hosts (common for BizTalk host servers), continue using the manual MSI/DACPAC update process described below.

CLI commands for agents

For agents in the generated package, the CLI installs a single agent with install-agent (see Common CLI commands); its Monitoring Database is deployed as part of that run. For an IIS-hosted agent, install-agent also updates an existing Monitoring Database by applying the latest DACPAC.

.\Nodinite.Installer.Cli.exe install-agent --config .\NODINITE01\config.cli.json --agent AzureLogicApps

Until those commands are published, use:

  • The CLI workflow for agents installed on the Nodinite application server
  • The MSI/DACPAC manual flow below for agents installed on remote hosts

To update the database manually, follow the steps below.

Usually, you do not need to perform the update manually since the Monitoring Agent updates the database during the startup of the service, if it has the appropriate rights. You can find information about the outcome of such operations in the diagnostic files.

1. Executing the database installer manually using the .exe file

  1. Please review the configuration steps in the install section and adjust the configuration file before you continue.
  2. Run the Nodinite.Installer.MonitorAgent.%AgentName%Database.exe, using the account that has SQL rights to create new databases

Agent database update
Manual update of a Monitoring Agent database using the installer

2. Manually updating the monitoring database using the .DACPAC file

Follow the guide below to update the monitoring database using the %NAME%.DACPAC file manually:

  1. Copy the %NAME%.DACPAC file from the folder where the Monitoring Agent is installed to a local disk on the target SQL Server instance.
  2. From SSMS on the SQL Server instance where you want to update the database, choose "Update Data Tier Application".
    • Follow the steps in the Update Data-tier Wizard...

    If you host multiple monitoring databases on the same SQL Server instance, make sure to select the correct database for the update operation.

Next Steps

Back up the Monitoring Database regularly, and use the Nodinite Database Monitoring Agent to check that its size stays within your thresholds.