Enable SOCKS5 Proxy Support

On this page

Overview

Install the socks Package
SOCKS5 Client Options
Example
Additional Information
API Documentation

Overview

In this guide, you can learn how to connect to MongoDB instances by using a SOCKS5 proxy. SOCKS5 is a standardized protocol for connecting to network services through a proxy server.

Tip

To learn more about the SOCKS5 protocol, see the Wikipedia entry on SOCKS.

Install the socks Package

Starting in version 6.0 of the Node.js driver, you must install the socks package to use SOCKS5 proxy support in your application. You can install socks by running the following command in your shell:

npm i socks

SOCKS5 Client Options

You can set options in your MongoClientOptions instance or in your connection URI to configure SOCKS5 proxy support for your connection. The following table describes the client options related to SOCKS5:

Name	Accepted Values	Default Value	Description
proxyHost	string	`null`	Specifies the SOCKS5 proxy IPv4 address, IPv6 address, or domain name.
proxyPort	non-negative integer	`null`	Specifies the TCP port number of the SOCKS5 proxy server. If you set the `proxyHost` option, the value of this option defaults to `1080`.
proxyUsername	string	`null`	Specifies the username for authentication to the SOCKS5 proxy server. If you set this option to a zero-length string, the driver ignores it.
proxyPassword	string	`null`	Specifies the password for authentication to the SOCKS5 proxy server. If you set this option to a zero-length string, the driver ignores it.

Important

The driver throws an error if you set the proxyPort, proxyUsername, or proxyPassword options without setting the proxyHost option.

Example

This example shows how to instantiate a MongoClient that uses SOCKS5 proxy support. The following example code specifies proxy server options and connects to MongoDB:

// Replace the placeholder with your connection string
const uri = "<connection string uri>";
// Replace the placeholders with your SOCKS5 proxy server details
const socksOptions = {
  proxyHost: "<host>",
  proxyPort: 1080,
  proxyUsername: "<username>",
  proxyPassword: "<password>",
};
// Create a new client with the proxy server details
const client = new MongoClient(uri, socksOptions);

Tip

The preceding sample code uses placeholders for the connection URI and proxy server details. To run this code, you must replace these placeholders with the information for your deployment and proxy server.

Additional Information

For more information about SOCKS5 proxy support, see the MongoDB SOCKS5 specification.

API Documentation

To learn more about the methods and types discussed in this guide, see the following API Documentation:

Back

Enable TLS on a Connection

Stable API