mirror of
https://github.com/wekan/wekan.git
synced 2026-11-20 09:45:04 -05:00
docs/Databases/Supported.md is the one list: FerretDB v1 with SQLite (the default everywhere), PostgreSQL (works), MySQL, MariaDB and SAP HANA (experimental), FerretDB 2 (not tested), and MongoDB 6, 7, 8 and 9 - with what checks each: the 110-query conformance catalogue answers the same on all of them, and WeKan's own tests run on Meteor's bundled MongoDB 8 and on FerretDB. It also says what to know about MongoDB versions: the Linux kernel 6.19-7.0.13 refusal and its fixes, AVX, the driver, and upgrades. The README and the Status section of CHANGELOG.md gain a Databases list, docs/Databases/README.md links the page, the Meteor 2.14 compatibility guide is marked historical, and the conformance page counts 110 cases and the MongoDB backends. CLAUDE.md and AGENTS.md describe the new Status block. Thanks to xet7 !
324 lines
9.0 KiB
Markdown
324 lines
9.0 KiB
Markdown
# MongoDB Compatibility Guide
|
|
|
|
> **Historical.** This page records fixes made when WeKan ran on Meteor 2.14.
|
|
> WeKan now runs on Meteor 3.6 with the Node.js MongoDB driver 6.16. For which
|
|
> databases are supported today and how they are tested, see
|
|
> [../Supported.md](../Supported.md): MongoDB 6, 7, 8 and 9, and FerretDB v1.
|
|
|
|
## 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/adminProblems.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.
|