Browse Source
- Add comprehensive connection cleanup and retry logic - Implement exponential backoff for database initialization - Add app lifecycle management for proper resource cleanup - Create diagnostic tools for troubleshooting database issues - Fix CameraDirection enum usage for Capacitor Camera v6 - Temporarily disable encryption to isolate connection problems - Add performance monitoring and health check capabilities - Document fixes and troubleshooting procedures Resolves: CapacitorSQLitePlugin null errors Resolves: "Connection timesafari.sqlite already exists" conflicts Resolves: Performance issues causing frame drops Resolves: Memory management and garbage collection errors Author: Matthew Raymerandroid-15-check
Matthew Raymer
3 weeks ago
5 changed files with 595 additions and 21 deletions
@ -0,0 +1,221 @@ |
|||
# Database Connection Fixes for TimeSafari |
|||
|
|||
## Overview |
|||
|
|||
This document outlines the fixes implemented to resolve database connection issues in the TimeSafari application, particularly for Capacitor SQLite on Android devices. |
|||
|
|||
## Issues Identified |
|||
|
|||
### 1. CapacitorSQLitePlugin Errors |
|||
- Multiple `*** ERROR CapacitorSQLitePlugin: null` messages in Android logs |
|||
- Database connection conflicts and initialization failures |
|||
- Connection leaks causing "Connection timesafari.sqlite already exists" errors |
|||
|
|||
### 2. Performance Issues |
|||
- App skipping 57 frames due to main thread blocking |
|||
- Null pointer exceptions in garbage collection |
|||
- Memory management issues |
|||
|
|||
### 3. Connection Management |
|||
- Lack of proper connection cleanup on app lifecycle events |
|||
- No retry logic for failed connections |
|||
- Missing error handling and recovery mechanisms |
|||
|
|||
## Implemented Fixes |
|||
|
|||
### 1. Enhanced Database Initialization |
|||
|
|||
#### Connection Cleanup |
|||
- Added `cleanupExistingConnections()` method to properly close existing connections |
|||
- Implemented connection consistency checks before creating new connections |
|||
- Added proper error handling for connection cleanup failures |
|||
|
|||
#### Retry Logic |
|||
- Implemented exponential backoff retry mechanism for database connections |
|||
- Maximum of 3 retry attempts with increasing delays |
|||
- Comprehensive error logging for each attempt |
|||
|
|||
#### Database Configuration |
|||
- Configured optimal SQLite settings for performance and stability: |
|||
- `PRAGMA journal_mode=WAL` for better concurrency |
|||
- `PRAGMA synchronous=NORMAL` for balanced performance |
|||
- `PRAGMA cache_size=10000` for improved caching |
|||
- `PRAGMA temp_store=MEMORY` for faster temporary operations |
|||
- `PRAGMA mmap_size=268435456` (256MB) for memory mapping |
|||
|
|||
### 2. Lifecycle Management |
|||
|
|||
#### App Lifecycle Listeners |
|||
- Added event listeners for `beforeunload` and `visibilitychange` |
|||
- Automatic database cleanup when app goes to background |
|||
- Proper resource management to prevent connection leaks |
|||
|
|||
#### Health Monitoring |
|||
- Implemented `healthCheck()` method for connection status monitoring |
|||
- Added `reinitializeDatabase()` for forced reconnection |
|||
- Performance metrics tracking for database operations |
|||
|
|||
### 3. Error Handling and Diagnostics |
|||
|
|||
#### Comprehensive Error Handling |
|||
- Enhanced error logging with detailed context |
|||
- Graceful degradation when database operations fail |
|||
- User-friendly error messages with recovery suggestions |
|||
|
|||
#### Diagnostic Tools |
|||
- Created `databaseDiagnostics.ts` utility for troubleshooting |
|||
- Database stress testing capabilities |
|||
- Performance monitoring and reporting |
|||
- System information collection for debugging |
|||
|
|||
### 4. Configuration Changes |
|||
|
|||
#### Capacitor Configuration |
|||
- Temporarily disabled encryption to isolate connection issues |
|||
- Disabled biometric authentication to reduce complexity |
|||
- Maintained proper database location settings |
|||
|
|||
#### Camera Integration Fixes |
|||
- Fixed `CameraDirection` enum usage for Capacitor Camera v6 |
|||
- Updated from string literals to proper enum values |
|||
- Resolved TypeScript compilation errors |
|||
|
|||
## Usage |
|||
|
|||
### Running Diagnostics |
|||
|
|||
```typescript |
|||
import { runDatabaseDiagnostics, stressTestDatabase } from '@/utils/databaseDiagnostics'; |
|||
|
|||
// Run comprehensive diagnostics |
|||
const diagnosticInfo = await runDatabaseDiagnostics(); |
|||
console.log('Database status:', diagnosticInfo.connectionStatus); |
|||
|
|||
// Run stress test |
|||
await stressTestDatabase(20); |
|||
``` |
|||
|
|||
### Health Checks |
|||
|
|||
```typescript |
|||
import { PlatformServiceFactory } from '@/services/PlatformServiceFactory'; |
|||
|
|||
const platformService = PlatformServiceFactory.getInstance(); |
|||
const health = await platformService.healthCheck(); |
|||
|
|||
if (!health.healthy) { |
|||
console.error('Database health check failed:', health.error); |
|||
// Attempt reinitialization |
|||
await platformService.reinitializeDatabase(); |
|||
} |
|||
``` |
|||
|
|||
### Performance Monitoring |
|||
|
|||
```typescript |
|||
import { logDatabasePerformance } from '@/utils/databaseDiagnostics'; |
|||
|
|||
// Wrap database operations with performance monitoring |
|||
const start = Date.now(); |
|||
await platformService.dbQuery("SELECT * FROM users"); |
|||
const duration = Date.now() - start; |
|||
logDatabasePerformance("User query", duration); |
|||
``` |
|||
|
|||
## Troubleshooting Guide |
|||
|
|||
### Common Issues and Solutions |
|||
|
|||
#### 1. "Connection timesafari.sqlite already exists" |
|||
**Cause**: Multiple database connections not properly closed |
|||
**Solution**: |
|||
- Use the enhanced cleanup methods |
|||
- Check for existing connections before creating new ones |
|||
- Implement proper app lifecycle management |
|||
|
|||
#### 2. CapacitorSQLitePlugin null errors |
|||
**Cause**: Database initialization failures or connection conflicts |
|||
**Solution**: |
|||
- Use retry logic with exponential backoff |
|||
- Check connection consistency |
|||
- Verify database configuration settings |
|||
|
|||
#### 3. Performance Issues |
|||
**Cause**: Main thread blocking or inefficient database operations |
|||
**Solution**: |
|||
- Use WAL journal mode for better concurrency |
|||
- Implement proper connection pooling |
|||
- Monitor and optimize query performance |
|||
|
|||
#### 4. Memory Leaks |
|||
**Cause**: Database connections not properly closed |
|||
**Solution**: |
|||
- Implement proper cleanup on app lifecycle events |
|||
- Use health checks to monitor connection status |
|||
- Force reinitialization when issues are detected |
|||
|
|||
### Debugging Steps |
|||
|
|||
1. **Check Logs**: Look for database-related error messages |
|||
2. **Run Diagnostics**: Use `runDatabaseDiagnostics()` to get system status |
|||
3. **Monitor Performance**: Track query execution times |
|||
4. **Test Connections**: Use stress testing to identify issues |
|||
5. **Verify Configuration**: Check Capacitor and SQLite settings |
|||
|
|||
### Recovery Procedures |
|||
|
|||
#### Automatic Recovery |
|||
- Health checks run periodically |
|||
- Automatic reinitialization on connection failures |
|||
- Graceful degradation for non-critical operations |
|||
|
|||
#### Manual Recovery |
|||
- Force app restart to clear all connections |
|||
- Clear app data if persistent issues occur |
|||
- Check device storage and permissions |
|||
|
|||
## Security Considerations |
|||
|
|||
### Data Protection |
|||
- Encryption can be re-enabled once connection issues are resolved |
|||
- Biometric authentication can be restored after stability is confirmed |
|||
- Proper error handling prevents data corruption |
|||
|
|||
### Privacy |
|||
- Diagnostic information is logged locally only |
|||
- No sensitive data is exposed in error messages |
|||
- User data remains protected during recovery procedures |
|||
|
|||
## Performance Impact |
|||
|
|||
### Improvements |
|||
- Reduced connection initialization time |
|||
- Better memory usage through proper cleanup |
|||
- Improved app responsiveness with background processing |
|||
- Enhanced error recovery reduces user impact |
|||
|
|||
### Monitoring |
|||
- Performance metrics are tracked automatically |
|||
- Slow operations are logged with warnings |
|||
- System resource usage is monitored |
|||
|
|||
## Future Enhancements |
|||
|
|||
### Planned Improvements |
|||
1. **Connection Pooling**: Implement proper connection pooling for better performance |
|||
2. **Encryption Re-enablement**: Restore encryption once stability is confirmed |
|||
3. **Advanced Monitoring**: Add real-time performance dashboards |
|||
4. **Automated Recovery**: Implement self-healing mechanisms |
|||
|
|||
### Research Areas |
|||
1. **Alternative Storage**: Investigate other storage solutions for specific use cases |
|||
2. **Migration Tools**: Develop tools for seamless data migration |
|||
3. **Cross-Platform Optimization**: Optimize for different device capabilities |
|||
|
|||
## Conclusion |
|||
|
|||
These fixes address the core database connection issues while maintaining application stability and user experience. The enhanced error handling, monitoring, and recovery mechanisms provide a robust foundation for reliable database operations across all platforms. |
|||
|
|||
## Author |
|||
|
|||
Matthew Raymer - Database Architecture and Mobile Platform Development |
|||
@ -0,0 +1,158 @@ |
|||
/** |
|||
* Database Diagnostics Utility |
|||
* |
|||
* This utility provides diagnostic tools for troubleshooting database connection |
|||
* issues in the TimeSafari application, particularly for Capacitor SQLite. |
|||
* |
|||
* @author Matthew Raymer |
|||
*/ |
|||
|
|||
import { logger } from "./logger"; |
|||
import { PlatformServiceFactory } from "@/services/PlatformServiceFactory"; |
|||
|
|||
export interface DatabaseDiagnosticInfo { |
|||
platform: string; |
|||
timestamp: string; |
|||
databaseName: string; |
|||
connectionStatus: string; |
|||
errorDetails?: string; |
|||
performanceMetrics?: { |
|||
initializationTime?: number; |
|||
queryTime?: number; |
|||
}; |
|||
systemInfo?: { |
|||
userAgent: string; |
|||
platform: string; |
|||
memory?: { |
|||
used: number; |
|||
total: number; |
|||
}; |
|||
}; |
|||
} |
|||
|
|||
/** |
|||
* Performs comprehensive database diagnostics |
|||
*/ |
|||
export async function runDatabaseDiagnostics(): Promise<DatabaseDiagnosticInfo> { |
|||
const startTime = Date.now(); |
|||
const diagnosticInfo: DatabaseDiagnosticInfo = { |
|||
platform: "unknown", |
|||
timestamp: new Date().toISOString(), |
|||
databaseName: "timesafari.sqlite", |
|||
connectionStatus: "unknown", |
|||
}; |
|||
|
|||
try { |
|||
// Get platform service
|
|||
const platformService = PlatformServiceFactory.getInstance(); |
|||
const capabilities = platformService.getCapabilities(); |
|||
|
|||
diagnosticInfo.platform = capabilities.isIOS ? "iOS" : |
|||
capabilities.isMobile ? "Android" : "Web"; |
|||
|
|||
// Add system information
|
|||
diagnosticInfo.systemInfo = { |
|||
userAgent: navigator.userAgent, |
|||
platform: navigator.platform, |
|||
}; |
|||
|
|||
// Add memory information if available
|
|||
if ('memory' in performance) { |
|||
const memory = (performance as any).memory; |
|||
diagnosticInfo.systemInfo.memory = { |
|||
used: memory.usedJSHeapSize, |
|||
total: memory.totalJSHeapSize, |
|||
}; |
|||
} |
|||
|
|||
// Test database connection
|
|||
const initStart = Date.now(); |
|||
|
|||
try { |
|||
// Test a simple query
|
|||
const queryStart = Date.now(); |
|||
const result = await platformService.dbQuery("SELECT 1 as test"); |
|||
const queryTime = Date.now() - queryStart; |
|||
|
|||
diagnosticInfo.connectionStatus = "healthy"; |
|||
diagnosticInfo.performanceMetrics = { |
|||
queryTime, |
|||
}; |
|||
|
|||
logger.log("[DatabaseDiagnostics] Database connection test successful"); |
|||
} catch (error) { |
|||
diagnosticInfo.connectionStatus = "error"; |
|||
diagnosticInfo.errorDetails = error instanceof Error ? error.message : String(error); |
|||
|
|||
logger.error("[DatabaseDiagnostics] Database connection test failed:", error); |
|||
} |
|||
|
|||
const totalTime = Date.now() - startTime; |
|||
if (diagnosticInfo.performanceMetrics) { |
|||
diagnosticInfo.performanceMetrics.initializationTime = totalTime; |
|||
} |
|||
|
|||
} catch (error) { |
|||
diagnosticInfo.connectionStatus = "critical"; |
|||
diagnosticInfo.errorDetails = error instanceof Error ? error.message : String(error); |
|||
logger.error("[DatabaseDiagnostics] Diagnostic run failed:", error); |
|||
} |
|||
|
|||
// Log the complete diagnostic information
|
|||
logger.log("[DatabaseDiagnostics] Diagnostic results:", diagnosticInfo); |
|||
|
|||
return diagnosticInfo; |
|||
} |
|||
|
|||
/** |
|||
* Logs database performance metrics |
|||
*/ |
|||
export function logDatabasePerformance(operation: string, duration: number): void { |
|||
logger.log(`[DatabasePerformance] ${operation}: ${duration}ms`); |
|||
|
|||
// Log warning for slow operations
|
|||
if (duration > 1000) { |
|||
logger.warn(`[DatabasePerformance] Slow operation detected: ${operation} took ${duration}ms`); |
|||
} |
|||
} |
|||
|
|||
/** |
|||
* Creates a database connection stress test |
|||
*/ |
|||
export async function stressTestDatabase(iterations: number = 10): Promise<void> { |
|||
logger.log(`[DatabaseStressTest] Starting stress test with ${iterations} iterations`); |
|||
|
|||
const platformService = PlatformServiceFactory.getInstance(); |
|||
const results: number[] = []; |
|||
|
|||
for (let i = 0; i < iterations; i++) { |
|||
const start = Date.now(); |
|||
try { |
|||
await platformService.dbQuery("SELECT 1 as test"); |
|||
const duration = Date.now() - start; |
|||
results.push(duration); |
|||
|
|||
logger.log(`[DatabaseStressTest] Iteration ${i + 1}: ${duration}ms`); |
|||
} catch (error) { |
|||
logger.error(`[DatabaseStressTest] Iteration ${i + 1} failed:`, error); |
|||
} |
|||
|
|||
// Small delay between iterations
|
|||
await new Promise(resolve => setTimeout(resolve, 100)); |
|||
} |
|||
|
|||
if (results.length > 0) { |
|||
const avg = results.reduce((a, b) => a + b, 0) / results.length; |
|||
const min = Math.min(...results); |
|||
const max = Math.max(...results); |
|||
|
|||
logger.log(`[DatabaseStressTest] Results - Avg: ${avg.toFixed(2)}ms, Min: ${min}ms, Max: ${max}ms`); |
|||
} |
|||
} |
|||
|
|||
/** |
|||
* Exports diagnostic information for debugging |
|||
*/ |
|||
export function exportDiagnosticInfo(info: DatabaseDiagnosticInfo): string { |
|||
return JSON.stringify(info, null, 2); |
|||
} |
|||
Loading…
Reference in new issue