Mongoose Connection Management: How to Properly Close Database Connections to Prevent Node.js Process Hanging

Problem Background and Symptoms

A common issue in Node.js scripts using Mongoose for database operations is that the process fails to exit normally after completing tasks, requiring manual termination. This often occurs in non-continuously running scripts, such as one-time data processing tasks or test scripts. The core problem lies in improper management of the Mongoose connection lifecycle.

Basic Methods for Closing Connections

According to the best answer, the correct way to close a Mongoose connection is to use mongoose.connection.close(). This method closes the underlying MongoDB connection and allows the Node.js process to exit normally. Here is a basic example:

const mongoose = require('mongoose');
mongoose.connect('mongodb://localhost:27017/mydb');
// Perform database operations
// ...
mongoose.connection.close(); // Correctly close the connection

However, in practice, simply calling close() may not suffice, especially when there are pending queries.

In-Depth Analysis and Supplementary References

Other answers mention that sometimes mongoose.disconnect() is needed. In fact, mongoose.disconnect() is an alias for mongoose.connection.close(), and both are functionally equivalent. The key point is that, regardless of the method used, it is essential to ensure all database queries have completed. If there are unfinished asynchronous operations, the connection close request may be ignored, causing the process to hang.

The following code demonstrates how to ensure queries complete before closing the connection:

const mongoose = require('mongoose');
async function runScript() {
    await mongoose.connect('mongodb://localhost:27017/mydb');
    const MyModel = mongoose.model('MyModel', new mongoose.Schema({ name: String }));
    
    // Perform asynchronous queries
    const results = await MyModel.find({});
    console.log(results);
    
    // Close the connection after ensuring all operations are complete
    await mongoose.connection.close();
}
runScript().catch(console.error);

This example uses async/await syntax to ensure database operations execute sequentially and closes the connection after all operations are complete.

Best Practices and Considerations

To prevent process hanging, it is recommended to follow these best practices:

1. Use asynchronous patterns (e.g., async/await or Promises) to manage database operations, ensuring all queries complete before closing the connection.
2. Explicitly call mongoose.connection.close() in the script's exit logic.
3. Handle potential errors, such as connection failures or query timeouts, and close the connection in error handlers.
4. For complex applications, consider using connection pools or lifecycle hooks (e.g., process.on('exit', ...)) to manage connection states.

Additionally, note that Mongoose and the MongoDB driver may internally cache connections or delay actual closure, so thorough testing is necessary in production environments to ensure the reliability of connection management logic.

Conclusion

Properly closing Mongoose connections is crucial for ensuring Node.js processes exit normally. By using mongoose.connection.close() and ensuring all asynchronous queries complete, process hanging issues can be effectively avoided. Combining asynchronous programming best practices with error handling enables the construction of more robust database operation scripts.