Mingo Documentation

About

What is Mingo

Mingo is the latest addition to the family of MongoDB Admin tools, yet it aspires to be the most widely used of all such tools. The goal is to create the most user-friendly and fastest app, packed with features helping (mainly) Javascript / NodeJS developers in managing their MongoDB. Let's see if we can make it :-).

Our team

Mingo is being developed by David and Rad. We are not even a small start-up and we haven't raised any money to build Mingo. Just two guys enjoying our work. We'd like to create a small helpful app, get to know nice people and learn a lot along the way.

Submitting issues

To make Mingo really usefull, we need your feedback. So if you happen to find a bug, report it, please.
Don't dismiss Mingo right away. Thank you.

Feature requests

Ideas, feature requests and even minor usability issues are the caffeine that keeps us rolling.
Please, submit your ideas on Github.

This documentation always refers to the latest version of Mingo (currently v1.4.2). Make sure you are using it.

Installation

Download

Mingo is available for Mac (OSX), Linux and Windows. You can download Mingo at our download page.

Apple / Mac (OSX)	Mingo for Apple is available in three formats: DMG, ZIP, PKG. We recommend the DMG format. Download the latest version here.
Linux	Mingo for Linux is available in tree formats: AppImage, Deb, Snap. Download the latest version here.
Windows	For windows, Mingo is packaged as NSIS. Download the latest version here.

Windows shows an alert before installation saying "Windows Defender SmartScreen prevented an unrecognized app from starting...". The reason is that we didn't bother buying an over-priced developer licence. This alert will not show once "a fair number of users install the app".
Please bear with us. Thank you!

Migration from other apps

Since most other MongoDB GUIs encrypt their connection data, we are not able to import these settings easily to Mingo. Furthermore, Mingo's projects are a new concept and so we cannot import them.

Setting up connections and projects in Mingo take a few seconds, just copy your Mongo URI and you'll be set to go. Thanks for understanding.

Navigation

Workspaces

Mingo currently supports one window at a time - a workspace. Each connection and project has its own workspace. You can switch between workspaces with the workspace selector at the top of the sidebar.

Keep in mind, that switching workspaces (to a different connection or project) terminates the current tabs and the actions in progress.

Sidebar

Mingo's sidebar is the main navigation. It contains:

Workspace selector - for switching connections and projects
Databases and Collections
Other tools

Workspace selector

Allows selecting the connection / project you want to work with. Your entire view (Mingo's window) is focused on the workspace you have selected.

Databases and Collections

This is a tree view of databases and their collections. Use right-click on a database or a collection to show the respective context menu.

If you click on a collection, it will open a new tab.

Mingo shows basic collection stats if you point the cursor at it.

If you have databases with larger number of collections, but you usually work with only a handfull of them, you can "pin" a collection. Pinned collections are shown even when the database is collapsed.

Tabs

Tabs in Mingo work the same way you are used to from a browser. You may rearrange tabs (drag & drop or keyboard shortcuts), close, reopen closed tabs or close "other" tabs.

The following types of tabs are currently used in Mingo:

Database - contains everything for managing a database, listing its collections, NodeShell, dump, copy, restore, etc.
Collection - contains everything for managing a collection, viewing documents, aggragating, analyzing schema, indexes, views, doing exports or imports, etc.
Compare / Sync - a tool to compare and possibly sync data in different databases.

Each tab works independently and you may switch between tabs even while work is being done in the background.

Tab views

Tabs are separated into views (such as "Documents", "Aggregator", "Indexes" or "Export" in case of a collection tab).

Switching between tab views is fast and keeps everything running in the background.

Context menu

Mingo has lots of features and these are mostly hidden to keep the UI clean. Most features can be found using the context menu (mouse right click). The context menu works as usual, showing options for the item you click on. Such items are database or collection (in the side bar), a document, a document field, etc. So, if you want to "do something with a document field", open the document and right-click on the field in question.

Finder

When you open a new tab, Mingo's finder will pop up. Finder let's you open collections or databases swiftly. Just start typing the name of a collection, for example, and Mingo will give you suggestion.

Use up and down arrow keys to select a collection and left or right keys to choose the a view. Enter to submit.

If you paste an ObjectID into Finder, Mingo will find it in the selected database for you.

Keyboard shortcuts

To make using Mingo even faster and more intuitive, it features a lot of keyboard shortcuts. We didn't want you to learn new set of shorcuts, so we tried to use the same ones you are used to.

Global

CTRL+SHIFT+F	open Finder
CTRL+R	reload the content of the current tab's view (for example reload documents)

Tabs

CTRL+T	open new tab
CTRL+W	close current tab
CTRL+SHIFT+T	reopen recently closed tab
CTRL+1 - CTRL+8	focus n-th tab
CTRL+9	focus last tab
CTRL+LEFT	focus tab to the left
CTRL+RIGHT	focus tab to the right
CTRL+SHIFT+LEFT	move current tab to the left
CTRL+SHIFT+RIGHT	move current tab to the right
CTRL+TAB	focus previous tab

Documents

CTRL+R	reload documents
CTRL+A	select all documents
CTRL+Enter	in query input to submit
CTRL+S	focus query input (selector)
CTRL+Z	open Mingo UNDO
Point cursor at document and press X (only letter x) or space	select that document
Point cursor at document header and press CTRL+C	copy the entire document
Point cursor at document and press E	edit the document
Point cursor at field and press CTRL+C	copy the value
Point cursor at field and press E or Double-Click	edit the field inline

Connections

What is a connection?

A connection is exactly what you are used to from other MongoDB GUIs. Connections allow full database and connection management.

You may have a project and a connection to the same server simultaneously.

Creating a connection

To create a new connection, click the workspace selector (top left) and select the Add new Connection / Project option. In the modal window, choose Create a connection.

Connection selector

Connection options

Color	Select a color that will represent your connection in Mingo. Collections, tabs and some other UI elements will be using this color to remind you what collection you are working with.
Name	Choose a short descriptive name for your connection. Examples: "Localhost", "My project", etc.
Favicon	An optional favicon to represent the connection. You may use an image or a Font Awesome icon. Image / icon - use the URL of the image or ico file Font Awesome icon - use any Font Awesome icon. Make sure to add the full classname of an icon, for example fal fa-home.
Mongo URI	The mongo URI of your connection. This could be in standard or SRV format. In case of sharded connections, include the URI with all sharded connections separated by a comma. MongoDB URI documentation can be found here.
Connect using SSH	In case you need to use an SSH tunnel to connect to your database, select this option and fill in the details: Password or private key required, but not both. Click the "Use default" link to guess your privaty key path.

Updating a connection

To update an existing connection, click the workspace selector (top left) and then click pencil icon by the connection you would like to update. Follow the same rules as for Creating a connection.

Refreshing a connection

Mingo will regularly scan your connection for databases and collections. In case you need to refresh the connection, you can do it manually using the workspace selector and clicking on "Refresh". This is, however, rarely necessary, as Mingo will do it automatically (for example, when collection is added, removed, renamed, etc).

Deleting a connection

To delete an existing connection, click the workspace selector (top left) and then click pencil icon by the connection you would like to delete. At the bottom left of the modal window, click the Delete connection... This will ask you for confirmation before deleting the connection.

Deleting a connection from Mingo WILL NOT delete any data from the server. It will only delete the connection to the database from Mingo.

Projects

What is a project?

Mingo came up with the concept of Projects. A project is like a wrapper on several connections to “sibling” databases, such as “development”, “production”, “testing”, “staging”. Mingo treats these databases as “similar” and understands the relationships between them. Query history, bookmarks, pinned columns and other settings are shared across each database.

Furthermore, projects simplify daily tasks such as "Dump Production DB into Development DB", "Copy collection from Production to Dev" or "Send one document from Production to Dev" with one click.

You may have a project and a connection to the same server simultaneously.

Creating a project

To create a new project, click the workspace selector (top left) and select the Add new project / Project option. In the modal window, choose Create a project.

Project options

Name	Choose a short descriptive name for your project. Examples: "Carrot", "Pine tree", etc.
Favicon	An optional favicon to represent the connection. You may use an image or a Font Awesome icon. Image / icon - use the URL of the image or ico file Font Awesome icon - use any Font Awesome icon. Make sure to add the full classname of an icon, for example fal fa-home.
Databases	Each project may contain several databases. These databases are usually on different connections (servers) and refer to databases of the same project. Examples would be "Development", "Production", "Backup", "Staging", etc. Each database is esentially a connection with the same settings as a connection.
Connect using SSH	In case you need to use an SSH tunnel to connect to your database, select this option and fill in the details: Password or private key required, but not both. Click the "Use default" link to guess your privaty key path.

In case of a project, the connection URI must point to a specific database, not an entire server.

Updating a project

To update an existing project, click the workspace selector (top left) and then click pencil icon by the project you would like to update. Follow the same rules as for Creating a project.

Deleting a project

To delete an existing project, click the workspace selector (top left) and then click pencil icon by the project you would like to delete. At the bottom left of the modal window, click the Delete project... This will ask you for confirmation before deleting the project.

Deleting a project from Mingo WILL NOT delete any data from the servers. It will only delete the project and its connections from Mingo.

Databases

Write-Lock

Write-Lock will prevent unintended changes on documents of a locked database.

Databases are locked by default. You may unlock the database from the database context menu. When trying to perform a write action on a locked database, Mingo will ask ask you to confirm the action by allowing to unlock the database for 10 minutes or completely.

Collections list

To view the list of all collections of a database, click the Collections & Stats in the database context menu. This is an alphabetical list with basic statistics. To view detailed information about a collection, just click on its row. To perform actions on a collection, use right-click on the row.

You may also add a new collection in this view using the Create new collection button at the top.

Create a new database

To create a new database, click the "Create Database" button in the sidebar below the existing databases. Creating a new database is only possible in a connection and you (the user) must have relevant privileges.

Creating a new database is not possible in a project, since a project is already connecting to existing databases.

Dump and copy data

Mingo features a great dump tool to simplify and automate dumping, duplicating and copying collections across databases.

To open the Dump tool, right-click on a database in sidebar and choose Dump database....

This feature requires MongoDB's mongodump and mongorestore to be installed locally on your computer. If not found in the default PATH, Mingo will ask you to choose the location of these files. To install mongodump and mongorestore, refer to the documentation.

Here's how it works:

Open Dump - right-click on database and choose Dump database...
Select the collections to dump.
Select the destination.
- Directory - dump selected collections into a directory using the regular mongodump tool.
- Archive - dump selected collections into an archive file using the regular mongodump tool with -archive directive.
- Other database - copy collections into another database within current workspace.
- New database - select a connection to create a new database in and choose a database name. Selected collections will be copied into the newly created database.
Choose dump options (if relevant) - only gzip is currently available to compress the dump files.
Choose restore options (if relevant) - only drop is currently available to drop the destination collection before copying the new data.
Confirm action - before actually performing the dump / copy operation, Mingo will ask for confirmation explaining the planned steps.

You may leave the tab / view while dump being performed. Mingo will let you know when the action is finished with a beep sound.

Save dump settings

Mingo lets you save the current dump / copy settings and reuse them again quickly when needed. Settings are stored for the current database only. To save the settings, use the Save button in main menu bar. To open, use the Open button and select the settings.

When saving, choose a short descriptive name. If you want to overwrite stored settings, just use the same name again.

NodeShell

Mingo's NodeShell let's you execute JavaScript code to work with data directly in Mingo. This is NOT MONGO SHELL, though.

The command should be either a regular async JS function with a return value or a simple MongoDB Node.js driver command. It's API can be found here.

Executing MongoDB Node.js driver commands

To execute simple commands, just type the command:

db.collection("MyCollection").find({}).toArray()

You may omit the .toArray() and Mingo will guess it to fetch results.

Results are limited to 100 rows (documents) if larger.

Executing regular JavaScript code

This allows complex code with loops, conditions and variable initialization to be executed. This code must be a definition of a async function and should return something to see "results". You can use this to fetch and process data using JS code and return the result or update documents using a script with loop, etc. Examples:

async () => {
  return await db.collection("").find({});
}

async () => {
  const docs = await db.collection("Amenities").find({}).toArray();
  for (const doc of docs) {
    await db.collection("Amenities").updateOne({_id: doc._id}, {$set: {something: "new"}})
  }

  return docs.length;
}

Snippets and saved code

Mingo provides some example snippets. You may also save your code for later use. Code is saved for each database separately. History of your executed commands is also available.

Refresh database

If you need to refresh database information, collections and basic stats, you may do this manually using the context menu (right-click) on the database in sidebar and select Refresh. Mingo, however, does this automatically in the background.

Drop database

Dropping an entire database with all collections and their data is possible using the context menu (right-click) on the database in sidebar and selecting Drop database.... Mingo will ask for a confirmation.

There is NO UNDO available after dropping a database. Think twice.

Collections

The collection tab

When you open a new tab with a collection, that tab is dedicated to the selected collection. It provides all the tools and actions you may need to perform on a collection.

At the top left, you'll find your current location: Connection -> Database -> Collection. Next to it, the pills represent views / features / tools to work with the collection:

Documents - let's you browse documents, view their contents and perform actions on them
Aggregator - Mingo's interactive tool for creating aggregations visually
Schema - analyzes documents' schema and lets you perform statistical or clean-up operations on documents
Indexes - List of indexes and their manager
View - list of collection's views and their manager
Export - an interactive tool to export documents in different formats
Import - to import documents into the collection from various sources
Actions - further actions to perform with the collection

Copy collection to

Mingo lets you copy your collection into a different database or new collection very easily with just a few clicks. This will take you to Mingo's Dump tool and preset your selection. Just submit your action and Mingo will perform the copying.

Dump collection

Basically the same functionality as with Copy collection to, but dumps the collection into a directory or archive file. This action opens the same Dump tool, but with different settings.

Export collection

This option focuses the Export view in the collection tab. The details of how to export documents are described in the Export section of the docs.

Create view

This action opens the View generator form in a modal window. Creating views requires a basic knowledge of how they work, so refer to the MongoDB documentation, please.

Since Views are created using aggregation pipelines, you can create the pipeline first using the Aggregator and then use it to create the View.

Rename collection

This does what it says and it's very simple. Just provide the new collection name.

Truncate collection

Truncating a collection means deleting all its documents completely, essentially making it empty. All associated Views and Indexes are kept. So use this feature wisely. There's NO UNDO for this action.

Drop collection

Dropping a collection means deleting all its documents and the collection itself, completely. Views and Indexes are deleted, too. So use this feature wisely. There's NO UNDO for this action.