NPipeline.Connectors.SqlServer.Analyzers 0.68.0

NPipeline SQL Server Connector Analyzers

SQL Server connector-specific analyzers for NPipeline.

Installation

This analyzer is distributed as a separate NuGet package to provide connector-specific diagnostics only to users who use the SQL Server connector.

dotnet add package NPipeline.Connectors.SqlServer.Analyzers

Analyzers

NP9502: SQL Server source with checkpointing requires ORDER BY clause

Category: Reliability Default Severity: Warning

When using checkpointing with SQL Server source nodes, the SQL query must include an ORDER BY clause on a unique, monotonically increasing column. This ensures consistent row ordering across checkpoint restarts. Without proper ordering, checkpointing may skip rows or process duplicates.

Example

// ⚠️ NP9502: checkpointing without ORDER BY
var source = SqlServerConnector.Source<MyRecord>(connectionString, "SELECT id, name FROM my_table",
    o => o with { CheckpointStrategy = CheckpointStrategy.Offset, CheckpointStorage = storage });

// ✅ A stable order on a unique key
var ordered = SqlServerConnector.Source<MyRecord>(connectionString, "SELECT id, name FROM my_table ORDER BY id",
    o => o with { CheckpointStrategy = CheckpointStrategy.Offset, CheckpointStorage = storage });

Both CheckpointStrategy.Offset and InMemory resume by skipping the rows already read, so both are checked. The analyzer recognises SqlServerConnector.Source(...), the dependency-injection factory's CreateSourceNode(...), and options built with an object initializer.

Why This Matters

Checkpointing tracks the position of processed rows to enable recovery from failures. Without a consistent ORDER BY clause:

• Data Loss: Rows may be skipped during recovery
• Data Duplication: Rows may be processed multiple times
• Inconsistent State: Checkpoint positions become unreliable

Recommended Ordering Columns

Use a unique, monotonically increasing column such as:

• id (primary key)
• created_at (timestamp)
• updated_at (timestamp)
• timestamp (timestamp column)
• Any auto-incrementing or sequential column

Configuration

This analyzer is automatically enabled when the package is referenced. No additional configuration is required.

Scope

This analyzer only applies to:

• SqlServerSourceNode<T> instantiations
• Queries with checkpointing enabled (any strategy except CheckpointStrategy.None)
• String literal queries (not interpolated strings or dynamic queries)

Related Documentation

• SQL Server Connector Documentation
• Checkpointing Best Practices
• Production Recommendations

License

This package is licensed under the Business Source License 1.1.

Free for non-production use. Production use is free for organizations with 4 or fewer developers and annual revenue of $5M AUD or less. Larger organizations require a commercial license. This license automatically converts to MIT two years after each release.