Skip to main content
Connect Supaboard to a MongoDB database using a standard connection string (URI).

​
Before you connect

Network access — Supaboard connects from a fixed set of egress IPs. For MongoDB Atlas, add them to your cluster’s IP access list under Security → Network Access. The current IP list is shown inside the connector form under Whitelist IPs. Database user permissions — The user in your connection string needs at minimum:
  • read role on the target database
See Recommended database user permissions for instructions.

​
Connection fields

FieldDefaultRequiredDescription
Display Name—YesLabel shown in the Supaboard UI
Connection String—YesFull MongoDB URI (see format below)

​
Connection string format

Supaboard accepts a full MongoDB URI. The standard format is: 
mongodb+srv://username:password@cluster-host/?authSource=admin
For non-SRV connections (self-hosted or older Atlas clusters): 
mongodb://username:password@host:27017/database?authSource=admin
PartDescription
mongodb+srv://Use +srv for Atlas and DNS-based clusters; use mongodb:// for direct host connections
username:passwordMongoDB user credentials — URL-encode special characters (e.g. @ → %40)
cluster-hostCluster hostname (Atlas) or server IP/hostname (self-hosted)
databaseOptional — the specific database to connect to; if omitted, Supaboard auto-discovers
authSource=adminThe authentication database — usually admin for Atlas

​
Finding your connection details

​
MongoDB Atlas

  1. Open cloud.mongodb.com and select your project.
  2. In the Clusters view, click Connect on your cluster.
  3. Select Drivers (or Connect your application).
  4. Choose any driver — you only need the connection string, not the code snippet.
  5. Copy the connection string. It will look like: 
    mongodb+srv://<username>:<password>@cluster0.xxxxx.mongodb.net/?retryWrites=true&w=majority
  6. Replace <username> and <password> with your Atlas database user credentials.
  7. Paste the full string into the Connection String field in Supaboard.
Documentation: Connect to a cluster · Connection string URI format Adding Supaboard IPs to Atlas: Atlas requires you to explicitly allow external IPs before any connection can succeed.
  1. In your Atlas project, go to Security → Network Access.
  2. Click Add IP Address.
  3. Add each Supaboard egress IP individually (found in the connector form under Whitelist IPs).
  4. Click Confirm.
Atlas IP access list changes take effect immediately. You do not need to restart your cluster.
Documentation: Configure IP access list entries

​
Recommended database user permissions

In MongoDB Atlas:
  1. Go to Security → Database Access.
  2. Click Add New Database User.
  3. Choose Password authentication.
  4. Set a username and strong password.
  5. Under Database User Privileges, select Built-in Role → Read Only (or use a custom role scoped to specific databases).
  6. Click Add User.
  7. Use this username and password in your connection string.
For self-hosted MongoDB: 
use your_database
db.createUser({
  user: "supaboard",
  pwd: "strong_password_here",
  roles: [{ role: "read", db: "your_database" }]
})

​
Troubleshooting

ErrorLikely causeFix
connection refusedAtlas IP access list missing Supaboard IPsAdd all Supaboard egress IPs under Security → Network Access
Authentication failedWrong username or password in the URIVerify credentials in Atlas under Security → Database Access
bad auth : authentication failedWrong authSourceAdd ?authSource=admin to the URI
URI must include hostnameMalformed connection stringCheck that the URI starts with mongodb:// or mongodb+srv://
querySrv ENODATADNS resolution failing for +srv URITry switching to a direct mongodb:// URI with explicit host and port
Special characters in passwordURI parsing errorURL-encode special characters: @ → %40, # → %23, : → %3A
Last modified on March 11, 2026