wekan/docs/Databases/MongoDB/Compatibility-Guide.md

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: 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:

// 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:

// 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

// 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

// 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

# 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.