DocumentDB Local<\/strong> is part of the broader open-source DocumentDB project<\/strong>, a document-oriented database engine built on PostgreSQL. You can explore the project and follow its updates here: https:\/\/github.com\/microsoft\/documentdb<\/a><\/p>\n This guide walks you through setting up DocumentDB Local<\/strong> with Docker and connecting to it using the DocumentDB for VS Code Extension<\/strong>.<\/p>\n Before you begin, check if Docker is already installed:<\/p>\n \u2705 If the command returns a version number, you’re ready to continue with the next step.<\/strong><\/p>\n Otherwise, follow the instructions below to install Docker:<\/p>\n \u2705 Once installed, confirm Docker is running with To start DocumentDB Local<\/strong>, run the following command in your terminal:<\/p>\n What this command does:<\/strong><\/p>\n You can modify the port number, the username, and the password to match your requirements.<\/p>\n Docker will download the image the first time you run the command. It might take a minute or two depending on your connection. Once started, the container runs DocumentDB Local<\/strong> and exposes it on your machine.<\/p>\n \u2705 DocumentDB Local is now running and ready to accept connections.<\/strong><\/p>\n By The Way: <\/strong>The command docker ps<\/a> will list all running containers and docker stop<\/a> will gracefully stop a container for you once you\u2019re done with this walkthrough.<\/p>\n Once DocumentDB Local is running<\/strong>, use the DocumentDB for VS Code Extension<\/strong> to connect and manage your local data.<\/p>\n \u2705 Your DocumentDB Local database is now ready, and you can begin managing and exploring your data.<\/strong><\/p>\n Once the new connection has been created, you can connect to your DocumentDB Local<\/strong> and create a new database and collection to start managing data.<\/p>\n \u2705 You have successfully created a new database and collection.<\/strong><\/p>\n Populate your collection with sample data to explore the extension\u2019s features. Here<\/strong><\/a> is a download link for a sample file containing a description of 500 restaurants and their reviews. Download the file and have it available for the next steps.<\/p>\n \u2705 You’ve now connected to DocumentDB Local using the VS Code extension and imported your first dataset.<\/strong><\/p>\n Use the JSON<\/strong>, Tree<\/strong>, and Table<\/strong> Views<\/strong> to analyze your data in different formats.<\/p>\n Navigate through the paging controls<\/strong> to explore beyond the first 10 documents<\/strong>.<\/p>\n \u2705 You have explored different ways to view your data.<\/strong><\/p>\n Working with DocumentDB for VS Code<\/strong> is only one way to connect to DocumentDB Local<\/strong>. You can also use any MongoDB-compatible tool, or go directly to the shell:<\/p>\n The DocumentDB for VS Code extension<\/strong> can also launch the shell for you. This is helpful because it automatically handles your credentials and connection parameters.<\/p>\n The tutorial above introduced the basic setup of DocumentDB Local<\/strong> and the core features of the DocumentDB for VS Code Extension<\/strong>. However, both tools offer more advanced functionality to support your development workflow.<\/p>\n DocumentDB Local<\/strong> is an open-source, PostgreSQL-based document database engine that implements the MongoDB wire protocol<\/strong>. It enables local-first development and testing while ensuring compatibility with DocumentDB for Azure. Its containerized architecture makes it easy to start and stop on-demand and fits perfectly into CI\/CD workflows.<\/p>\n DocumentDB for VS Code<\/strong> is a lightweight extension that helps developers manage DocumentDB and MongoDB instances<\/strong> without leaving their editor. It provides an intuitive GUI for browsing databases, managing documents, importing\/exporting data, and running queries across local and remote environments.<\/p>\n We welcome your feedback<\/strong> on both tools! Join the conversation, report issues, and contribute ideas on GitHub<\/strong>:<\/p>\n Your feedback drives development! Vote on features, report issues, or suggest improvements. We look forward to hearing from you!<\/p>\n Azure Cosmos DB is a fully managed and serverless NoSQL and vector database for modern app development, including AI applications. With its SLA-backed speed and availability as well as instant dynamic scalability, it is ideal for real-time NoSQL and MongoDB applications that require high performance and distributed computing over massive volumes of NoSQL and vector data.<\/p>\n To stay in the loop on Azure Cosmos DB updates, follow us on\u00a0X<\/a>,\u00a0YouTube<\/a>, and\u00a0LinkedIn<\/a>.<\/p>\n To quickly build your first database, watch our\u00a0Get Started videos<\/a>\u00a0on YouTube and explore ways to\u00a0dev\/test free.<\/a><\/p>\n","protected":false},"excerpt":{"rendered":" Introduction DocumentDB Local provides a lightweight, containerized environment that lets you develop and test applications locally using a MongoDB-compatible interface. It\u2019s ideal for prototyping or running integration tests without needing a cloud setup. When paired with the DocumentDB Extension for Visual Studio Code, it creates a focused and consistent local development environment. DocumentDB Local is […]<\/p>\n","protected":false},"author":181541,"featured_media":10555,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[15,19],"tags":[963,1768,1951,1246,1870,498],"class_list":["post-10520","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-mongodb-api","category-tips-and-tricks","tag-api-for-mongodb","tag-azure-cosmos-db-api-for-mongodb","tag-documentdb","tag-mongodb","tag-vcore","tag-visual-studio-code"],"acf":[],"blog_post_summary":" Introduction DocumentDB Local provides a lightweight, containerized environment that lets you develop and test applications locally using a MongoDB-compatible interface. It\u2019s ideal for prototyping or running integration tests without needing a cloud setup. When paired with the DocumentDB Extension for Visual Studio Code, it creates a focused and consistent local development environment. DocumentDB Local is […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/10520","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/users\/181541"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/comments?post=10520"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/10520\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media\/10555"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media?parent=10520"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/categories?post=10520"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/tags?post=10520"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}\ud83c\udf93 End-to-End DocumentDB Local Walkthrough<\/h2>\n
1. Prerequisites: Set Up Docker<\/h3>\n
docker --version<\/code><\/pre>\nWindows<\/h4>\n
\n
WSL 2<\/code> is enabled (Docker will prompt you if it’s not).<\/li>\nmacOS<\/h4>\n
\n
Linux<\/h4>\n
\n
\n
sudo<\/code>.<\/li>\n<\/ul>\ndocker --version<\/code>.<\/strong><\/p>\n2. Start DocumentDB Local<\/h3>\n
docker run -dt -p 10260:10260 -e USERNAME=YourUsername -e PASSWORD=YourPassword ghcr.io\/microsoft\/documentdb\/documentdb-local:latest<\/code><\/pre>\n\n
docker<\/code>: The command-line tool used to manage Docker containers.<\/li>\n-dt<\/code>: Runs the container in detached mode with a terminal attached.<\/li>\n-p 10260:10260<\/code>: Maps port 10260<\/code> on your machine to the container. This is the port you’ll use to connect to DocumentDB Local<\/strong>.<\/li>\n-e USERNAME=YourUsername<\/code>: Sets your admin username to YourUsername<\/code>.<\/li>\n-e PASSWORD=YourPassword<\/code>: Sets your admin password to YourPassword<\/code>.<\/li>\nghcr.io\/microsoft\/documentdb\/documentdb-local:latest<\/code>: The public container image hosted on GitHub Container Registry.<\/li>\n<\/ul>\n![\"DocumentDB](\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2025\/05\/2025-05-DocumentDB-Local-Docker-Pulling.png\")
<\/a><\/p>\n![\"DocumentDB](\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2025\/05\/2025-05-DocumentDB-Local-Docker-Stopping.png\")
<\/a><\/p><\/blockquote>\n3. Connect using the DocumentDB for VS Code Extension<\/h3>\n
3.1. Install VS Code<\/h4>\n
\n
3.2. Install the DocumentDB for VS Code Extension<\/h4>\n
\n
Ctrl + Shift + X<\/strong><\/code> on Windows and Command + Shift + X<\/strong><\/code> on macOS.<\/li>\n3.3. Add a New Connection<\/strong><\/h4>\n
![\"DocumentDB](\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2025\/05\/2025-05-DocumentDB-Local-New-Connection.png\")
<\/a><\/p>\n\n
\n
\n
Disable TLS\/SSL<\/code> option.\n\n
3.4. Connect and Create a New Database and a Collection<\/h4>\n
![\"DocumentDB](\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2025\/05\/2025-05-DocumentDB-Local-New-Database.png\")
<\/a><\/p>\n\n
MyDatabase<\/strong><\/code> when prompted for the database name.<\/li>\nMyCollection<\/strong><\/code> when prompted for the collection name.<\/li>\n<\/ol>\n3.5 Import Sample Data<\/h4>\n
\n
restaurants.json<\/strong><\/code><\/a>.<\/li>\n![\"DocumentDB](\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2025\/05\/2025-05-DocumentDB-Local-Import.png\")
<\/a><\/p>\n3.6. Explore JSON, Tree, and Table Views<\/h4>\n
\n
\n
additionalInfo<\/strong><\/code>.<\/li>\n<\/ul>\n<\/li>\n\n
\n
additionalInfo<\/strong><\/code> to inspect embedded objects.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n4. More Ways To Connect<\/h3>\n
mongosh localhost:10260 -u <username> -p <password> \\\r\n --authenticationMechanism SCRAM-SHA-256 \\\r\n --tls \\\r\n --tlsAllowInvalidCertificates\r\n<\/code><\/pre>\n![\"DocumentDB](\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2025\/05\/2025-05-DocumentDB-Local-Launch-Shell-1024x682.png\")
<\/a><\/p>\nThere Is More<\/h2>\n
\ud83d\udcac Join the Discussion!<\/h2>\n
DocumentDB Local<\/strong><\/h4>\n
\n
DocumentDB for VS Code Extension<\/strong><\/h4>\n
\n
About Azure Cosmos DB<\/strong><\/h2>\n