docs: Add comprehensive documentation to migration system modules
- Add detailed file-level documentation with architecture overview and usage examples - Document all interfaces, classes, and methods with JSDoc comments - Include migration philosophy, best practices, and schema evolution guidelines - Add extensive inline documentation for database schema and table purposes - Document privacy and security considerations in database design - Provide troubleshooting guidance and logging explanations - Add template and examples for future migration development - Include platform-specific documentation for Capacitor SQLite integration - Document validation and integrity checking processes with detailed steps The migration system is now thoroughly documented for maintainability and onboarding of new developers to the codebase.
This commit is contained in:
Matthew Raymer
@@ -237,28 +237,107 @@ export class CapacitorPlatformService implements PlatformService {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute database migrations for the Capacitor platform
|
||||
*
|
||||
* This method orchestrates the database migration process specifically for
|
||||
* Capacitor-based platforms (mobile and Electron). It provides the platform-specific
|
||||
* SQL execution functions to the migration service and handles Capacitor SQLite
|
||||
* plugin integration.
|
||||
*
|
||||
* ## Migration Process:
|
||||
*
|
||||
* 1. **SQL Execution Setup**: Creates platform-specific SQL execution functions
|
||||
* that properly handle the Capacitor SQLite plugin's API
|
||||
*
|
||||
* 2. **Parameter Handling**: Ensures proper parameter binding for prepared statements
|
||||
* using the correct Capacitor SQLite methods (run vs execute)
|
||||
*
|
||||
* 3. **Result Parsing**: Provides extraction functions that understand the
|
||||
* Capacitor SQLite result format
|
||||
*
|
||||
* 4. **Migration Execution**: Delegates to the migration service for the actual
|
||||
* migration logic and tracking
|
||||
*
|
||||
* 5. **Integrity Verification**: Runs post-migration integrity checks to ensure
|
||||
* the database is in the expected state
|
||||
*
|
||||
* ## Error Handling:
|
||||
*
|
||||
* The method includes comprehensive error handling for:
|
||||
* - Database connection issues
|
||||
* - SQL execution failures
|
||||
* - Migration tracking problems
|
||||
* - Schema validation errors
|
||||
*
|
||||
* Even if migrations fail, the integrity check still runs to assess the
|
||||
* current database state and provide debugging information.
|
||||
*
|
||||
* ## Logging:
|
||||
*
|
||||
* Detailed logging is provided throughout the process using emoji-tagged
|
||||
* console messages that appear in the Electron DevTools console. This
|
||||
* includes:
|
||||
* - SQL statement execution details
|
||||
* - Parameter values for debugging
|
||||
* - Migration success/failure status
|
||||
* - Database integrity check results
|
||||
*
|
||||
* @throws {Error} If database is not initialized or migrations fail critically
|
||||
* @private Internal method called during database initialization
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // Called automatically during platform service initialization
|
||||
* await this.runCapacitorMigrations();
|
||||
* ```
|
||||
*/
|
||||
private async runCapacitorMigrations(): Promise<void> {
|
||||
if (!this.db) {
|
||||
throw new Error("Database not initialized");
|
||||
}
|
||||
|
||||
/**
|
||||
* SQL execution function for Capacitor SQLite plugin
|
||||
*
|
||||
* This function handles the execution of SQL statements (INSERT, UPDATE, CREATE, etc.)
|
||||
* through the Capacitor SQLite plugin. It automatically chooses the appropriate
|
||||
* method based on whether parameters are provided.
|
||||
*
|
||||
* @param sql - SQL statement to execute
|
||||
* @param params - Optional parameters for prepared statements
|
||||
* @returns Promise resolving to execution results
|
||||
*/
|
||||
const sqlExec = async (sql: string, params?: unknown[]): Promise<capSQLiteChanges> => {
|
||||
console.log(`🔧 [CapacitorMigration] Executing SQL:`, sql);
|
||||
console.log(`📋 [CapacitorMigration] With params:`, params);
|
||||
|
||||
if (params && params.length > 0) {
|
||||
// Use run method for parameterized queries
|
||||
// Use run method for parameterized queries (prepared statements)
|
||||
// This is essential for proper parameter binding and SQL injection prevention
|
||||
const result = await this.db!.run(sql, params);
|
||||
console.log(`✅ [CapacitorMigration] Run result:`, result);
|
||||
return result;
|
||||
} else {
|
||||
// Use execute method for non-parameterized queries
|
||||
// This is more efficient for simple DDL statements
|
||||
const result = await this.db!.execute(sql);
|
||||
console.log(`✅ [CapacitorMigration] Execute result:`, result);
|
||||
return result;
|
||||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* SQL query function for Capacitor SQLite plugin
|
||||
*
|
||||
* This function handles the execution of SQL queries (SELECT statements)
|
||||
* through the Capacitor SQLite plugin. It returns the raw result data
|
||||
* that can be processed by the migration service.
|
||||
*
|
||||
* @param sql - SQL query to execute
|
||||
* @param params - Optional parameters for prepared statements
|
||||
* @returns Promise resolving to query results
|
||||
*/
|
||||
const sqlQuery = async (sql: string, params?: unknown[]): Promise<DBSQLiteValues> => {
|
||||
console.log(`🔍 [CapacitorMigration] Querying SQL:`, sql);
|
||||
console.log(`📋 [CapacitorMigration] With params:`, params);
|
||||
@@ -268,6 +347,24 @@ export class CapacitorPlatformService implements PlatformService {
|
||||
return result;
|
||||
};
|
||||
|
||||
/**
|
||||
* Extract migration names from Capacitor SQLite query results
|
||||
*
|
||||
* This function parses the result format returned by the Capacitor SQLite
|
||||
* plugin and extracts migration names. It handles the specific data structure
|
||||
* used by the plugin, which can vary between different result formats.
|
||||
*
|
||||
* ## Result Format Handling:
|
||||
*
|
||||
* The Capacitor SQLite plugin can return results in different formats:
|
||||
* - Object format: `{ name: "migration_name" }`
|
||||
* - Array format: `["migration_name", "timestamp"]`
|
||||
*
|
||||
* This function handles both formats to ensure robust migration name extraction.
|
||||
*
|
||||
* @param result - Query result from Capacitor SQLite plugin
|
||||
* @returns Set of migration names found in the result
|
||||
*/
|
||||
const extractMigrationNames = (result: DBSQLiteValues): Set<string> => {
|
||||
console.log(`🔍 [CapacitorMigration] Extracting migration names from:`, result);
|
||||
|
||||
@@ -287,13 +384,14 @@ export class CapacitorPlatformService implements PlatformService {
|
||||
};
|
||||
|
||||
try {
|
||||
// Execute the migration process
|
||||
await runMigrations(sqlExec, sqlQuery, extractMigrationNames);
|
||||
|
||||
// After migrations, run integrity check
|
||||
// After migrations, run integrity check to verify database state
|
||||
await this.verifyDatabaseIntegrity();
|
||||
} catch (error) {
|
||||
console.error(`❌ [CapacitorMigration] Migration failed:`, error);
|
||||
// Still try to verify what we have
|
||||
// Still try to verify what we have for debugging purposes
|
||||
await this.verifyDatabaseIntegrity();
|
||||
throw error;
|
||||
}
|
||||
@@ -301,6 +399,55 @@ export class CapacitorPlatformService implements PlatformService {
|
||||
|
||||
/**
|
||||
* Verify database integrity and migration status
|
||||
*
|
||||
* This method performs comprehensive validation of the database structure
|
||||
* and migration state. It's designed to help identify issues with the
|
||||
* migration process and provide detailed debugging information.
|
||||
*
|
||||
* ## Validation Steps:
|
||||
*
|
||||
* 1. **Migration Records**: Checks which migrations are recorded as applied
|
||||
* 2. **Table Existence**: Verifies all expected core tables exist
|
||||
* 3. **Schema Validation**: Checks table schemas including column presence
|
||||
* 4. **Data Integrity**: Validates basic data counts and structure
|
||||
*
|
||||
* ## Core Tables Validated:
|
||||
*
|
||||
* - `accounts`: User identity and cryptographic keys
|
||||
* - `secret`: Application secrets and encryption keys
|
||||
* - `settings`: Configuration and user preferences
|
||||
* - `contacts`: Contact network and trust relationships
|
||||
* - `logs`: Application event logging
|
||||
* - `temp`: Temporary data storage
|
||||
*
|
||||
* ## Schema Checks:
|
||||
*
|
||||
* For critical tables like `contacts`, the method validates:
|
||||
* - Table structure using `PRAGMA table_info`
|
||||
* - Presence of important columns (e.g., `iViewContent`)
|
||||
* - Column data types and constraints
|
||||
*
|
||||
* ## Error Handling:
|
||||
*
|
||||
* This method is designed to never throw errors - it captures and logs
|
||||
* all validation issues for debugging purposes. This ensures that even
|
||||
* if integrity checks fail, they don't prevent the application from starting.
|
||||
*
|
||||
* ## Logging Output:
|
||||
*
|
||||
* The method produces detailed console output with emoji tags:
|
||||
* - `✅` for successful validations
|
||||
* - `❌` for validation failures
|
||||
* - `📊` for data summaries
|
||||
* - `🔍` for investigation steps
|
||||
*
|
||||
* @private Internal method called after migrations
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // Called automatically after migration completion
|
||||
* await this.verifyDatabaseIntegrity();
|
||||
* ```
|
||||
*/
|
||||
private async verifyDatabaseIntegrity(): Promise<void> {
|
||||
if (!this.db) {
|
||||
@@ -311,11 +458,11 @@ export class CapacitorPlatformService implements PlatformService {
|
||||
console.log(`🔍 [DB-Integrity] Starting database integrity check...`);
|
||||
|
||||
try {
|
||||
// Check migrations table
|
||||
// Step 1: Check migrations table and applied migrations
|
||||
const migrationsResult = await this.db.query("SELECT name, applied_at FROM migrations ORDER BY applied_at");
|
||||
console.log(`📊 [DB-Integrity] Applied migrations:`, migrationsResult);
|
||||
|
||||
// Check core tables exist
|
||||
// Step 2: Verify core tables exist
|
||||
const coreTableNames = ['accounts', 'secret', 'settings', 'contacts', 'logs', 'temp'];
|
||||
const existingTables: string[] = [];
|
||||
|
||||
@@ -333,12 +480,13 @@ export class CapacitorPlatformService implements PlatformService {
|
||||
}
|
||||
}
|
||||
|
||||
// Check contacts table schema (including iViewContent column)
|
||||
// Step 3: Check contacts table schema (including iViewContent column)
|
||||
if (existingTables.includes('contacts')) {
|
||||
try {
|
||||
const contactsSchema = await this.db.query("PRAGMA table_info(contacts)");
|
||||
console.log(`📊 [DB-Integrity] Contacts table schema:`, contactsSchema);
|
||||
|
||||
// Check for iViewContent column specifically
|
||||
const hasIViewContent = contactsSchema.values?.some((col: any) =>
|
||||
(col.name === 'iViewContent') || (Array.isArray(col) && col[1] === 'iViewContent')
|
||||
);
|
||||
@@ -353,7 +501,7 @@ export class CapacitorPlatformService implements PlatformService {
|
||||
}
|
||||
}
|
||||
|
||||
// Check for data integrity
|
||||
// Step 4: Check for basic data integrity
|
||||
try {
|
||||
const accountCount = await this.db.query("SELECT COUNT(*) as count FROM accounts");
|
||||
const settingsCount = await this.db.query("SELECT COUNT(*) as count FROM settings");
|
||||
|
||||
Reference in New Issue
Block a user