crowd-funder-for-time-pwa/.cursor/rules/SQLITE.mdc

---
description: 
globs: 
alwaysApply: true
---
# @capacitor-community/sqlite MDC Ruleset

## Project Overview
This ruleset is for the `@capacitor-community/sqlite` plugin, a Capacitor community plugin that provides native and Electron SQLite database functionality with encryption support.

## Key Features
- Native SQLite database support for iOS, Android, and Electron
- Database encryption support using SQLCipher (Native) and better-sqlite3-multiple-ciphers (Electron)
- Biometric authentication support
- Cross-platform database operations
- JSON import/export capabilities
- Database migration support
- Sync table functionality

## Platform Support Matrix

### Core Database Operations
| Operation | Android | iOS | Electron | Web |
|-----------|---------|-----|----------|-----|
| Create Connection (RW) | ✅ | ✅ | ✅ | ✅ |
| Create Connection (RO) | ✅ | ✅ | ✅ | ❌ |
| Open DB (non-encrypted) | ✅ | ✅ | ✅ | ✅ |
| Open DB (encrypted) | ✅ | ✅ | ✅ | ❌ |
| Execute/Query | ✅ | ✅ | ✅ | ✅ |
| Import/Export JSON | ✅ | ✅ | ✅ | ✅ |

### Security Features
| Feature | Android | iOS | Electron | Web |
|---------|---------|-----|----------|-----|
| Encryption | ✅ | ✅ | ✅ | ❌ |
| Biometric Auth | ✅ | ✅ | ✅ | ❌ |
| Secret Management | ✅ | ✅ | ✅ | ❌ |

## Configuration Requirements

### Base Configuration
```typescript
// capacitor.config.ts
{
  plugins: {
    CapacitorSQLite: {
      iosDatabaseLocation: 'Library/CapacitorDatabase',
      iosIsEncryption: true,
      iosKeychainPrefix: 'your-app-prefix',
      androidIsEncryption: true,
      electronIsEncryption: true
    }
  }
}
```

### Platform-Specific Requirements

#### Android
- Minimum SDK: 23
- Target SDK: 35
- Required Gradle JDK: 21
- Required Android Gradle Plugin: 8.7.2
- Required manifest settings for backup prevention
- Required data extraction rules

#### iOS
- No additional configuration needed beyond base setup
- Supports biometric authentication
- Uses keychain for encryption

#### Electron
Required dependencies:
```json
{
  "dependencies": {
    "better-sqlite3-multiple-ciphers": "latest",
    "electron-json-storage": "latest",
    "jszip": "latest",
    "node-fetch": "2.6.7",
    "crypto": "latest",
    "crypto-js": "latest"
  }
}
```

#### Web
- Requires `sql.js` and `jeep-sqlite`
- Manual copy of `sql-wasm.wasm` to assets folder
- Framework-specific asset placement:
  - Angular: `src/assets/`
  - Vue/React: `public/assets/`

## Best Practices

### Database Operations
1. Always close connections after use
2. Use transactions for multiple operations
3. Implement proper error handling
4. Use prepared statements for queries
5. Implement proper database versioning

### Security
1. Always use encryption for sensitive data
2. Implement proper secret management
3. Use biometric authentication when available
4. Follow platform-specific security guidelines

### Performance
1. Use appropriate indexes
2. Implement connection pooling
3. Use transactions for bulk operations
4. Implement proper database cleanup

## Common Issues and Solutions

### Android
- Build data properties conflict: Add to `app/build.gradle`:
  ```gradle
  packagingOptions {
      exclude 'build-data.properties'
  }
  ```

### Electron
- Node-fetch version must be ≤2.6.7
- For Capacitor Electron v5:
  - Use Electron@25.8.4
  - Add `"skipLibCheck": true` to tsconfig.json

### Web
- Ensure proper WASM file placement
- Handle browser compatibility
- Implement proper fallbacks

## Version Compatibility
- Requires Node.js ≥16.0.0
- Compatible with Capacitor ≥7.0.0
- Supports TypeScript 4.1.5+

## Testing Requirements
- Unit tests for database operations
- Platform-specific integration tests
- Encryption/decryption tests
- Biometric authentication tests
- Migration tests
- Sync functionality tests

## Documentation
- API Documentation: `/docs/API.md`
- Connection API: `/docs/APIConnection.md`
- DB Connection API: `/docs/APIDBConnection.md`
- Release Notes: `/docs/info_releases.md`
- Changelog: `CHANGELOG.md`

## Contributing Guidelines
- Follow Ionic coding standards
- Use provided linting and formatting tools
- Maintain platform compatibility
- Update documentation
- Add appropriate tests
- Follow semantic versioning

## Maintenance
- Regular security updates
- Platform compatibility checks
- Performance optimization
- Documentation updates
- Dependency updates

## License
MIT License - See LICENSE file for details