148 lines
8.2 KiB
Markdown
148 lines
8.2 KiB
Markdown
---
|
|
source_files:
|
|
- DataPRO/DbAPI/Connections/IConnectionDetails.cs
|
|
- DataPRO/DbAPI/Connections/ConnectionDetails.cs
|
|
- DataPRO/DbAPI/Connections/IConnections.cs
|
|
- DataPRO/DbAPI/Connections/ConnectionManager.cs
|
|
generated_at: "2026-04-17T15:54:12.769963+00:00"
|
|
model: "zai-org/GLM-5-FP8"
|
|
schema_version: 1
|
|
sha256: "2046609d3e9bf292"
|
|
---
|
|
|
|
# Documentation: DbAPI.Connections Namespace
|
|
|
|
## 1. Purpose
|
|
|
|
This module manages database connectivity for the DataPRO system, supporting both SQL Server LocalDB instances and remote/centralized databases. It handles the full lifecycle of LocalDB instances (creation, startup, shutdown, deletion, and database attachment), provides user authentication services with both NTLM and username/password modes, and maintains thread-safe tracking of active connections and logged-in users. The module serves as the data access foundation for the broader DataPRO application.
|
|
|
|
---
|
|
|
|
## 2. Public Interface
|
|
|
|
### IConnectionDetails (Interface)
|
|
|
|
Properties:
|
|
- `bool UseNTLMAuthentication { get; set; }` - Controls whether NTLM authentication is used for database connections.
|
|
- `string DbUser { get; set; }` - Username for database authentication when not using NTLM.
|
|
- `string DbUserPassword { get; set; }` - Password for database authentication when not using NTLM.
|
|
- `string InstanceName { get; set; }` - LocalDB instance name.
|
|
- `string DbServer { get; set; }` - Database server address for remote connections.
|
|
- `string DbName { get; set; }` - Target database name.
|
|
- `bool UsingCentralizedDb { get; set; }` - Distinguishes between LocalDB (false) and remote DB (true) modes.
|
|
- `string DbFolderPath { get; set; }` - Path to database files for LocalDB.
|
|
- `string AttachDbsBatPath { get; set; }` - Path to attach.bat script for LocalDB database attachment.
|
|
- `string ODBCToolsPath { get; set; }` - Path to SQLCMD.EXE directory.
|
|
- `string SqlDbPath { get; set; }` - Path to SQL Server LocalDB installation.
|
|
- `int ClientDbVersion { get; set; }` - Expected database version from client code.
|
|
- `int ConnectionDbVersion { get; set; }` - Actual database version being used.
|
|
|
|
Methods:
|
|
- `string GetConnectionString()` - Returns a connection string suitable for `SqlClient`.
|
|
- `IConnectionDetails Clone()` - Returns a deep copy of the connection details.
|
|
|
|
---
|
|
|
|
### ConnectionDetails (Class)
|
|
|
|
Implements `IConnectionDetails`.
|
|
|
|
**Constructors:**
|
|
- `ConnectionDetails()` - Default constructor with initialized defaults.
|
|
- `ConnectionDetails(ConnectionDetails details)` - Copy constructor for cloning.
|
|
|
|
**Default Values:**
|
|
| Property | Default Value |
|
|
|----------|---------------|
|
|
| `UseNTLMAuthentication` | `true` |
|
|
| `DbUser` | `"DataPROUser"` |
|
|
| `DbUserPassword` | `"DTSSealBeachHQ"` |
|
|
| `InstanceName` | `"DataPROInstance"` |
|
|
| `DbServer` | `@"(localdb)\DataPROInstance"` |
|
|
| `DbName` | `"DataPRO"` |
|
|
| `UsingCentralizedDb` | `false` |
|
|
| `DbFolderPath` | `""` |
|
|
| `AttachDbsBatPath` | `""` |
|
|
| `SqlDbPath` | `""` |
|
|
| `ODBCToolsPath` | `""` |
|
|
|
|
**Methods:**
|
|
- `virtual string GetConnectionString()` - Returns cached connection string if available; otherwise builds and caches it. Format depends on `UseNTLMAuthentication`:
|
|
- NTLM: `Server={DbServer};Database={DbName};Trusted_Connection=TRUE;`
|
|
- SQL Auth: `Server={DbServer};Database={DbName};User Id={DbUser};Password={DbUserPassword};`
|
|
- `override string ToString()` - Returns `"{DbServer}\{DbName}"` for centralized DB or `"Local\{DbName}"` for LocalDB.
|
|
- `virtual IConnectionDetails Clone()` - Returns a new `ConnectionDetails` copied from the current instance.
|
|
|
|
---
|
|
|
|
### IConnections (Interface)
|
|
|
|
Methods:
|
|
- `IConnectionDetails[] GetActiveConnections()` - Returns all successfully connected databases.
|
|
- `ulong LoginUserHash(IConnectionDetails connection, string user, string hash, out IUserDbRecord userObject)` - Authenticates user with a pre-hashed password. Returns `0` (ERROR_SUCCESS) on success, `ERROR_LOGINFAILED` for failed login, `ERROR_UNKNOWN` for unexpected errors.
|
|
- `ulong LoginUser(IConnectionDetails connection, string user, string password, out IUserDbRecord userObject)` - Authenticates user with plaintext password. Returns same error codes as `LoginUserHash`.
|
|
- `ulong ConnectToDb(IConnectionDetails details)` - Establishes database connection. Returns `0` on success.
|
|
- `bool IsUserLoggedIn(IUserDbRecord user, IConnectionDetails connection)` - Checks if a user is currently logged in to a specific database.
|
|
- `Tuple<IUserDbRecord, IConnectionDetails>[] GetLoggedInUsers()` - Returns all logged-in users across all connected databases.
|
|
- `void ClearConnections()` - Removes all logged-in users and database connections.
|
|
|
|
---
|
|
|
|
### ConnectionManager (Internal Class)
|
|
|
|
Internal implementation of `IConnections`. Not exported publicly.
|
|
|
|
**Additional Internal/Static Methods:**
|
|
- `static ulong GetSqlCommand(IConnectionDetails con, out SqlCommand cmd, string commandText = "")` - Creates an open `SqlConnection` with a `SqlCommand`. Returns `ERROR_SUCCESS` or `ERROR_UNKNOWN`.
|
|
|
|
**Private Methods:**
|
|
- `ulong Connect(IConnectionDetails details)` - Internal connection logic; clones details and routes to `ConnectRemote` or `ConnectLocal`.
|
|
- `ulong ConnectRemote(IConnectionDetails details)` - Handles remote database connections.
|
|
- `ulong ConnectLocal(IConnectionDetails details)` - Handles LocalDB lifecycle (stop, delete, create, start, attach).
|
|
- `void StopInstance(IConnectionDetails details, LogDelegate log)` - Stops LocalDB instance.
|
|
- `void DeleteInstance(IConnectionDetails details, LogDelegate log)` - Deletes LocalDB instance.
|
|
- `void CreateInstance(IConnectionDetails details, LogDelegate log)` - Creates LocalDB instance.
|
|
- `void StartInstance(IConnectionDetails details, LogDelegate log)` - Starts LocalDB instance.
|
|
- `void AttachDatabases(IConnectionDetails details, LogDelegate log)` - Attaches DataPRO and ISO databases.
|
|
- `static void AttachDatabase(IConnectionDetails details, string dbName, LogDelegate log)` - Attaches a single database via batch file.
|
|
|
|
---
|
|
|
|
## 3. Invariants
|
|
|
|
- **Thread Safety:** All access to `_loggedInUsers` is protected by `LOGIN_LOCK`, and all access to `_connections` is protected by `CONNECT_LOCK`.
|
|
- **Connection String Caching:** `GetConnectionString()` caches the result in `_Connection` after first call; subsequent calls return the cached value.
|
|
- **Error Code Convention:** All public methods returning `ulong` use `0` to indicate `ERROR_SUCCESS`. Non-zero values indicate errors.
|
|
- **Clone Independence:** `Clone()` produces a deep copy; modifications to the clone do not affect the original.
|
|
- **LocalDB Lifecycle Order:** When connecting to LocalDB, the system always executes: stop → delete → create → start → attach.
|
|
- **Process Synchronization:** `PROCESS_LOCK` ensures only one external process (SqlLocalDB.exe or batch file) runs at a time.
|
|
- **Password Hashing Format:** `LoginUser` hashes passwords using SHA256 with format `"{password}_{user}"` encoded in UTF-8, then Base64-encoded.
|
|
|
|
---
|
|
|
|
## 4. Dependencies
|
|
|
|
**This module depends on:**
|
|
- `DbAPI.User` - For `User.GetUser()` and `IUserDbRecord`.
|
|
- `DbAPI.Errors` / `DbAPI.Logging` - For `ErrorCodes`, `LogManager`, and `LogEvents`.
|
|
- `DTS.Common.Interface.Database` - For `IUserDbRecord` interface.
|
|
- `DTS.Common.Utils.Database` - For `SqlServerLocalDbException`, `LogDelegate`.
|
|
- `DTS.Common.Utilities.Logging` - For `APILogger.Log`.
|
|
- `System.Data.SqlClient` - For `SqlConnection` and `SqlCommand`.
|
|
- `System.Security.Cryptography` - For `SHA256` password hashing.
|
|
- `System.Diagnostics` - For `Process` execution.
|
|
|
|
**What depends on this module:**
|
|
- Not determinable from the provided source files alone.
|
|
|
|
---
|
|
|
|
## 5. Gotchas
|
|
|
|
1. **Hardcoded Default Credentials:** `ConnectionDetails` defaults contain hardcoded credentials (`DbUser = "DataPROUser"`, `DbUserPassword = "DTSSealBeachHQ"`). These should be overridden in production use.
|
|
|
|
2. **ConnectRemote Does Not Validate:** The `ConnectRemote()` method unconditionally returns `ERROR_SUCCESS` without actually validating the connection. The actual connection validation only occurs when `GetSqlCommand()` is called later.
|
|
|
|
3. **LocalDB Instance Destruction:** Every call to `ConnectLocal()` destroys and recreates the LocalDB instance. This is destructive and may impact other processes sharing the same instance.
|
|
|
|
4. **Dual Database Attachment:** `AttachDatabases()` always attempts to attach both the configured `DbName` database AND a |