Lightweight Cosmos DB emulator
Go to file
Pijus Kamandulis 0cec7816c1 Fixed authentication key generation for partition key ranges
Fixed collection rid generation

Improved compatibility with SDKs
2024-06-01 02:32:52 +03:00
.github Added Docker to releaser configuration 2024-04-06 19:07:14 +03:00
api Fixed authentication key generation for partition key ranges 2024-06-01 02:32:52 +03:00
docs Implement OFFSET LIMIT 2024-03-11 22:09:55 +02:00
internal Fixed authentication key generation for partition key ranges 2024-06-01 02:32:52 +03:00
parsers Implement OFFSET LIMIT 2024-03-11 22:09:55 +02:00
query_executors/memory_executor Implement OFFSET LIMIT 2024-03-11 22:09:55 +02:00
.gitignore Implement STRINGEQUALS 2024-02-18 22:37:09 +02:00
.goreleaser.yaml Fix docker tags 2024-04-06 19:14:37 +03:00
Dockerfile Added Docker to releaser configuration 2024-04-06 19:07:14 +03:00
LICENSE Added README 2024-02-25 23:27:21 +02:00
Makefile Generate legit ResourceIds for SDK compatibility 2024-02-26 21:03:47 +02:00
README.md Added Docker to releaser configuration 2024-04-06 19:07:14 +03:00
go.mod Code cleanup; Implement persistant storage; Use maps for storage 2024-02-25 22:20:11 +02:00
go.sum Code cleanup; Implement persistant storage; Use maps for storage 2024-02-25 22:20:11 +02:00
main.go Load state from '-Persist' path if '-InitialData' not supplied 2024-02-27 22:11:33 +02:00

README.md

Cosmium

Cosmium is a lightweight Cosmos DB emulator designed to facilitate local development and testing. While it aims to provide developers with a solution for running a local database during development, it's important to note that it's not 100% compatible with Cosmos DB. However, it serves as a convenient tool for E2E or integration tests during the CI/CD pipeline. Read more about compatibility here.

One of Cosmium's notable features is its ability to save and load state to a single JSON file. This feature makes it easy to load different test cases or share state with other developers, enhancing collaboration and efficiency in development workflows.

Getting Started

Installation via Homebrew

You can install Cosmium using Homebrew by adding the pikami/brew tap and then installing the package.

brew tap pikami/brew
brew install cosmium

This will download and install Cosmium on your system, making it easy to manage and update using Homebrew.

Downloading Cosmium Binaries

You can download the latest version of Cosmium from the GitHub Releases page. Choose the appropriate release for your operating system and architecture.

Supported Platforms

Cosmium is available for the following platforms:

  • Linux: cosmium-linux-amd64
  • macOS: cosmium-darwin-amd64
  • macOS on Apple Silicon: cosmium-darwin-arm64
  • Windows: cosmium-windows-amd64.exe

Running Cosmium

Once downloaded, you can launch Cosmium using the following command:

cosmium -Persist "./save.json"

Connection String Example:

AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;

Running Cosmos DB Explorer

If you want to run Cosmos DB Explorer alongside Cosmium, you'll need to build it yourself and point the -ExplorerDir argument to the dist directory. Please refer to the Cosmos DB Explorer repository for instructions on building the application.

Once running, the explorer can be reached by navigating following URL: https://127.0.0.1:8081/_explorer/ (might be different depending on your configuration).

Running with docker (optional)

If you wan to run the application using docker, configure it using environment variables see example:

docker run --rm \
  -e Persist=/save.json \
  -v ./save.json:/save.json \
  -p 8081:8081 \
  ghcr.io/pikami/cosmium

SSL Certificate

By default, Cosmium uses a pre-generated SSL certificate. You can provide your own certificates by specifying paths to the SSL certificate and key (PEM format) using the -Cert and -CertKey arguments, respectively.

To disable SSL and run Cosmium on HTTP instead, you can use the -DisableTls flag. However most applications will require HTTPS.

Other Available Arguments

  • -AccountKey: Account key for authentication (default "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==")
  • -DisableAuth: Disable authentication
  • -Host: Hostname (default "localhost")
  • -InitialData: Path to JSON containing initial state
  • -Persist: Saves data to the given path on application exit (When -InitialData argument is not supplied, it will try to load data from path supplied in -Persist)
  • -Port: Listen port (default 8081)
  • -Debug: Runs application in debug mode, this provides additional logging

These arguments allow you to configure various aspects of Cosmium's behavior according to your requirements.

All mentioned arguments can also be set using environment variables:

  • COSMIUM_ACCOUNTKEY for -AccountKey
  • COSMIUM_DISABLEAUTH for -DisableAuth
  • COSMIUM_HOST for -Host
  • COSMIUM_INITIALDATA for -InitialData
  • COSMIUM_PERSIST for -Persist
  • COSMIUM_PORT for -Port
  • COSMIUM_DEBUG for -Debug

License

This project is MIT licensed.