Docs Menu

Docs Home → Develop Applications → MongoDB Drivers → Node.js Driver

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:

← Enable TLS on a Connection
Stable API →

On this page