init
This commit is contained in:
@@ -0,0 +1,230 @@
|
||||
---
|
||||
source_files:
|
||||
- DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Storage/DbOperationsEnum.cs
|
||||
- DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Storage/DbVersion.cs
|
||||
- DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Storage/IDbTimeStampAware.cs
|
||||
- DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Storage/DbOperations.cs
|
||||
generated_at: "2026-04-16T04:57:49.383657+00:00"
|
||||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||||
schema_version: 1
|
||||
sha256: "a23af2f838d45bd9"
|
||||
---
|
||||
|
||||
# Documentation: Database Export Module – Version 57 (`DatabaseExport`)
|
||||
|
||||
---
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This module provides infrastructure for exporting and managing database schema and data for **Version 57** of the DataPRO system. It defines core abstractions for database interaction, including table/field metadata constants, stored procedure identifiers, version tracking (`DbVersion`), and timestamp-based concurrency control (`DbTimeStampBase`/`IDbTimeStampAware`). Its primary role is to support migration, export, and synchronization workflows by encapsulating versioned database structure and state management logic—particularly for legacy data exports where schema evolution must be tracked and reconciled.
|
||||
|
||||
---
|
||||
|
||||
## 2. Public Interface
|
||||
|
||||
### `DbOperationsEnum.StoredProcedure`
|
||||
|
||||
- **Type**: `enum`
|
||||
- **Members**:
|
||||
- `sp_DbVersionGet`: Represents the stored procedure used to retrieve the current database version.
|
||||
|
||||
### `DbVersion`
|
||||
|
||||
- **Constructor**:
|
||||
```csharp
|
||||
public DbVersion(System.Data.DataRow dr)
|
||||
```
|
||||
- **Behavior**: Initializes a `DbVersion` instance by extracting values from a `DataRow` expected to contain columns: `"Version"`, `"Step"`, `"Date"`, `"Remarks"`, and `"UserField"`.
|
||||
|
||||
- **Properties**:
|
||||
- `int Version { get; set; }`
|
||||
- Database version number.
|
||||
- `int Step { get; set; }`
|
||||
- Step within the version (e.g., migration step).
|
||||
- `DateTime Date { get; set; }`
|
||||
- Timestamp of the version/step.
|
||||
- `string Remarks { get; set; }`
|
||||
- Optional notes about the version/step.
|
||||
- `string UserField { get; set; }`
|
||||
- Arbitrary user-defined field.
|
||||
|
||||
### `IDbTimeStampAware` Interface & `DbTimeStampBase` Abstract Class
|
||||
|
||||
- **Interface**:
|
||||
```csharp
|
||||
public interface IDbTimeStampAware
|
||||
{
|
||||
long GetTimeStampMemory();
|
||||
void SetTimeStampMemory(long value);
|
||||
long GetTimeStampDb();
|
||||
bool IsOutOfDate();
|
||||
}
|
||||
```
|
||||
|
||||
- **Abstract Base Class**: `DbTimeStampBase`
|
||||
- **Properties**:
|
||||
- `public abstract string LookupTable { get; }`
|
||||
- Name of the database table used to look up the timestamp.
|
||||
- `public abstract ConstraintHelper[] GetConstraints();`
|
||||
- Returns an array of `ConstraintHelper` objects defining the primary key or unique constraints for the record.
|
||||
|
||||
- **Methods**:
|
||||
- `long GetTimeStampMemory()`
|
||||
- Returns the in-memory timestamp (`DbTimeStamp` field).
|
||||
- `void SetTimeStampMemory(long value)`
|
||||
- Sets the in-memory timestamp.
|
||||
- `void SetTimeStampMemory(System.Data.DataRow row)`
|
||||
- Sets in-memory timestamp to `0` (currently unimplemented beyond that).
|
||||
- `void SetTimeStampMemory(System.Data.IDataReader reader)`
|
||||
- Sets in-memory timestamp to `0` (currently unimplemented beyond that).
|
||||
- `long GetTimeStampDb()`
|
||||
- **Currently returns `0`** (implementation is commented out). Intended to fetch the database timestamp for the current record.
|
||||
- `long GetTimeStampDb(Dictionary<string, long> lookup)`
|
||||
- **Currently returns `0`** (implementation is commented out). Intended to fetch timestamp via lookup table.
|
||||
- `Dictionary<string, long> GetAllTimeStampDb()`
|
||||
- **Currently returns an empty dictionary** (implementation is commented out). Intended to fetch all timestamps from the database.
|
||||
- `bool IsNotInDb()`
|
||||
- Returns `true` if `GetTimeStampDb() == 0`.
|
||||
- `bool IsOutOfDate()`
|
||||
- Compares DB and memory timestamps:
|
||||
- Returns `false` if DB timestamp is `0`.
|
||||
- If memory timestamp is `0` and DB is non-zero, sets memory to DB and returns `false`.
|
||||
- Otherwise returns `true` if DB ≠ memory.
|
||||
|
||||
- **Nested Types**:
|
||||
- `ConstraintHelper`:
|
||||
```csharp
|
||||
public class ConstraintHelper
|
||||
{
|
||||
public string ColumnName { get; set; }
|
||||
public System.Data.SqlDbType DbType { get; set; }
|
||||
public object DbValue { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
- **Exception**:
|
||||
- `DbItemOutOfDateException : Exception`
|
||||
- Thrown when an item is detected as out-of-date (not used in current code, but defined).
|
||||
|
||||
### `DbOperations`
|
||||
|
||||
- **Nested Abstract Classes (Table/Field Constants)**:
|
||||
- `Tags`:
|
||||
- `Table = "tblTags"`, `TagFields` enum (`TagId`, `TagText`, `Obsolete`).
|
||||
- `TAGASSIGNMENTS_TABLE = "TagAssignments"`, `TagAssignmentFields`.
|
||||
- `DbVersions`:
|
||||
- `DbVersionFields` enum (`Version`, `Step`, `Date`, `Remarks`, `UserField`).
|
||||
- `Settings`, `Users`, `SensorDB`, `CalculatedChannels`, `LevelTriggers`, `TestSetups`, `TestObjectChannelSettings`, `DigitalOutputSettings`, `Squib`, `MMETables`, `DAS`, `DigitalInputSettings`
|
||||
- All define table names and field enums (e.g., `TestSetups.TestSetupsTable = "tblTestSetups"`).
|
||||
- `DbTypeAttr`:
|
||||
- Custom attribute for mapping enum fields to SQL types (used in reflection via `GetDbType()`).
|
||||
- `CustomChannelFieldSizeAttribute`:
|
||||
- Custom attribute for specifying max field size (e.g., `[CustomChannelFieldSizeAttribute(50)]`).
|
||||
|
||||
- **Static Methods**:
|
||||
- `SqlCommand GetSQLCommand(bool newCommand = false)`
|
||||
- Returns a `SqlCommand` with an open connection (uses `Connection.GetLocalConnectionString()`). Clears parameters.
|
||||
- `void CreateParam(IDbCommand icmd, string name, SqlDbType type, object value)`
|
||||
- Adds a parameter to `icmd`. Special handling for `DateTime` (formats as `"yyyy-MM-dd HH:mm:ss"`).
|
||||
- `DataSet QueryDataSet(IDbCommand icmd)`
|
||||
- Executes `icmd` and returns results as `DataSet`. Supports both SQL Server (`_usingMSSQL == true`) and SQLite (fallback).
|
||||
- `int ExecuteCommand(IDbCommand icmd)`
|
||||
- Executes `icmd` (non-query) and returns affected rows. Supports both SQL Server and SQLite.
|
||||
- `IDbCommand GetISOCommand()`
|
||||
- Returns a new `SqlCommand` connected to the ISO database.
|
||||
- `IDbCommand GetCommand()`
|
||||
- Returns a new `SqlCommand` or `SQLiteCommand` depending on `_usingMSSQL`.
|
||||
|
||||
- **Static Properties**:
|
||||
- `bool _usingCentralizedDB`, `_usingMSSQL`, `_usingNTLMAuthentication`, `_previousDir`
|
||||
- `DbOperations Connection { get; }`
|
||||
- Singleton instance of `DbOperations`.
|
||||
- `bool LastConnectionStatus { get; set; }`
|
||||
- Tracks last connection success/failure.
|
||||
- `ConnectionStatusChangedDelegate ConnectionStatusChanged { get; set; }`
|
||||
- Event for connection status changes.
|
||||
|
||||
- **Instance Properties**:
|
||||
- `string Server`, `DBName`, `Username`, `Password`
|
||||
- Connection configuration.
|
||||
- `string GetLocalConnectionString()`, `GetLocalISOConnectionString()`
|
||||
- Builds connection strings based on auth mode and settings.
|
||||
|
||||
---
|
||||
|
||||
## 3. Invariants
|
||||
|
||||
- **`DbVersion`**:
|
||||
- All fields (`Version`, `Step`, `Date`, `Remarks`, `UserField`) are required in the source `DataRow`; nulls or missing columns will cause `InvalidCastException` or `NullReferenceException`.
|
||||
- `Date` is parsed via `Convert.ToDateTime`, so culture-sensitive formatting may cause failures.
|
||||
|
||||
- **`DbTimeStampBase`**:
|
||||
- `LookupTable` and `GetConstraints()` must be implemented by subclasses; otherwise, runtime errors occur.
|
||||
- `GetTimeStampDb()` and `GetAllTimeStampDb()` currently **always return `0` or empty**, indicating incomplete implementation. No functional timestamp comparison occurs.
|
||||
- `IsNotInDb()` and `IsOutOfDate()` rely on `GetTimeStampDb()` returning `0` for missing records—currently true by design (but not correctness, since `GetTimeStampDb()` is unimplemented).
|
||||
- `SetTimeStampMemory(DataRow)` and `SetTimeStampMemory(IDataReader)` do **not** populate `DbTimeStamp`; they unconditionally set it to `0`.
|
||||
|
||||
- **`DbOperations`**:
|
||||
- `_usingMSSQL` and `_usingCentralizedDB` control runtime behavior (e.g., which DB provider is used). Changing them mid-execution may cause inconsistent behavior.
|
||||
- `GetLocalConnectionString()` throws `Exception("db connection not initialized")` if `Server` is `null`.
|
||||
- `QueryDataSet` and `ExecuteCommand` throw `SystemException` with message `"NoConnection"` on connection failure.
|
||||
- `CreateParam` for `DateTime` normalizes to `"yyyy-MM-dd HH:mm:ss"` format—potentially losing precision.
|
||||
|
||||
---
|
||||
|
||||
## 4. Dependencies
|
||||
|
||||
### This Module Depends On:
|
||||
- **`System.Data`** (ADO.NET): `DataRow`, `DataSet`, `SqlDataAdapter`, `SqlCommand`, `SqlDbType`, `SqlDataReader`, `SqlException`, `ConnectionState`.
|
||||
- **`System.Data.SqlClient`**: For SQL Server connectivity.
|
||||
- **`System.Data.SQLite`**: For SQLite fallback (used when `_usingMSSQL == false`).
|
||||
- **`System.ComponentModel`**: `INotifyPropertyChanged` (used by `DbTimeStampBase`).
|
||||
- **`System.Reflection`**: Used in `DbTypeAttr.GetDbType()`.
|
||||
|
||||
### This Module Is Used By:
|
||||
- Other modules in `DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/` (inferred from namespace).
|
||||
- Likely consumed by migration scripts, export utilities, or data sync components that need to:
|
||||
- Track DB version (`DbVersion`).
|
||||
- Synchronize state with DB via timestamps (`DbTimeStampAware`).
|
||||
- Access table/field metadata (`DbOperations.Tags`, `DbOperations.TestSetups`, etc.).
|
||||
|
||||
---
|
||||
|
||||
## 5. Gotchas
|
||||
|
||||
- **`GetTimeStampDb()` and `GetAllTimeStampDb()` are stubbed**:
|
||||
All timestamp-related logic is non-functional. The implementations are commented out, so `IsOutOfDate()` and `IsNotInDb()` will always behave as if the record is missing or in-memory is authoritative. **Do not rely on timestamp concurrency control in this module.**
|
||||
|
||||
- **`SetTimeStampMemory(DataRow)` and `SetTimeStampMemory(IDataReader)` are no-ops**:
|
||||
They set `DbTimeStamp = 0` regardless of input—likely placeholder code.
|
||||
|
||||
- **`DbOperations.Connection` is a singleton but mutable**:
|
||||
`Connection.Server`, `DBName`, etc., can be set externally, potentially causing race conditions if accessed concurrently.
|
||||
|
||||
- **`CreateParam` for `DateTime` truncates precision**:
|
||||
Converts `DateTime` to `"yyyy-MM-dd HH:mm:ss"` (no milliseconds), risking data loss.
|
||||
|
||||
- **`DbVersion` constructor lacks null/invalid column checks**:
|
||||
Assumes `dr["Version"]`, `dr["Step"]`, etc., exist and are non-null. Will throw on schema mismatches.
|
||||
|
||||
- **`MMETables` field name inconsistencies**:
|
||||
Notes that `"MyType"` → `"CustomChannelType"` → `"TYPE"` and `"Id"` → `"ID"` were used across versions. Code using these must handle historical schema differences.
|
||||
|
||||
- **`DbOperations.QueryDataSet` and `ExecuteCommand` have duplicated logic for SQL Server/SQLite**:
|
||||
Code paths for both providers are interleaved, increasing maintenance risk. SQLite fallback uses `_previousDir` and `"db/datapro.db"`.
|
||||
|
||||
- **No error handling in `GetTimeStampDb`/`GetAllTimeStampDb` stubs**:
|
||||
The commented-out code had `try/catch` blocks and logging (`APILogger.Log(ex)`), but the active code silently returns `0`.
|
||||
|
||||
- **`DbOperations.Connection` uses `GetLocalConnectionString()` which is not thread-safe outside the `lock`**:
|
||||
While the singleton initialization is locked, `GetLocalConnectionString()` itself is not re-entrant safe (though `lock(dbLock)` is used internally).
|
||||
|
||||
- **`_usingMSSQL` and `_usingNTLMAuthentication` are static flags**:
|
||||
Changing them after `Connection` is instantiated may not affect existing connections.
|
||||
|
||||
- **`DbItemOutOfDateException` is defined but never thrown**:
|
||||
Its purpose is unclear; no usage found in the provided files.
|
||||
|
||||
---
|
||||
|
||||
*End of Documentation*
|
||||
Reference in New Issue
Block a user