DP44/docs/ai/DataPRO/Modules/Database/DatabaseMigrator.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/Modules/Database/DatabaseMigrator/MigrateDatabase.cs DataPRO/Modules/Database/DatabaseMigrator/MigrationForm.Designer.cs DataPRO/Modules/Database/DatabaseMigrator/MigrationForm.cs	2026-04-17T15:55:24.798276+00:00	zai-org/GLM-5-FP8	1	0f84be859c5d0bf5

DatabaseMigrator Module Documentation

1. Purpose

The DatabaseMigrator module is a Windows Forms application that provides a GUI utility for migrating DataPRO databases between versions. It handles SQL Server Express LocalDB instance management, database backup creation, and version upgrades by orchestrating calls to DbOperations.Connection.UpgradeVersionsIfNeeded. The module exists to allow developers or administrators to upgrade database schemas from older versions (minimum version 61) to the current database version.

---

2. Public Interface

MigrateDatabase (static class)

static void Main(string[] args)

• Entry point for the application. Marked with [STAThread].
• Currently ignores command-line arguments (parsing logic is commented out).
• Sets targetDir to Environment.CurrentDirectory.
• Initializes visual styles and launches MigrationForm.

MigrationForm (class, inherits from Form)

public MigrationForm(string targetDir)

• Constructor accepting the target directory path where database files reside.
• Initializes the form components and stores targetDir in a private readonly field.

Event Handlers (private, wired to UI controls):

• void buttonOK_Click(object sender, EventArgs e) - Initiates the migration process. Queries current database version, validates against desired version, creates a backup via CopyLocalDB(), and calls DbOperations.Connection.UpgradeVersionsIfNeeded(). Displays appropriate warnings if versions match or current version exceeds desired.

• void buttonCancel_Click(object sender, EventArgs e) - Closes the form without performing migration.

• void MigrationForm_Load(object sender, EventArgs e) - Initializes numericUpDownDesiredVersion with minimum 61, maximum DbOperations.CURRENT_DB_VERSION, and default value of current version. Checks for existing local database and populates TbDatabasePath.

• void numericUpDownDesiredVersion_ValueChanged(object sender, EventArgs e) - Updates _desiredDatabaseVersion field from the numeric control.

Helper Methods (private):

• int GetDatabaseVersion(bool usingLocalDatabase) - Retrieves current database version by calling stored procedure sp_DbVersionGet. Returns 0 on failure.

• bool CopyLocalDB() - Creates timestamped backup copies of .mdf and _log.ldf files.

• string InstallDatabase() - Configures SQL LocalDB instance by stopping, deleting, creating, and starting DataPROInstance, then attaches both DataPRO and ISO databases.

• static string ProcessSqlLocalDbCommand(string command) - Executes SQL LocalDB utility commands.

• static string AttachDatabase(string targetDir, string dbName, string sqlDbFileName, string sqlLogFileName) - Attaches a database using sqlcmd.exe via batch file.

• static string GetSqlServerLocalDBPath() - Queries Windows Registry to find the highest installed SQL Server LocalDB version path.

• static string SqlCommandProcessor(string sqlLocalDbExeFileName, string command) - Executes a SQL command-line utility and captures output.

• static string BatchCommandProcessor(string batchFileName, string dbName, string sqlDbFileName, string sqlLogFileName, string fullSqlcmdPath) - Executes a batch file for database operations.

• bool LocalDataExists() - Checks for existence of DataPRO.mdf (SQL LocalDB) or datapro.db (SQLite) files.

---

3. Invariants

• Version bounds: numericUpDownDesiredVersion.Minimum is always 61; numericUpDownDesiredVersion.Maximum is always DbOperations.CURRENT_DB_VERSION.
• Database name: The database name is hardcoded as "DataPRO" throughout the module.
• Form behavior: The form is always TopMost = true and centered on screen (StartPosition = CenterScreen).
• Backup naming: Backup files are named with timestamp format YYYY_MM_DD HH_MM appended before the file extension.
• SQL LocalDB instance name: The instance name is DataPROInstance (from Settings.Default.LocalDbDataPROInstance).
• Migration direction: Migration only proceeds if currentDatabaseVersion < _desiredDatabaseVersion. Equal or greater versions result in user warnings and no migration.

---

4. Dependencies

This module depends on:

• System.Windows.Forms - Windows Forms UI framework
• System.Data.SqlClient - SQL Server database connectivity
• Microsoft.Win32 - Registry access for SQL LocalDB path detection
• DTS.Common.Storage - Contains DbOperations and DbOperationsEnum
• DTS.Common.Enums - Contains MigrationResult enum
• DTS.Common.Utils.Database - Contains GetODBCToolsPath() method
• DatabaseMigrator.Properties.Settings - Application settings for paths, instance names, and message strings

External dependencies (inferred from usage):

• DbOperations.Connection - Must provide UpgradeVersionsIfNeeded(), Server, DBName, DbVersion properties
• DbOperations.CURRENT_DB_VERSION - Constant defining maximum supported version
• DbOperations.GetSQLCommand() - Factory method for SQL commands
• MigrationResult enum with values: OK, ExceptionThrown, WarningAllowStreamingModesWasNotMigrated

---

5. Gotchas

1. Dead code: Command-line argument parsing in Main() is fully commented out. The application always uses Environment.CurrentDirectory regardless of arguments passed.

2. Hardcoded values with "fix this" comments: Multiple locations contain hardcoded values that were intended to be configurable:

   • GetDatabaseVersion(true) - parameter is ignored; true is hardcoded
   • Database name "DataPRO" is hardcoded instead of using tbDBName.Text (commented out)
   • UpgradeVersionsIfNeeded receives hardcoded strings "previousdir", "targetdir", "applicationSettings" with a "fix this" comment

3. SQLite support is incomplete: The code contains commented-out SQLite handling in GetDatabaseVersion() and LocalDataExists(). The localSQLiteDataExists flag is set but never acted upon.

4. Silent failures: GetDatabaseVersion() catches all exceptions and returns 0 without logging or rethrowing. This could mask connectivity or schema issues.

5. Static mutable state: The StringBuilder sb field is static and reused across SqlCommandProcessor and BatchCommandProcessor. While it's cleared before each use, this could cause issues if methods are called concurrently.

6. Commented-out exit codes: Multiple Environment.Exit() calls are commented out after error conditions, meaning errors display a message box but allow the application to continue.

7. Process output handling asymmetry: SqlCommandProcessor and BatchCommandProcessor redirect both stdout and stderr, but only stderr is read asynchronously via OutputHandler, while stdout is read synchronously with ReadToEnd().