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.6.4). 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 supports multiple windows 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 many 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. It let's you open collections or databases swiftly. Just start typing the name of a collection, for example, and Mingo will give you suggestions.

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+Rreload the content of the current tab's view (for example reload documents)
CTRL+Ffind in page (fulltext)
CTRL+Nopen a new Mingo window
Tabs
CTRL+Topen new tab
CTRL+Wclose current tab
CTRL+SHIFT+Treopen 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+TABfocus previous tab
Documents
CTRL+Rreload documents
CTRL+Aselect all documents
CTRL+Enter in query input to submit
CTRL+Sfocus query input (selector)
CTRL+Zopen Mingo UNDO
Point cursor at document and press X (only letter x) or spaceselect that document
Point cursor at document header and press CTRL+Ccopy the entire document
Point cursor at document and press Eedit the document
Point cursor at field and press CTRL+Ccopy the value
Point cursor at field and press E or Double-Clickedit the field inline
Type {to focus query input (selector)

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 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:

  1. Open Dump - right-click on database and choose Dump database...
  2. Select the collections to dump.
  3. 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.
  4. Choose dump options (if relevant) - only gzip is currently available to compress the dump files.
  5. Choose restore options (if relevant) - only drop is currently available to drop the destination collection before copying the new data.
  6. 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.

Documents

Mingo's documents browser is the most convenient way to browse, view and work with MongoDB documents.

Querying

To find and view documents, Mingo let's you define a query and a sorting object. Skip and limit are replaced with pagination. Projection is also omited to prevent confusion by showing the documents as they are. Also, Mingo handles huge documents easily.

The query editor has many hidden features you should know about.

General features

  • Query history - is available by clicking on the "Query" label on the left of the query input.
  • Sort history - is available by clicking on the "Sort" label on the left of the sort input. By default, Mingo provides options to sort by indexes.
  • Auto suggestions - Mingo analyzes the structure of the documents in each collection and will suggest field names, functions and even values in some cases.
  • Format query - this button in the top right of the query editor will format (and indent) the current query.
  • Reset query - the X button in the top right will reset the query and sorting. By default, this means empty query and no sorting. However, if you have saved a default query for the collection, it will default to it.
  • Submit / Refresh - the query can be submitted by CTRL+Enter or just Enter, depending on your settings. To refresh the documents' list, just press CTRL+R
  • Saving queries - you can either create a saved named query or save the current query as the default (both query and sorting) for the collection. Anytime you open a new tab with this collection, the default query will be used.
Automatic quotes in queries
Mingo will automatically correct your missing quotes in queries. Submitting { user.lastName: "Pear"} will be automatically corrected to { "user.lastName": "Pear"}.

Dates in queries

Mingo supports human-readable shorthands for dates in queries. Compare the following two queries:

{ "createAt": { "$gte": ISODate("2020-02-21T00:00:00Z"), // or new Date(…) "$lt": ISODate("2020-02-28T00:00:00Z"),) // or new Date(…) } } { "createdAt": #lastWeek }

There are two main types of date shorthands available:

  • Durations - (prefixed with #) represent periods between two moments.
    For example: {"createdAt": #lastWeek} will search for documents where createdAt is between the beginning and end of last week.
  • Moments - (prefixed with @) represent a single exact moments.
    For example: {"createdAt": @2021-11-22} will search for documents where createdAt is EXACTLY the moment of the start of that day.
Duration shorthands
#todaysince the start of the today
#yesterdayduring yesterday
#tomorrowduring tomorrow
#thisWeekduring the current week
#thisMonthduring the current month
#thisYearduring the current year
#lastWeekduring the previous week
#lastMonthduring the previous month
#lastYearduring the previous year
#lastYearduring the previous year
#last{number}{period}
#last2days, #last14weeks, #last3years
During the last {number} {period}. Use any number and one of the following periods: minutes, hours, days, weeks, months, years. This is case insesitive, so you may use #last4Years.
#next{number}{period}
#next2days, #next14weeks, #next3years
During the next {number} {period}. Use any number and one of the following periods: minutes, hours, days, weeks, months, years. This is case insesitive, so you may use #next4Years.
#2021-11-22during any specific date
#2021-11during any specific month
#2021during any specific year
#since2017-10-03since any specific date
#before2017-10-03before any specific date
Moment shorthands
@2020-01-29T17:29:50+00:00 ISO 8601 format, or any part of it, such as @2020-01-29, @2020-01-29T17:29, etc. These represent a specific moment, so the documents have to match exact moment.

Smart (quick) searches

Indexed fields can be searched swiftly by using the value as query.

So instead of providing an object as a query, such as {city: 'Amsterdam'}, you can simply use Amsterdam as the query. Mingo will try to find the phrase "Amsterdam" in ALL the indexed fields.

You can even use regular expressions as quick queries, such as /amsterdam/i.

For example, you could copy an _id “KdMKY4qzDik3sm6CE” from your admin and paste it as a query. Mingo will look for the value in all indexed fields (_ids are always indexed) and show you the real query you meant to use: {_id: “KdMKY4qzDik3sm6CE”}. This also works with ObjectIDs.

Regular expressions in queries

Mingo supports querying by regular expressions. For example: {firstName: /david/i}.

You can even use regular expressions as quick queries, such as /david/i.

Paste & Go

This is a great feature, especially combined with Quick Search. Pressing CTRL+G will paste the current clipboard value into the query field and submit it. The pasted value could be a regular query or just a phrase or _id copied from your admin or other app.

Browsing

Mingo shows 50 documents per page. Click a document to view its content. Click on any field to expand its subdocuments. CTRL++click will expand the document (or field) recursively.

Table columns

When a collection is opened for the first time, Mingo will try to pick a few fields to show as columns by default. Any changes you make to them will be saved as defaults for the collection.

  • Adding columns - add more columns to view by clicking at the + sign in the column headers row. You may also pin any field or even nested field by right-clicking at the field and selecting "Pin as new column".
  • Removing columns - click the column header and select Unpin.
  • Sorting by columns - click the column header and select the sorting option you need.
  • Aligning columns - click the column header and select the alignment icon.
  • Resizing columns - click the column header and select the icon for minimum, optimum or maximum column width. You may also use the "resize handle" icon in column header and drag it to resize.
  • Reorganizing columns - Drag the column header to reorganize them.
  • Formatting columns - Select the "Customize" option on the colum header to set conditional formatting and much more (*experimental feature).

Manipulating

Document actions

Right-click any document to get a list of options and actions for that document.

Working with multiple documents

Mingo supports actions upon multiple selected documents.

  • Select all documents - click the checkbox in the table header or press CTRL+A. Press it again to toggle. Selecting "all documents" means selecting all documents in the collection, even those not currently listed.
  • Selecting individual documents - just hover a document and click space to toggle its selection. Shift+click will select a range of documents. You can even select multiple ranges.

Field actions

Right-click any field to get a list of options and actions for that field.

  • Edit field value - double-click a field or hover it and press E to edit the value.
  • Foreign keys - if the field's value looks like an _id, Mingo will let you find the document in the database with one click. The found document will be opened in a new tab. How cool is that? :-)
  • Long values - if the field's value is too long, Mingo will truncate it and let you view the entire value by clicking at it.
  • Urls - if the field's value resembles a URL, Mingo will make it a link and open it in your default browser..

Undo

UNDO is available to reverse changes done by insert, update or remove operations. Press CTRL+Z to open the list of recent changes to documents. You may then select the action to UNDO.