# db-contrib-tool
The `db-contrib-tool` - MongoDB's tools for contributors.
## Table of contents
- [db-contrib-tool](#db-contrib-tool)
- [Table of contents](#table-of-contents)
- [Description](#description)
- [Dependencies](#dependencies)
- [Installation](#installation)
- [Usage](#usage)
- [Contributor's Guide (local development)](#contributors-guide-local-development)
- [Install project dependencies](#install-project-dependencies)
- [Run command line tool (local development)](#run-command-line-tool-local-development)
- [Run linters](#run-linters)
- [Run tests](#run-tests)
- [Pre-commit](#pre-commit)
- [Testing changes in mongo](#testing-changes-in-mongo)
- [Testing changes locally](#testing-changes-locally)
- [Versioning](#versioning)
- [Code Review](#code-review)
- [Deployment](#deployment)
## Description
The command line tool with various subcommands:
- `bisect`
- [README.md](src/db_contrib_tool/evg_aware_bisect/README.md)
- performs an evergreen-aware git-bisect to find the 'last passing version' and 'first failing version' of mongo
- `setup-repro-env`
- [README.md](src/db_contrib_tool/setup_repro_env/README.md)
- downloads and installs:
- particular MongoDB versions
- debug symbols
- artifacts (including resmoke, python scripts etc)
- python venv for resmoke, python scripts etc
- `symbolize`
- [README.md](src/db_contrib_tool/symbolizer/README.md)
- Symbolizes stacktraces from recent `mongod` and `mongos` binaries compiled in Evergreen, including patch builds, mainline builds, and release/production builds.
- Requires authenticating to an internal MongoDB symbol mapping service.
## Dependencies
- Python 3.9 or later (python3 from the [MongoDB Toolchain](https://github.com/10gen/toolchain-builder/blob/master/INSTALL.md) is highly recommended)
## Installation
Make sure [dependencies](#dependencies) are installed.
Use [pipx](https://pypa.github.io/pipx/) to install db-contrib-tool that will be available globally on your machine:
```bash
python3 -m pip install pipx
python3 -m pipx ensurepath
```
Installing db-contrib-tool:
```bash
python3 -m pipx install db-contrib-tool
```
Upgrading db-contrib-tool:
```bash
python3 -m pipx upgrade db-contrib-tool
```
In case of installation errors, some of them may be related to pipx and could be fixed by re-installing pipx.
Removing pipx completely (WARNING! This will delete everything that is installed and managed by pipx):
```bash
python3 -m pip uninstall pipx
rm -rf ~/.local/pipx # in case you're using the default pipx home directory
```
Now you can try to install again from scratch.
## Usage
Print out help message:
```bash
db-contrib-tool --help
```
For more information see [description](#description) section.
## Contributor's Guide (local development)
### Install project dependencies
This project uses [poetry](https://python-poetry.org/) for dependency management.
```bash
poetry install
```
### Run command line tool (local development)
Some subcommands like `bisect` and `symbolize` could be tested from the db-contrib-tool repo root:
```bash
poetry run db-contrib-tool --help
```
For `setup-repro-env` some features can also be tested from the db-contrib-tool repo root,
but full features are available when running from mongo repo root.
See [testing changes locally](#testing-changes-locally) section.
### Run linters
```bash
poetry run ruff format
poetry run ruff check
```
### Run tests
```bash
poetry run pytest
```
### Pre-commit
This project has [pre-commit](https://pre-commit.com/) configured. Pre-commit will run
configured checks at git commit time.<br>
To enable pre-commit on your local repository run:
```bash
poetry run pre-commit install
```
To run pre-commit manually:
```bash
poetry run pre-commit run
```
or across all files (not just those staged):
```bash
poetry run pre-commit run --all-files
```
### Testing changes in mongo
This tool is used to help run tests in the mongodb/mongo repository. On occasion, it may be
desirable to run a mongodb-mongo-* patch build with in-flight changes to this repository. The
following steps can be taken to accomplish that.
- Create a patch build with the changes you wish to test, running the `create_pyinstaller_binary` tasks.
- In the `mongo` repository, edit [evergreen/download_db_contrib_tool.py](https://github.com/10gen/mongo/blob/2a3cf647ce2b4e64d8b5001f50e00620114425c8/evergreen/download_db_contrib_tool.py#L17) to use your patch's Evergreen
version, like `https://mdb-build-public.s3.amazonaws.com/db-contrib-tool-binaries/<your patch's version ID>/"`
### Testing changes locally
Pipx installation recommendations can be found in [installation](#installation) section.
The tool can be installed via pipx from your local repo:
```bash
python3 -m pipx install /path/to/db-contrib-tool/repo/root/dir
```
If the tool is already installed you can force install an updated version using --force flag:
```bash
python3 -m pipx install --force /path/to/db-contrib-tool/repo/root/dir
```
After these steps you can run in-development version of db-contrib-tool from any directory:
```bash
db-contrib-tool --help
```
### Versioning
This project uses [semver](https://semver.org/) for versioning.
Please include a description what is added for each new version in `CHANGELOG.md`.
### Code Review
This projects uses GitHub PRs for code reviews. You should assign any reviewers you would like to look at the PR to it.
This project uses the GitHub merge queue. Click "Merge when ready" as soon as you'd like.
### Deployment
Deployment to pypi is done by [deploy](https://spruce.mongodb.com/commits/db-contrib-tool?taskNames=deploy)
task of `db-contrib-tool` project in Evergreen.
A new version in Evergreen is created on merges to `main` branch.
Raw data
{
"_id": null,
"home_page": "https://github.com/10gen/db-contrib-tool",
"name": "db-contrib-tool",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.9",
"maintainer_email": null,
"keywords": null,
"author": "DAG team",
"author_email": "dev-prod-dag@mongodb.com",
"download_url": "https://files.pythonhosted.org/packages/88/4e/986c1028a95f52aaafd7a74fddca298b223daf02935e4e86a888c6554ede/db_contrib_tool-1.1.5.tar.gz",
"platform": null,
"description": "# db-contrib-tool\n\nThe `db-contrib-tool` - MongoDB's tools for contributors.\n\n## Table of contents\n\n- [db-contrib-tool](#db-contrib-tool)\n - [Table of contents](#table-of-contents)\n - [Description](#description)\n - [Dependencies](#dependencies)\n - [Installation](#installation)\n - [Usage](#usage)\n - [Contributor's Guide (local development)](#contributors-guide-local-development)\n - [Install project dependencies](#install-project-dependencies)\n - [Run command line tool (local development)](#run-command-line-tool-local-development)\n - [Run linters](#run-linters)\n - [Run tests](#run-tests)\n - [Pre-commit](#pre-commit)\n - [Testing changes in mongo](#testing-changes-in-mongo)\n - [Testing changes locally](#testing-changes-locally)\n - [Versioning](#versioning)\n - [Code Review](#code-review)\n - [Deployment](#deployment)\n\n## Description\n\nThe command line tool with various subcommands:\n- `bisect`\n - [README.md](src/db_contrib_tool/evg_aware_bisect/README.md)\n - performs an evergreen-aware git-bisect to find the 'last passing version' and 'first failing version' of mongo\n- `setup-repro-env`\n - [README.md](src/db_contrib_tool/setup_repro_env/README.md)\n - downloads and installs:\n - particular MongoDB versions\n - debug symbols\n - artifacts (including resmoke, python scripts etc)\n - python venv for resmoke, python scripts etc\n- `symbolize`\n - [README.md](src/db_contrib_tool/symbolizer/README.md)\n - Symbolizes stacktraces from recent `mongod` and `mongos` binaries compiled in Evergreen, including patch builds, mainline builds, and release/production builds.\n - Requires authenticating to an internal MongoDB symbol mapping service.\n\n## Dependencies\n\n- Python 3.9 or later (python3 from the [MongoDB Toolchain](https://github.com/10gen/toolchain-builder/blob/master/INSTALL.md) is highly recommended)\n\n## Installation\n\nMake sure [dependencies](#dependencies) are installed.\nUse [pipx](https://pypa.github.io/pipx/) to install db-contrib-tool that will be available globally on your machine:\n\n```bash\npython3 -m pip install pipx\npython3 -m pipx ensurepath\n```\n\nInstalling db-contrib-tool:\n\n```bash\npython3 -m pipx install db-contrib-tool\n```\n\nUpgrading db-contrib-tool:\n\n```bash\npython3 -m pipx upgrade db-contrib-tool\n```\n\nIn case of installation errors, some of them may be related to pipx and could be fixed by re-installing pipx.\n\nRemoving pipx completely (WARNING! This will delete everything that is installed and managed by pipx):\n\n```bash\npython3 -m pip uninstall pipx\nrm -rf ~/.local/pipx # in case you're using the default pipx home directory\n```\n\nNow you can try to install again from scratch.\n\n## Usage\n\nPrint out help message:\n\n```bash\ndb-contrib-tool --help\n```\n\nFor more information see [description](#description) section.\n\n## Contributor's Guide (local development)\n\n### Install project dependencies\n\nThis project uses [poetry](https://python-poetry.org/) for dependency management.\n\n```bash\npoetry install\n```\n\n### Run command line tool (local development)\n\nSome subcommands like `bisect` and `symbolize` could be tested from the db-contrib-tool repo root:\n\n```bash\npoetry run db-contrib-tool --help\n```\n\nFor `setup-repro-env` some features can also be tested from the db-contrib-tool repo root,\nbut full features are available when running from mongo repo root.\nSee [testing changes locally](#testing-changes-locally) section.\n\n### Run linters\n\n```bash\npoetry run ruff format\npoetry run ruff check\n```\n\n### Run tests\n\n```bash\npoetry run pytest\n```\n\n### Pre-commit\n\nThis project has [pre-commit](https://pre-commit.com/) configured. Pre-commit will run\nconfigured checks at git commit time.<br>\nTo enable pre-commit on your local repository run:\n```bash\npoetry run pre-commit install\n```\n\nTo run pre-commit manually:\n```bash\npoetry run pre-commit run\n```\nor across all files (not just those staged):\n```bash\npoetry run pre-commit run --all-files\n```\n\n### Testing changes in mongo\n\nThis tool is used to help run tests in the mongodb/mongo repository. On occasion, it may be\ndesirable to run a mongodb-mongo-* patch build with in-flight changes to this repository. The\nfollowing steps can be taken to accomplish that.\n\n- Create a patch build with the changes you wish to test, running the `create_pyinstaller_binary` tasks.\n- In the `mongo` repository, edit [evergreen/download_db_contrib_tool.py](https://github.com/10gen/mongo/blob/2a3cf647ce2b4e64d8b5001f50e00620114425c8/evergreen/download_db_contrib_tool.py#L17) to use your patch's Evergreen\nversion, like `https://mdb-build-public.s3.amazonaws.com/db-contrib-tool-binaries/<your patch's version ID>/\"`\n\n### Testing changes locally\n\nPipx installation recommendations can be found in [installation](#installation) section.\n\nThe tool can be installed via pipx from your local repo:\n\n```bash\npython3 -m pipx install /path/to/db-contrib-tool/repo/root/dir\n```\n\nIf the tool is already installed you can force install an updated version using --force flag:\n\n```bash\npython3 -m pipx install --force /path/to/db-contrib-tool/repo/root/dir\n```\n\nAfter these steps you can run in-development version of db-contrib-tool from any directory:\n\n```bash\ndb-contrib-tool --help\n```\n\n### Versioning\n\nThis project uses [semver](https://semver.org/) for versioning.\nPlease include a description what is added for each new version in `CHANGELOG.md`.\n\n### Code Review\n\nThis projects uses GitHub PRs for code reviews. You should assign any reviewers you would like to look at the PR to it.\n\nThis project uses the GitHub merge queue. Click \"Merge when ready\" as soon as you'd like.\n\n### Deployment\n\nDeployment to pypi is done by [deploy](https://spruce.mongodb.com/commits/db-contrib-tool?taskNames=deploy)\ntask of `db-contrib-tool` project in Evergreen.\nA new version in Evergreen is created on merges to `main` branch.\n",
"bugtrack_url": null,
"license": null,
"summary": "The `db-contrib-tool` - MongoDB's tool for contributors.",
"version": "1.1.5",
"project_urls": {
"Homepage": "https://github.com/10gen/db-contrib-tool",
"Repository": "https://github.com/10gen/db-contrib-tool"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b41062967411076ef0ade08fc17271bdf98221a003502fb977d65fcbef885e89",
"md5": "bab869e2a070ce4e55c065446bcefc54",
"sha256": "a08dc79d7816d8c49e487831c1e77aef44750c5c713093099da3085d616f77d2"
},
"downloads": -1,
"filename": "db_contrib_tool-1.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bab869e2a070ce4e55c065446bcefc54",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.9",
"size": 70226,
"upload_time": "2025-07-11T20:59:35",
"upload_time_iso_8601": "2025-07-11T20:59:35.938926Z",
"url": "https://files.pythonhosted.org/packages/b4/10/62967411076ef0ade08fc17271bdf98221a003502fb977d65fcbef885e89/db_contrib_tool-1.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "884e986c1028a95f52aaafd7a74fddca298b223daf02935e4e86a888c6554ede",
"md5": "40ce3a2cc9ef28d13ce44211d0156aee",
"sha256": "e48d64c4117e3c5d1280336d19f75395f47cb61b7b28076c9c531324ce2d583a"
},
"downloads": -1,
"filename": "db_contrib_tool-1.1.5.tar.gz",
"has_sig": false,
"md5_digest": "40ce3a2cc9ef28d13ce44211d0156aee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.9",
"size": 56134,
"upload_time": "2025-07-11T20:59:37",
"upload_time_iso_8601": "2025-07-11T20:59:37.299386Z",
"url": "https://files.pythonhosted.org/packages/88/4e/986c1028a95f52aaafd7a74fddca298b223daf02935e4e86a888c6554ede/db_contrib_tool-1.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 20:59:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "10gen",
"github_project": "db-contrib-tool",
"github_not_found": true,
"lcname": "db-contrib-tool"
}
JSON
