Skip to content

Add SQL Server query notifications support - #2987

Open
arnabnandy7 wants to merge 1 commit into
microsoft:mainfrom
arnabnandy7:feature/sql-query-notifications
Open

Add SQL Server query notifications support#2987
arnabnandy7 wants to merge 1 commit into
microsoft:mainfrom
arnabnandy7:feature/sql-query-notifications

Conversation

@arnabnandy7

Copy link
Copy Markdown

Description

Adds full SQL Server Query Notifications support, addressing #2910.

This introduces both low-level TDS subscription registration and a high-level Service Broker listener for Java applications that need event-driven cache invalidation or change detection without polling.

Changes

  • Added SQLServerQueryNotificationRequest for configuring notification subscriptions.
  • Added Query Notification TDS headers to SQL batch and RPC requests.
  • Added statement APIs to set, retrieve, and clear notification requests.
  • Added SQLServerQueryNotification as the notification event model.
  • Added ISQLServerQueryNotificationListener for notification and error callbacks.
  • Added SQLServerQueryNotificationListener with:
    • Dedicated Service Broker receive connection
    • Background daemon receiver
    • Configurable callback executor
    • Persistent callback registration
    • Automatic reconnection after connection failures
    • Service Broker conversation cleanup
    • Explicit queue and service creation/removal helpers
  • Added secure notification XML parsing with DTD and external-entity protections.
  • Added validation for request lengths, timeout ranges, payload structure, and listener arguments.
  • Added usage and Service Broker setup documentation.
  • Updated the changelog.

Usage

SQLServerQueryNotificationListener listener =
        new SQLServerQueryNotificationListener(dataSource, "ProductNotificationQueue");

listener.register("products-cache", notification -> {
    System.out.println(notification.getInfo());
    // Refresh data and re-execute the query to renew the one-time subscription.
});

listener.start();

SQLServerQueryNotificationRequest request =
        new SQLServerQueryNotificationRequest(
                "products-cache",
                "service=ProductNotificationService;local database=Products",
                300);

try (SQLServerPreparedStatement statement =
        (SQLServerPreparedStatement) connection.prepareStatement(
                "SELECT ProductID, Name FROM dbo.Products")) {
    statement.setQueryNotificationRequest(request);

    try (ResultSet resultSet = statement.executeQuery()) {
        // Populate the cache.
    }
}

Query Notification subscriptions remain one-shot, consistent with SQL Server behavior. Callback registrations remain active so applications can renew subscriptions using the same correlation key.

Validation

  • JRE 8 compilation passed.
  • JRE 11 compilation passed.
  • 8 focused unit tests passed:
    • Request validation and protocol boundaries
    • Secure payload parsing
    • Malformed and unsafe XML rejection
    • Callback dispatch and persistent registration
    • Callback removal and listener validation
  • git diff --check passed.

Testing limitation

Live Service Broker integration testing was not run locally because mssql_jdbc_test_connection_properties was not configured. The new functionality should be validated in CI against a Service Broker-enabled SQL Server instance.

Checklist

  • Backward-compatible public API additions
  • No new dependencies
  • JRE 8 and JRE 11 compilation
  • Unit tests added
  • Public API Javadoc added
  • Secure XML processing
  • Service Broker lifecycle documented
  • CHANGELOG updated

Closes #2910.

Signed-off-by: Arnab Nandy <arnab_nandy7@yahoo.com>
@github-project-automation github-project-automation Bot moved this to In progress in MSSQL JDBC Jul 15, 2026
@machavan machavan added this to the 13.7.0 milestone Jul 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: In progress

Development

Successfully merging this pull request may close these issues.

[FEATURE REQUEST] : Support for SQL Server Query Notifications (similar to SqlDependency)

2 participants