Operations and processes¶

DBConnectionAPI brokers database connection strings. For each request it resolves a template and a secure credential from the SAIF Environment API, composes a connection string, optionally proves that it connects with a constant probe query, caches the result in memory, and returns it. Three retrieval operations serve Oracle, SQL Server and PostgreSQL strings, and three Admin operations return the raw credential parts without validation or caching.

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

Operation catalog¶

ID	Operation	Entry endpoint	Trigger	Owning component	Rules
OP-01	Get SQL Server connection string	`GET /v1/Connections/SQL/{server}/{instance}/{username}`	Authorized HTTP request	`ConnectionManager.GetSqlConnectionString`	BR-DBC-001, BR-DBC-002, BR-DBC-009, BR-DBC-012, BR-DBC-013, BR-DBC-016, BR-DBC-018, BR-DBC-025
OP-02	Get PostgreSQL connection string	`GET /v1/Connections/PostgreSQL/{instance}/{username}`	Authorized HTTP request	`ConnectionManager.GetPostgreSqlConnectionString`	BR-DBC-006, BR-DBC-020, BR-DBC-021, BR-DBC-025
OP-03	Get Oracle connection string	`GET /v1/Connections/ORA/{instance}/{username}`	Authorized HTTP request	`ConnectionManager.GetOracleConnectionString`	BR-DBC-001, BR-DBC-012, BR-DBC-013, BR-DBC-015, BR-DBC-016, BR-DBC-019, BR-DBC-025
OP-04	Inspect Oracle connection info	`POST /v1/Admin/GetOracleConnectionInfo`	Authorized HTTP request	`AdminController.GetOracleConnectionInfo`	BR-DBC-023, BR-DBC-024, BR-DBC-025
OP-05	Inspect PostgreSQL connection info	`POST /v1/Admin/GetPostgresConnectionInfo`	Authorized HTTP request	`AdminController.GetPostgresConnectionInfo`	BR-DBC-006, BR-DBC-023, BR-DBC-024, BR-DBC-025
OP-06	Inspect SQL Server connection info	`POST /v1/Admin/GetSqlConnectionInfo`	Authorized HTTP request	`AdminController.GetSqlConnectionInfo`	BR-DBC-023, BR-DBC-024, BR-DBC-025

All 25 rules are cataloged on Business rules.

Cross-operation flow diagram¶

The following diagram visualizes how a retrieval request moves through the operations that share the connection manager.

flowchart TD
    R["Incoming request"] --> A{"Authorized?"}
    A -->|"Denied"| Z["Authorization denial, status not visible in source"]
    A -->|"Authorized"| B{"Which surface?"}
    B -->|"Connections GET"| C["Audit log and key build"]
    B -->|"Admin POST"| H["OP-04, OP-05, OP-06:<br>read template and secure credential,<br>no cache, no probe"]
    C --> T["Read Environment API template (every request)"]
    T -->|"Template missing"| X["Unhandled/package error, status not visible in source"]
    T --> D{"Key cached?"}
    D -->|"Yes"| E["Return cached string"]
    D -->|"No"| F["Read secure credential, split at first pipe"]
    F -->|"Secure setting missing"| N["404 ConnectionManagerException"]
    F -->|"No pipe"| X2["Unhandled/package error, status not visible in source"]
    F --> G{"Database type"}
    G -->|"Oracle OP-03"| I["Probe SELECT 1 FROM DUAL, retry"]
    G -->|"SQL Server OP-01"| J["Probe SELECT 1, retry"]
    G -->|"PostgreSQL OP-02"| K["No probe"]
    I -->|"Final failure"| M["400 (Oracle) / 400* (SQL Server) or 500"]
    J -->|"Final failure"| M
    I --> L["Cache and return"]
    J --> L
    K --> L
    H -->|"Read fails"| X

Transaction boundaries¶

Operation	Unit of work	Commit point	Rollback trigger
OP-01	`IUnitOfWorkFactory` (`SAIF.NetCore.NHibernate`), one throw-away unit per probe attempt	None; `Begin()` is never called and nothing is written	Not applicable
OP-03	`IUnitOfWorkFactory` (`SAIF.NetCore.NHibernate`), one throw-away unit per probe attempt	None; nothing is written	Not applicable

OP-02, OP-04, OP-05 and OP-06 perform no database access. The API writes no data in any operation.

Failure and edge-case behavior¶

Secure setting missing (OP-01, OP-02, OP-03): 404 from ConnectionManagerException, rendered by package middleware (DynamicErrorHandler†) (BR-DBC-009)
Oracle TNS alias not resolved: 400 through the same middleware (BR-DBC-015)
Probe failure after four attempts, invalid credentials, database unavailable or network interruption: 500 through the same middleware (BR-DBC-016)
Credential without a pipe on a retrieval request, or a missing template: unhandled exception; the status is not visible in source** (BR-DBC-010)
Credential without a pipe on an Admin request: 200 with an Error entry (BR-DBC-024)
Authorization failure: produced by the package authorization handler†; the status is not visible in source** (BR-DBC-025)
Cache entries never expire, so a rotated credential is served stale until the process restarts (BR-DBC-004)

Note: Statements marked with † are derived from dependency library documentation via the Legends CLI. Statements marked with * were inferred from code structure or contextual evidence. Statements marked with ** could not be confirmed; treat as unknown until verified.

Sources¶

DBConnectionAPI/DBConnectionAPI/Controllers/ConnectionsController.cs
DBConnectionAPI/DBConnectionAPI/Controllers/AdminController.cs
DBConnectionAPI/DBConnectionAPI/Services/ConnectionManager.cs
DBConnectionAPI/DBConnectionAPI/Services/IConnectionManager.cs
DBConnectionAPI/DBConnectionAPI/Exceptions/ConnectionManagerException.cs
DBConnectionAPI/DBConnectionAPI/Startup.cs