---
title: SAIF.NetCore.DBConnectionClient overview
summary: High-level purpose, scope, and responsibilities for this library.
status: draft
owner: Framework.NCore maintainers
last_reviewed: 2026-10-02
library: SAIF.NetCore.DBConnectionClient
reference_type: package
---

# SAIF.NetCore.DBConnectionClient overview

> **Documentation context:** Packaged Component (NuGet)

`SAIF.NetCore.DBConnectionClient` is an implementation-layer NuGet package that provides `ConnectionClient`, the sole behavioral type implementing the `IDBConnectionClient` contract from `SAIF.NetCore.ServiceContracts`; rather than connecting to any database itself, it retrieves fully formatted SQL Server, PostgreSQL, and Oracle connection strings from a remote HTTP service (the DBConnectionAPI) on behalf of the hosting application.

## Purpose
- Act as a connection-string retrieval client: callers that need to open a SQL Server, PostgreSQL, or Oracle connection ask `ConnectionClient` for the formatted connection string instead of assembling or storing one themselves.
- Centralize the HTTP calling convention (client-identity headers, NTLM authentication, retry-with-backoff, in-memory caching) that every connection-string lookup shares, so individual applications do not reimplement it.
- Serve as the implementation half of a contract/implementation split: the interface (`IDBConnectionClient`) lives in the foundation `SAIF.NetCore.ServiceContracts` package, while this package supplies the concrete behavior, typically wired up by `SAIF.NetCore.ServiceExtensions`.

## Responsibilities
- Resolve the DBConnectionAPI base URL and the three endpoint path segments from the `DBConnectionClient` configuration section via `IEnvironmentClient.GetSettingValue`.
- Configure the injected `IHttpJsonClient` with client-identity headers and, when supplied, explicit NTLM service-account credentials.
- Retrieve connection strings over HTTP with a bounded retry policy and cache successful results per connection name for the lifetime of the client instance.
- Classify HTTP outcomes into permanent failures (401, 403, 404 — fail fast), transient failures (503 or network error — retry), and other failures, and translate classified response failures and exhausted transient retries into `DBClientException`; a malformed backoff configuration instead throws `InvalidOperationException`, and exceptions from the injected `IHttpJsonClient` or `IEnvironmentClient` propagate unwrapped.
- Decode legacy special-character placeholders (`ZSPECIALCHAR`) in returned connection strings before caching and returning them.

## Key components
- `ConnectionClient`: the template-method-style class that owns configuration resolution, HTTP client setup, retrieval-with-retry, and caching.
- `ConnectionClientKeys`: the `public static class` holding the configuration section name and the three endpoint-key constants.
- `DBClientException`: the `SAIFException` (ServiceContracts) subtype used to surface classified HTTP response failures and exhausted transient retries; configuration errors (`InvalidOperationException`) and collaborator exceptions are not wrapped in it.

## Related documentation
- [Index](index.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Configuration](configuration.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Security and authorization](security-authorization.md)
- [API reference](api/index.md)

## Sources
- `src/SAIF.NetCore.DbConnectionClient/SAIF.NetCore.DBConnectionClient/SAIF.NetCore.DBConnectionClient/ConnectionClient.cs`
- `src/SAIF.NetCore.DbConnectionClient/SAIF.NetCore.DBConnectionClient/SAIF.NetCore.DBConnectionClient/ClientException.cs`
- `src/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/SAIF.NetCore.ServiceContracts/IDBConnectionClient.cs`