- 14 minutes to read

SqlServer

Control how Nodinite Logging Service connects to SQL Server instances across Azure SQL, on-premises, Always On Availability Groups, and failover clusters. The SqlServer system parameter provides critical information about your SQL Server environment that determines server name resolution, linked server usage, and database creation behavior.

What you'll learn on this page:

✅ CRITICAL: When to contact Nodinite support before modifying this parameter
✅ Understand the JSON structure field-by-field (IsCloudServer, Host, LinkedServerName, etc.)
✅ Configure for Azure SQL Database, on-premises SQL Server, and Always On Availability Groups
✅ Database migration scenarios requiring SqlServer parameter updates
✅ Troubleshoot connection failures and linked server issues

[!DANGER] SUPPORT-ONLY MODIFICATIONS

Administrators should ONLY change any value in this parameter with technical assistance from Nodinite Support.

Changing it incorrectly will very likely render Nodinite totally non-operational, preventing:

  • ❌ Log Database creation and access
  • ❌ Logging Service startup
  • ❌ Monitoring Service data retrieval
  • ❌ Web API database queries
  • ❌ All Core Services database operations

Contact Nodinite Support BEFORE modifying this parameter unless you are executing a pre-approved database migration plan.

Overview

Purpose: The SqlServer system parameter is a JSON configuration object automatically created and maintained based on the Environment entry in the Nodinite portal during installation. It provides critical SQL Server connection details that enable Nodinite Core Services to:

  • ✅ Resolve SQL Server instance names (localhost, named instances, clusters, AOAG listeners)
  • ✅ Differentiate between Azure SQL and on-premises SQL Server environments
  • ✅ Determine correct Linked Server names for distributed queries
  • ✅ Create new Log Databases with proper server targeting
  • ✅ Handle Always On Availability Group configurations automatically

Who Uses This Parameter?

Only specific Nodinite services read the SqlServer parameter:

  • Logging Service — Creates Log Databases, resolves server names, executes distributed queries
  • Monitoring Service — Retrieves monitoring data across databases
  • Log API — Accesses log data through linked servers
  • Web API — Displays database status and server information

When Must This Parameter Be Changed?

Scenario Change Required? Who Should Make Changes?
Fresh Installation ❌ No — Automatically configured Install and Update Tool
Database Migration to Different SQL Server Instance ✅ YES — CRITICAL Nodinite Support with administrator
Azure SQL Migration ✅ YES — CRITICAL Nodinite Support with administrator
Always On Availability Group Setup ⚠️ Maybe — Usually auto-detects Nodinite Support
Named Instance Change ✅ YES — CRITICAL Nodinite Support with administrator
Version Upgrade ❌ No — Preserved Install and Update Tool
Adding New Log Databases ❌ No — Uses existing config None

Important

Database Migration Scenarios: If you are moving Nodinite databases to a different SQL Server instance (different server name, different cluster, different Azure SQL instance, or different named instance), you MUST update the SqlServer parameter as part of the migration process.

See the Database Migration Planning guide for complete migration checklists including when and how to update the SqlServer parameter.

How It Works

JSON Structure

The SqlServer parameter stores a JSON object with the following fields:

{
  "IsCloudServer": true,
  "Server": "myserver.database.windows.net",
  "Host": "myserver.database.windows.net",
  "LinkedServerName": "myserver",
  "Port": "1433",
  "Protocol": "tcp"
}

Field Definitions

Field Type Required? Purpose Used When
IsCloudServer boolean ✅ Critical Determines Azure SQL vs on-premises behavior Always
Server string ⚠️ Conditional SQL Server name/address for on-premises IsCloudServer = false
Host string ⚠️ Conditional FQDN for Azure SQL IsCloudServer = true
LinkedServerName string ⚠️ Conditional Linked server name for distributed queries IsCloudServer = false
Port string ❌ Optional SQL Server port (rarely used) Custom port configurations
Protocol string ❌ Optional Connection protocol (rarely used) Advanced scenarios

IsCloudServer (Critical)

Purpose: Switches Nodinite behavior between Azure SQL and on-premises SQL Server.

Values:

  • true — Azure SQL Database (uses Host field)
  • false — On-premises SQL Server (uses Server and LinkedServerName fields)

Impact:

Component When true (Azure SQL) When false (On-Premises)
Server Name Resolution Uses Host field Uses Server field or resolves localhost
Linked Server Queries Uses Host for four-part names Uses LinkedServerName with instance
Database Creation Targets Azure SQL endpoint Targets on-premises instance
Availability Group Handling Not applicable (Azure manages HA) Checks for AlwaysOn AG configuration
Connection Strings Uses Azure SQL patterns Uses traditional SQL Server patterns

Example Behavior:

// Code automatically switches based on IsCloudServer
if (sqlServerDetails.IsCloudServer)
{
    server = sqlServerDetails.Host;  // Azure: Use Host
}
else 
{
    server = "localhost";  // On-Prem: Use Server or localhost
}

Server

Purpose: Primary SQL Server identifier for on-premises installations.

Used For:

  • Connection string parsing
  • Default server name when not cloud
  • Fallback when other fields not specified

Example Values:

  • localhost — Same server, default instance
  • SQLSERVER01 — Remote server, default instance
  • SQLSERVER01\SQLEXPRESS — Remote server, named instance
  • . — Local default instance

Behavior:

  • On-Premises: Used directly or resolved to actual server name
  • Azure SQL: Ignored (uses Host instead)

Not Used When: IsCloudServer = true

Host

Purpose: Fully Qualified Domain Name (FQDN) for Azure SQL Server.

Required When: IsCloudServer = true

Used For:

  • Azure SQL connection targets
  • Distributed query server names in Azure
  • Database size checks on Azure SQL

Example Values:

  • myserver.database.windows.net — Standard Azure SQL
  • myserver.westeurope.database.windows.net — Specific Azure region
  • myserver-prod.database.usgovcloudapi.net — Azure Government cloud

Critical Code Behavior:

// When IsCloudServer=true, Server property returns Host
public string Server
{
    get => (IsCloudServer.HasValue && IsCloudServer.Value) ? Host : _server;
    set => _server = value;
}

Not Used When: IsCloudServer = false

LinkedServerName

Purpose: Server name for distributed SQL queries on-premises using four-part naming ([LinkedServerName].[Database].[Schema].[Table]).

Required When: On-premises SQL Server with cross-database queries.

Used For:

  • Four-part name queries across databases
  • Verifying Linked Server connectivity
  • Always On AG configurations
  • Creating new Log Databases

Example Values:

  • localhost — Same server, default instance
  • localhost\SQLEXPRESS — Same server, named instance
  • SQLSERVER01 — Remote server
  • SQLSERVER01\INSTANCE — Remote server, named instance

Critical Logic:

// Auto-determined during first database creation
if (sqlServerDetails.IsCloudServer == false)
{
    if (alwaysOnHighAvailabilityGroup is not null)
    {
        linkedServerName = serverInstance.ToStringWithoutPortConfig();  // AG: remove port
    }
    else
    {
        if (serverInstance.HasInstance())
        {
            linkedServerName = $"localhost\\{serverInstance.GetInstance()}";  // Named instance
        }
        else
        {
            linkedServerName = "localhost";  // Default instance
        }
    }
}

// Verify linked server works before creating databases
_logDatabasesManager.VerifyLinkedServer(linkedServerName);

Verification Query Example:

-- Four-part query using LinkedServerName
SELECT database_size 
FROM [localhost].[Nodinite_LogDatabase_001].[sys].[database_files]

Not Used When: IsCloudServer = true

Important

The LinkedServerName must match an actual Linked Server configured in SQL Server Management Studio. See the Linked Servers guide for configuration requirements including RPC and RPC Out settings.

Port & Protocol (Rarely Used)

Purpose: Advanced connection string customization.

Current Status: Defined in JSON structure but NOT actively used in current Nodinite codebase.

Potential Future Use:

  • Custom port configurations (non-default 1433)
  • Protocol specification (tcp vs named pipes)
  • Explicit connection string building

Example Values:

  • Port: "1433" (default), "1434" (dynamic), "49152" (custom)
  • Protocol: "tcp" (TCP/IP), "np" (named pipes), "lpc" (shared memory)

Note: Safe to leave empty or omit from JSON.

Default Behavior (Empty or Missing)

If the SqlServer parameter is empty ("") or missing, Nodinite uses safe defaults:

// Code defaults when parameter is empty
var sqlServerDetails = new SqlServerDetails()
{
    IsCloudServer = false,
    Host = "localhost",
    LinkedServerName = "localhost",
    Server = "localhost"
};

Result: Assumes on-premises localhost installation with default instance.

Use Cases

Scenario 1: Azure SQL Database

Environment: Nodinite deployed to Azure SQL Database.

Configuration:

{
  "IsCloudServer": true,
  "Server": "",
  "Host": "mynodinite.database.windows.net",
  "LinkedServerName": "",
  "Port": "",
  "Protocol": ""
}

Result:

  • ✅ All Log Databases use mynodinite.database.windows.net as server target
  • ✅ Connection strings use Azure SQL patterns
  • ✅ No linked server queries (Azure SQL uses different architecture)
  • ✅ Database creation targets Azure SQL endpoint

When to Use: Azure SQL deployments only.

Prerequisites: See SQL Server Options for Azure SQL requirements.

Scenario 2: On-Premises SQL Server (Default Instance)

Environment: Single Windows Server with SQL Server default instance.

Configuration:

{
  "IsCloudServer": false,
  "Server": "SQLSERVER01",
  "Host": "",
  "LinkedServerName": "localhost",
  "Port": "",
  "Protocol": ""
}

Result:

  • ✅ Connects to SQLSERVER01 (or resolves to actual server name)
  • ✅ Uses localhost for Linked Server queries
  • ✅ Four-part queries: [localhost].[Database].[Schema].[Table]
  • ✅ Standard SQL Server behavior

When to Use: Most common on-premises scenario.

Prerequisites: See Linked Servers for localhost linked server setup.

Scenario 3: On-Premises SQL Server (Named Instance)

Environment: Single Windows Server with SQL Server named instance (e.g., SQLEXPRESS, BIZTALK).

Configuration:

{
  "IsCloudServer": false,
  "Server": "SQLSERVER01\\SQLEXPRESS",
  "Host": "",
  "LinkedServerName": "localhost\\SQLEXPRESS",
  "Port": "",
  "Protocol": ""
}

Result:

  • ✅ Connects to SQLSERVER01\SQLEXPRESS
  • ✅ Linked server includes instance name: localhost\SQLEXPRESS
  • ✅ Four-part queries: [localhost\SQLEXPRESS].[Database].[Schema].[Table]
  • ✅ Named instance properly resolved

When to Use: Named instance installations (common with BizTalk Server environments).

Prerequisites:

  • See Linked Servers for named instance linked server setup
  • Ensure instance name matches exactly (case-insensitive but backslash-sensitive)

Scenario 4: Always On Availability Group (AOAG)

Environment: SQL Server Always On Availability Group with listener.

Configuration:

{
  "IsCloudServer": false,
  "Server": "AG-LISTENER",
  "Host": "",
  "LinkedServerName": "SQLNODE01",
  "Port": "",
  "Protocol": ""
}

Result:

  • ✅ Connects via AG-LISTENER for all connections
  • ✅ Auto-detects AG configuration
  • ✅ Creates databases on primary replica automatically
  • ✅ Uses primary replica server name for linked server queries
  • ⚠️ LinkedServerName may be auto-overridden to primary replica

When to Use: Always On Availability Group deployments.

Prerequisites:

Auto-Detection:

// Nodinite automatically detects AG and uses primary replica
if (alwaysOnHighAvailabilityGroup is not null)
{
    linkedServerName = alwaysOnHighAvailabilityGroup.GetPrimaryReplica().ServerName;
}

Scenario 5: Failover Cluster Instance

Environment: SQL Server failover cluster with virtual network name.

Configuration:

{
  "IsCloudServer": false,
  "Server": "SQL-CLUSTER",
  "Host": "",
  "LinkedServerName": "localhost",
  "Port": "",
  "Protocol": ""
}

Result:

  • ✅ Connects via SQL-CLUSTER virtual network name
  • ✅ Automatic failover to active node
  • ✅ Uses localhost for linked server queries (on active node)
  • ✅ Cluster-aware database creation

When to Use: Failover cluster installations.

Prerequisites:

  • See Linked Servers for cluster-specific linked server configuration
  • Ensure MSDTC configured as clustered resource
  • Linked servers must exist on all nodes

Scenario 6: Empty/Default Configuration

Environment: Development or POC installation on localhost.

Configuration:

{}

or empty string:

""

Result:

  • ✅ Falls back to code defaults:
    • IsCloudServer = false
    • Server = "localhost"
    • Host = "localhost"
    • LinkedServerName = "localhost"
  • ✅ Safe for local development
  • ✅ Works with default instance only

When to Use:

  • Development environments
  • POC installations
  • Single-server localhost testing

Not Recommended For: Production deployments (always configure explicitly).

Behavior Decision Matrix

Environment Type IsCloudServer Server Host LinkedServerName Behavior Summary
Azure SQL true (ignored) myserver.database.windows.net (not used) Uses Host for all operations, no linked servers
On-Prem Default Instance false localhost (not used) localhost Standard local server, four-part queries via localhost
On-Prem Named Instance false SERVER\INST (not used) localhost\INST Includes instance in linked server name
Always On AG false AG-LISTENER (not used) (auto-detected) Auto-resolves to primary replica, auto-failover support
Failover Cluster false SQL-CLUSTER (not used) localhost Cluster-aware, uses virtual network name
Empty/Default (defaults to false) localhost localhost localhost Safe defaults for local development

Common Issues & Troubleshooting

Issue Symptoms Root Cause Solution
Missing Host in Azure "Cannot connect to database" errors in Logging Service IsCloudServer=true but Host is empty Add "Host": "yourserver.database.windows.net"
Wrong LinkedServerName "Linked server not found" SQL error LinkedServerName doesn't match actual linked server Match LinkedServerName to existing linked server or use localhost for same server
AG Not Detected Database created on wrong replica AG configuration issue or permissions Verify AG setup, ensure Nodinite service account has VIEW SERVER STATE permission
Instance Name Missing "Cannot connect to SERVER\INSTANCE" Instance not included in Server or LinkedServerName Add \INSTANCE to both Server and LinkedServerName
Empty Config in Azure Tries to use localhost instead of Azure SQL Parameter empty for Azure deployment Set IsCloudServer=true and provide Host
Linked Server RPC Disabled "RPC remote procedure call" error Linked server missing RPC/RPC Out settings See Linked Servers to enable RPC and RPC Out
Kerberos Authentication Failure "Cannot generate SSPI context" Missing SPNs or delegation not configured See SPN and Trusted for delegation guides

Debugging Steps:

  1. Verify Linked Server Exists:

    -- In SSMS on Configuration Database SQL instance
SELECT * FROM sys.servers WHERE is_linked = 1;

  2. Test Linked Server Connectivity:

    -- Replace [LINKEDSERVERNAME] with your LinkedServerName value
SELECT @@SERVERNAME FROM [LINKEDSERVERNAME].[master].[sys].[databases];

  3. Check Logging Service Logs:

    • Look for errors during database creation (hourly check)
    • Search for "SqlServer" or "LinkedServer" in log messages

  4. Validate JSON Structure:

    • Use the POST /api/SystemParameters/SqlServer/ValidateJson endpoint
    • Verify no syntax errors in JSON

  5. Contact Nodinite Support:

    • Provide full error messages
    • Include current SqlServer parameter value
    • Describe SQL Server environment (Azure/on-prem, AOAG, cluster, etc.)

FAQ

How is this parameter created?

The SqlServer parameter is automatically created during installation by the Install and Update Tool based on the Environment entry you configure in the Nodinite portal. The tool detects your SQL Server configuration and sets appropriate values.

Can I modify this parameter myself?

NO — Contact Nodinite Support first. Incorrect modifications will break Nodinite database operations. The only exception is pre-approved database migration scenarios where you are following a migration plan provided by Nodinite Support.

What happens if I change this incorrectly?

Nodinite Core Services will fail to:

Recovery: Restore the correct value with assistance from Nodinite Support.

When do I need to change this during database migration?

You MUST change the SqlServer parameter when:

✅ Moving to a different SQL Server instance (different server name)
✅ Migrating to Azure SQL from on-premises
✅ Changing from default instance to named instance (or vice versa)
✅ Moving to a different Always On Availability Group
✅ Changing SQL Server cluster virtual network name

See Database Migration Planning for complete migration checklists.

Does this parameter store connection strings or passwords?

NO. The SqlServer parameter only stores server names and configuration flags. It does not store:

  • ❌ Connection strings
  • ❌ SQL credentials
  • ❌ Passwords
  • ❌ SQL Server ports (in most cases)

Connection strings are stored separately in Configuration Database connection string settings.

How does Always On Availability Group detection work?

Nodinite automatically detects Always On configurations by querying SQL Server system views:

// Automatic AG detection
if (alwaysOnHighAvailabilityGroup is not null)
{
    // Use primary replica for database creation
    linkedServerName = alwaysOnHighAvailabilityGroup.GetPrimaryReplica().ServerName;
}

Requirements:

  • Service account must have VIEW SERVER STATE permission
  • AG must be properly configured in SQL Server
  • Listener name must be in Server field

What if my SQL Server uses a non-standard port?

The Port field exists in the JSON structure but is not currently used by Nodinite. Port information is typically embedded in connection strings separately.

If you have a non-standard port scenario, contact Nodinite Support for guidance.

Can I have different SqlServer values for different Log Databases?

NO. The SqlServer parameter is a global setting that applies to all Nodinite operations. If you need to span multiple SQL Server instances for Log Databases, contact Nodinite Support for architecture guidance.

How often does Nodinite read this parameter?

The Logging Service reads the SqlServer parameter:

  • ✅ At service startup
  • ✅ When creating new Log Databases (hourly check by default)
  • ✅ When validating linked server connectivity

Changes take effect: Immediately for new operations, but existing connections remain unchanged until service restart.

What's the difference between Server, Host, and LinkedServerName?

Field Purpose When Used
Server On-premises SQL Server name IsCloudServer = false
Host Azure SQL FQDN IsCloudServer = true
LinkedServerName Distributed query target (four-part names) IsCloudServer = false

Key Insight: When IsCloudServer=true, the Server property returns Host automatically in code.

Next Step

Database Migration:

Related Configuration:

Troubleshooting:

Core Services:

SQL Server Configuration:

Database Migration:

System Parameters:

Installation:

Support: