mirror of
https://github.com/wekan/wekan.git
synced 2026-01-15 14:08:51 +01:00
Add support for MongoDB 3-8, detecting which one is in use.
Thanks to xet7 !
This commit is contained in:
Lauri Ojansivu
parent
1f5a549589
commit
74ccfea570
11 changed files with 1650 additions and 7 deletions
318
docs/Databases/MongoDB-Compatibility-Guide.md
Normal file
318
docs/Databases/MongoDB-Compatibility-Guide.md
Normal file
|
|
@ -0,0 +1,318 @@
|
|||
# MongoDB Compatibility Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This guide documents MongoDB compatibility issues and fixes for Wekan across MongoDB versions 3.0 through 8.0, ensuring proper operation with Meteor.js 2.14.
|
||||
|
||||
## Current Status
|
||||
|
||||
- **Meteor.js Version**: 2.14
|
||||
- **MongoDB Package**: mongo@1.16.8
|
||||
- **Supported MongoDB Versions**: 3.0 - 8.0
|
||||
- **Compatibility Status**: ✅ Fixed
|
||||
|
||||
## Compatibility Issues Fixed
|
||||
|
||||
### 1. Deprecated `.count()` Method
|
||||
|
||||
**Issue**: The `.count()` method is deprecated in newer MongoDB versions.
|
||||
|
||||
**Fixed Files**:
|
||||
- `models/users.js` - Line 1839
|
||||
- `server/migrations.js` - Line 209
|
||||
- `server/publications/cards.js` - Lines 709, 711, 713
|
||||
- `client/components/settings/adminReports.js` - Line 115
|
||||
|
||||
**Fix Applied**:
|
||||
```javascript
|
||||
// Before (deprecated)
|
||||
const count = collection.find().count();
|
||||
|
||||
// After (compatible)
|
||||
const count = collection.find().countDocuments();
|
||||
```
|
||||
|
||||
### 2. MongoDB 8.0 Null/Undefined Equality
|
||||
|
||||
**Issue**: MongoDB 8.0 changed behavior where equality matches to `null` no longer match `undefined` values.
|
||||
|
||||
**Fixed Files**:
|
||||
- `models/customFields.js` - Custom field initialization
|
||||
- `models/cards.js` - Card custom field initialization
|
||||
|
||||
**Fix Applied**:
|
||||
```javascript
|
||||
// Before (MongoDB 8.0 incompatible)
|
||||
{ field: null }
|
||||
|
||||
// After (MongoDB 8.0 compatible)
|
||||
{ field: { $in: [null, undefined] } }
|
||||
```
|
||||
|
||||
## Direct Operations Analysis
|
||||
|
||||
### Purpose of Direct Operations
|
||||
|
||||
Direct operations (`.direct.insert()`, `.direct.update()`, `.direct.remove()`) are used intentionally in Wekan to:
|
||||
|
||||
1. **Bypass Meteor Security**: For system operations that need to bypass validation
|
||||
2. **Migration Scripts**: For data migration operations
|
||||
3. **Import/Export**: For bulk data operations
|
||||
4. **System Initialization**: For setting up initial data
|
||||
|
||||
### Files Using Direct Operations
|
||||
|
||||
**Models**:
|
||||
- `models/wekanCreator.js` - Wekan board creation
|
||||
- `models/trelloCreator.js` - Trello import
|
||||
- `models/cards.js` - Card operations
|
||||
- `models/boards.js` - Board operations
|
||||
- `models/lists.js` - List operations
|
||||
- `models/swimlanes.js` - Swimlane operations
|
||||
- `models/customFields.js` - Custom field operations
|
||||
- `models/checklistItems.js` - Checklist operations
|
||||
- `models/integrations.js` - Integration operations
|
||||
- `models/csvCreator.js` - CSV export operations
|
||||
|
||||
**Server**:
|
||||
- `server/migrations.js` - Database migrations
|
||||
- `server/notifications/outgoing.js` - Notification operations
|
||||
|
||||
### Security Considerations
|
||||
|
||||
Direct operations bypass Meteor's security model, so they should only be used when:
|
||||
- ✅ System-level operations (migrations, imports)
|
||||
- ✅ Bulk operations that need performance
|
||||
- ✅ Operations that need to bypass validation
|
||||
- ❌ User-initiated operations (use regular methods)
|
||||
- ❌ Operations that need security validation
|
||||
|
||||
## Raw Collection Usage
|
||||
|
||||
### Purpose of Raw Collections
|
||||
|
||||
Raw collections (`.rawCollection()`) are used for:
|
||||
1. **Advanced Aggregation**: Complex aggregation pipelines
|
||||
2. **Database Commands**: Direct database commands
|
||||
3. **Index Management**: Creating/dropping indexes
|
||||
4. **Migration Operations**: Complex data transformations
|
||||
|
||||
### Files Using Raw Collections
|
||||
|
||||
- `models/server/metrics.js` - Metrics aggregation
|
||||
- `server/migrations.js` - Migration operations
|
||||
|
||||
### Security Considerations
|
||||
|
||||
Raw collections bypass all Meteor security, so they should only be used when:
|
||||
- ✅ Server-side only operations
|
||||
- ✅ System administration tasks
|
||||
- ✅ Complex aggregation pipelines
|
||||
- ❌ Client-side operations
|
||||
- ❌ User data operations without validation
|
||||
|
||||
## Version-Specific Compatibility
|
||||
|
||||
### MongoDB 3.0 - 3.6
|
||||
- ✅ Full compatibility
|
||||
- ✅ Uses mongodb3legacy driver
|
||||
- ✅ All operations supported
|
||||
|
||||
### MongoDB 4.0 - 4.4
|
||||
- ✅ Full compatibility
|
||||
- ✅ Uses mongodb4legacy driver
|
||||
- ✅ All operations supported
|
||||
|
||||
### MongoDB 5.0
|
||||
- ✅ Full compatibility
|
||||
- ✅ Uses mongodb5legacy driver
|
||||
- ✅ All operations supported
|
||||
|
||||
### MongoDB 6.0
|
||||
- ✅ Full compatibility
|
||||
- ✅ Uses mongodb6legacy driver
|
||||
- ✅ All operations supported
|
||||
|
||||
### MongoDB 7.0
|
||||
- ✅ Full compatibility
|
||||
- ✅ Uses mongodb7legacy driver
|
||||
- ✅ All operations supported
|
||||
|
||||
### MongoDB 8.0
|
||||
- ✅ Full compatibility (after fixes)
|
||||
- ✅ Uses mongodb8legacy driver
|
||||
- ✅ Null/undefined equality fixed
|
||||
|
||||
## Testing Recommendations
|
||||
|
||||
### Test Matrix
|
||||
|
||||
| MongoDB Version | Driver | Status | Test Priority |
|
||||
|----------------|--------|--------|---------------|
|
||||
| 3.0 | mongodb3legacy | ✅ Compatible | High |
|
||||
| 3.2 | mongodb3legacy | ✅ Compatible | High |
|
||||
| 3.4 | mongodb3legacy | ✅ Compatible | High |
|
||||
| 3.6 | mongodb3legacy | ✅ Compatible | High |
|
||||
| 4.0 | mongodb4legacy | ✅ Compatible | High |
|
||||
| 4.2 | mongodb4legacy | ✅ Compatible | High |
|
||||
| 4.4 | mongodb4legacy | ✅ Compatible | High |
|
||||
| 5.0 | mongodb5legacy | ✅ Compatible | Medium |
|
||||
| 6.0 | mongodb6legacy | ✅ Compatible | Medium |
|
||||
| 7.0 | mongodb7legacy | ✅ Compatible | Medium |
|
||||
| 8.0 | mongodb8legacy | ✅ Compatible | High |
|
||||
|
||||
### Test Scenarios
|
||||
|
||||
1. **Basic Operations**:
|
||||
- Create/Read/Update/Delete operations
|
||||
- Collection queries and filters
|
||||
- Index operations
|
||||
|
||||
2. **Advanced Operations**:
|
||||
- Aggregation pipelines
|
||||
- Complex queries with null/undefined
|
||||
- Direct operations
|
||||
- Raw collection operations
|
||||
|
||||
3. **Migration Operations**:
|
||||
- Database migrations
|
||||
- Data import/export
|
||||
- Schema changes
|
||||
|
||||
4. **Performance Testing**:
|
||||
- Large dataset operations
|
||||
- Concurrent operations
|
||||
- Memory usage
|
||||
|
||||
## Monitoring and Debugging
|
||||
|
||||
### MongoDB Driver System
|
||||
|
||||
The MongoDB driver system provides:
|
||||
- Automatic version detection
|
||||
- Driver selection based on MongoDB version
|
||||
- Connection monitoring
|
||||
- Error tracking
|
||||
|
||||
### Debug Methods
|
||||
|
||||
```javascript
|
||||
// Get connection statistics
|
||||
Meteor.call('mongodb-driver-stats', (error, result) => {
|
||||
console.log('Connection Stats:', result);
|
||||
});
|
||||
|
||||
// Test connection
|
||||
Meteor.call('mongodb-driver-test-connection', (error, result) => {
|
||||
console.log('Connection Test:', result);
|
||||
});
|
||||
|
||||
// Get supported versions
|
||||
Meteor.call('mongodb-driver-supported-versions', (error, result) => {
|
||||
console.log('Supported Versions:', result);
|
||||
});
|
||||
```
|
||||
|
||||
### Real-time Monitoring
|
||||
|
||||
```javascript
|
||||
// Subscribe to monitoring
|
||||
Meteor.subscribe('mongodb-driver-monitor');
|
||||
|
||||
// Access data in template
|
||||
Template.yourTemplate.helpers({
|
||||
driverStats() {
|
||||
return MongoDBDriverMonitor.findOne('stats');
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Query Optimization
|
||||
|
||||
1. **Use Indexes**: Ensure proper indexes for frequently queried fields
|
||||
2. **Limit Results**: Use `.limit()` and `.skip()` for pagination
|
||||
3. **Project Fields**: Use projection to limit returned fields
|
||||
4. **Aggregation**: Use aggregation pipelines for complex operations
|
||||
|
||||
### Security
|
||||
|
||||
1. **Validate Input**: Always validate user input
|
||||
2. **Use Regular Methods**: Prefer regular methods over direct operations
|
||||
3. **Server-side Only**: Keep sensitive operations server-side
|
||||
4. **Audit Logging**: Log important operations
|
||||
|
||||
### Performance
|
||||
|
||||
1. **Connection Pooling**: Use connection pooling for better performance
|
||||
2. **Batch Operations**: Use batch operations for bulk data
|
||||
3. **Caching**: Implement caching for frequently accessed data
|
||||
4. **Monitoring**: Monitor query performance and optimize as needed
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Connection Failures**:
|
||||
- Check MONGO_URL configuration
|
||||
- Verify MongoDB server is running
|
||||
- Check network connectivity
|
||||
|
||||
2. **Query Errors**:
|
||||
- Verify query syntax
|
||||
- Check field names and types
|
||||
- Validate MongoDB version compatibility
|
||||
|
||||
3. **Performance Issues**:
|
||||
- Check indexes
|
||||
- Optimize queries
|
||||
- Monitor connection pool usage
|
||||
|
||||
### Debug Commands
|
||||
|
||||
```bash
|
||||
# Check MongoDB version
|
||||
mongo --eval "db.version()"
|
||||
|
||||
# Check connection status
|
||||
mongo --eval "db.runCommand({connectionStatus: 1})"
|
||||
|
||||
# Check indexes
|
||||
mongo --eval "db.collection.getIndexes()"
|
||||
|
||||
# Check query performance
|
||||
mongo --eval "db.collection.find().explain('executionStats')"
|
||||
```
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### From Older MongoDB Versions
|
||||
|
||||
1. **Backup Data**: Always backup before migration
|
||||
2. **Test Compatibility**: Test with target MongoDB version
|
||||
3. **Update Drivers**: Use appropriate driver for MongoDB version
|
||||
4. **Run Migrations**: Execute any necessary data migrations
|
||||
5. **Validate**: Verify all functionality works correctly
|
||||
|
||||
### To Newer MongoDB Versions
|
||||
|
||||
1. **Check Compatibility**: Verify all queries are compatible
|
||||
2. **Update Queries**: Fix any deprecated method usage
|
||||
3. **Test Thoroughly**: Test all functionality
|
||||
4. **Monitor Performance**: Watch for performance changes
|
||||
5. **Update Documentation**: Update any version-specific documentation
|
||||
|
||||
## Support
|
||||
|
||||
For MongoDB compatibility issues:
|
||||
|
||||
1. Check this guide for known issues and solutions
|
||||
2. Review MongoDB release notes for version-specific changes
|
||||
3. Test with the MongoDB driver system
|
||||
4. Use the monitoring tools to diagnose issues
|
||||
5. Consult the Wekan community for additional help
|
||||
|
||||
## License
|
||||
|
||||
This MongoDB Compatibility Guide is part of Wekan and is licensed under the MIT License.
|
||||
Loading…
Add table
Add a link
Reference in a new issue