---
title: SAIF.NetCore.DBConnectionClient operations and processes
summary: Business and technical operations supported by this library.
status: draft
owner: Framework.NCore maintainers
last_reviewed: 2026-10-02
library: SAIF.NetCore.DBConnectionClient
reference_type: package
---

# SAIF.NetCore.DBConnectionClient operations and processes

This page is the operation catalog and cross-operation hub for this library. Each operation's detailed, step-by-step logic lives in its own page under `operations/`.

## Operation catalog
| Operation | Intent | Trigger | Inputs | Outputs | Rules |
| --- | --- | --- | --- | --- | --- |
| [Construct and configure the client](operations/construct-and-configure-client.md) | Build a working `ConnectionClient` instance bound to the DBConnectionAPI. | DI factory in `ServiceExtensions.RegisterDBConnectionClient`, or direct `new`. | `IHttpJsonClient`, `IEnvironmentClient` | Configured instance | [BR-DBC-01](business-rules.md#br-dbc-01-configuration-keys-source-the-service-url-and-endpoint-segments), [BR-DBC-02](business-rules.md#br-dbc-02-every-request-identifies-itself-via-client-info-headers), [BR-DBC-03](business-rules.md#br-dbc-03-ntlm-authentication%2C-defaulting-to-process-identity) |
| [Apply service-account credentials](operations/apply-service-account-credentials.md) | Replace the ambient NTLM identity with an explicit service-account credential. | Called by `ServiceExtensions.RegisterDBConnectionClient` after decrypting `connectionservicecreds`. | `username`, `password` | NTLM credentials applied | [BR-DBC-03](business-rules.md#br-dbc-03-ntlm-authentication%2C-defaulting-to-process-identity) |
| [Get a SQL Server connection string](operations/get-sql-server-connection-string.md) | Return a ready-to-use SQL Server connection string. | Caller invokes `GetSqlServerConnection`. | `server`, `instance`, `userName` | Connection string | [BR-DBC-04](business-rules.md#br-dbc-04-cache-keys-are-engine-prefixed) |
| [Get a PostgreSQL connection string](operations/get-postgresql-connection-string.md) | Return a ready-to-use PostgreSQL connection string. | Caller invokes `GetPostgreSqlServerConnection`. | `server`, `instance`, `userName` | Connection string | [BR-DBC-04](business-rules.md#br-dbc-04-cache-keys-are-engine-prefixed), [BR-DBC-05](business-rules.md#br-dbc-05-postgresql-host-is-managed-client-side) |
| [Get an Oracle connection string](operations/get-oracle-connection-string.md) | Return a ready-to-use Oracle connection string. | Caller invokes `GetOracleConnection`. | `instance`, `userName` | Connection string | [BR-DBC-04](business-rules.md#br-dbc-04-cache-keys-are-engine-prefixed) |
| [Cached lookup](operations/cached-lookup.md) | Serve a connection string from the in-memory cache, or populate it. | Called internally by every `Get*Connection` method. | `connectionName`, `urlPath` | Connection string | [BR-DBC-06](business-rules.md#br-dbc-06-successful-retrievals-are-cached-for-instance-lifetime%3B-failures-are-not) |
| [Retrieve with retry](operations/retrieve-with-retry.md) | Fetch a connection string from the DBConnectionAPI with bounded retry on transient failure. | Called internally on a cache miss. | `connectionName`, `urlPath` | Connection string, or `DBClientException` | [BR-DBC-07](business-rules.md#br-dbc-07-backoff-configuration-must-cover-all-retry-attempts), [BR-DBC-08](business-rules.md#br-dbc-08-bounded-retry-with-fixed-backoff), [BR-DBC-09](business-rules.md#br-dbc-09-401%2F403%2F404-are-permanent-failures), [BR-DBC-10](business-rules.md#br-dbc-10-503-or-network-level-failure-is-transient), [BR-DBC-11](business-rules.md#br-dbc-11-other-failures-and-empty-bodies-fail-immediately) |
| [Legacy special-character decoding](operations/legacy-special-character-decoding.md) | Decode legacy placeholder tokens in a returned connection string. | Called internally on a successful HTTP response. | Raw connection string | Decoded connection string | [BR-DBC-12](business-rules.md#br-dbc-12-legacy-special-character-token-is-decoded) |

## Process flow diagram
The following diagram visualizes the primary operational flow across operations.

```mermaid
flowchart TD
	Start(["Caller invokes Get*Connection"]) --> Key[Build engine-prefixed cache key]
	Key --> Cache{Key cached?}
	Cache -->|Yes| Return([Return cached connection string])
	Cache -->|No| Retrieve["Retrieve with retry: GetAsync against DBConnectionAPI"]
	Retrieve --> Outcome{HTTP outcome}
	Outcome -->|Success, non-empty body| Decode[Decode ZSPECIALCHAR tokens]
	Decode --> AddCache[Add to cache]
	AddCache --> Return
	Outcome -->|401/403/404| FailFast(["Throw DBClientException, no retry"])
	Outcome -->|503 or network error| Backoff{Attempts remaining?}
	Backoff -->|Yes| Delay[Delay 2s/3s/5s and retry]
	Delay --> Retrieve
	Backoff -->|No| FailFast
	Outcome -->|Other non-success or empty body| FailFast
```

## Failure and edge-case behavior
- A denied request (401/403) is never cached, so a later call for the same key hits the API again.
- A missing retry-configuration invariant (`RetrieveBackoffDelays.Length < MaxRetrieveAttempts - 1`) throws `InvalidOperationException` before any HTTP call is made.
- An empty successful body is treated as a failure ("Database connection string is null"), not as a valid empty connection string.

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

> **Note:** Statements marked with `*` were inferred from code structure, naming
> conventions, or contextual evidence where direct confirmation was not available
> in source artifacts.

## 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`