# CosmosDB Isolation Utilities
A unified command-line interface for managing Azure CosmosDB databases in isolation environments. This tool consolidates multiple utilities into a single CLI with consistent parameter handling and a clean separation between the interface and core implementation.
## Features
- **Unified CLI**: Single command-line tool with subcommands for all operations
- **Connection Testing**: Test and validate CosmosDB connections
- **Container Management**: View status, statistics, and manage containers
- **Data Export/Import**: Dump containers to JSON and restore from JSON files
- **Database Operations**: List and manage databases
- **Rich Output**: Beautiful terminal output with progress bars and tables
- **Safety Features**: Confirmation prompts and dry-run modes for destructive operations
## Installation
### From Source
```bash
git clone <repository-url>
cd cosmos-isolation-utils
pip install -e .
```
### Dependencies
The tool requires the following Python packages:
- `azure-cosmos>=4.0.0` - Azure CosmosDB client
- `click>=8.0.0` - CLI framework
- `rich>=13.0.0` - Rich terminal output
- `urllib3>=1.26.0` - HTTP client
## Usage
The unified CLI tool provides several subcommands, all sharing common connection parameters:
```bash
cosmos-isolation-utils <subcommand> -e <endpoint> -k <key> -d <database> [options]
```
### Common Parameters
- `-e, --endpoint`: CosmosDB endpoint URL (required)
- `-k, --key`: CosmosDB primary key (required)
- `-d, --database`: CosmosDB database name (required)
- `-a, --allow-insecure`: Allow insecure HTTPS requests (suppress warnings)
### Subcommands
#### 1. Test Connection
Test the connection to a CosmosDB database and list available containers:
```bash
cosmos-isolation-utils test -e <endpoint> -k <key> -d <database> [options]
```
**Options:**
- `--create-database`: Create database if it doesn't exist
- `-f, --force`: Skip confirmation prompts
**Example:**
```bash
cosmos-isolation-utils test -e "https://your-cosmosdb.documents.azure.com:443/" \
-k "your-primary-key" \
-d "testdb" \
--create-database
```
#### 2. Container Status
View the status and statistics of all containers in a database:
```bash
cosmos-isolation-utils status -e <endpoint> -k <key> -d <database> [options]
```
**Options:**
- `--detailed`: Show detailed information for each container
**Example:**
```bash
cosmos-isolation-utils status -e "https://your-cosmosdb.documents.azure.com:443/" \
-k "your-primary-key" \
-d "testdb" \
--detailed
```
#### 3. Dump Containers
Export all entries from containers to a JSON file:
```bash
cosmos-isolation-utils dump -e <endpoint> -k <key> -d <database> [options]
```
**Options:**
- `-c, --containers`: Comma-separated list of container names or "all"
- `-o, --output`: Output JSON file path (required)
- `-b, --batch-size`: Batch size for processing (default: 100)
- `-p, --pretty`: Pretty print JSON output
**Examples:**
```bash
# Dump all containers
cosmos-isolation-utils dump -e "https://your-cosmosdb.documents.azure.com:443/" \
-k "your-primary-key" \
-d "testdb" \
-c all -o all_containers.json
# Dump specific containers
cosmos-isolation-utils dump -e "https://your-cosmosdb.documents.azure.com:443/" \
-k "your-primary-key" \
-d "testdb" \
-c "users,orders" -o selected_containers.json
# Dump with pretty formatting
cosmos-isolation-utils dump -e "https://your-cosmosdb.documents.azure.com:443/" \
-k "your-primary-key" \
-d "testdb" \
-c all -o all_containers.json -p
```
#### 4. Upload Entries
Restore containers from a JSON dump file:
```bash
cosmos-isolation-utils upload -e <endpoint> -k <key> -d <database> [options]
```
**Options:**
- `-i, --input`: Input JSON file path (required)
- `-b, --batch-size`: Batch size for processing (default: 100)
- `-u, --upsert`: Use upsert instead of create (overwrites existing items)
- `-r, --dry-run`: Show what would be uploaded without actually uploading
- `-f, --force`: Skip confirmation prompts
- `--create-containers`: Automatically create containers if they don't exist
- `-c, --containers`: Comma-separated list of specific containers to upload
**Examples:**
```bash
# Upload all containers from dump
cosmos-isolation-utils upload -e "https://your-cosmosdb.documents.azure.com:443/" \
-k "your-primary-key" \
-d "testdb" \
-i all_containers.json --create-containers
# Upload specific containers with dry-run
cosmos-isolation-utils upload -e "https://your-cosmosdb.documents.azure.com:443/" \
-k "your-primary-key" \
-d "testdb" \
-i all_containers.json -c "users,orders" --dry-run
```
#### 5. Database Management
List and manage databases:
```bash
cosmos-isolation-utils delete-db -e <endpoint> -k <key> -d <database> [options]
```
**Options:**
- `-l, --list-databases`: List all existing databases
- `-f, --force`: Skip confirmation prompts for deletion
**Examples:**
```bash
# List all databases
cosmos-isolation-utils delete-db -e "https://your-cosmosdb.documents.azure.com:443/" \
-k "your-primary-key" \
-d "testdb" \
-l
# Delete a database (with confirmation)
cosmos-isolation-utils delete-db -e "https://your-cosmosdb.documents.azure.com:443/" \
-k "your-primary-key" \
-d "testdb"
# Force delete a database (skip confirmation)
cosmos-isolation-utils delete-db -e "https://your-cosmosdb.documents.azure.com:443/" \
-k "your-primary-key" \
-d "testdb" \
-f
```
## Project Structure
```
cosmos-isolation-utils/
├── cosmos_isolation_utils/
│ ├── __init__.py
│ ├── __main__.py # Entry point for python -m
│ ├── __main__.py # CLI interface and subcommands
│ ├── cosmos_client.py # CosmosDB client wrapper
│ └── core/ # Core implementation logic
│ ├── __init__.py
│ ├── connection.py # Connection testing
│ ├── status.py # Container status
│ ├── dump.py # Container export
│ ├── upload.py # Container import
│ └── delete.py # Database deletion
├── tests/ # Test suite
├── pyproject.toml # Project configuration
└── README.md # This file
```
## Architecture
The tool follows a clean separation of concerns:
- **CLI Layer** (`__main__.py`): Handles command-line interface, parameter parsing, and user interaction
- **Core Layer** (`core/`): Contains the actual business logic for each operation
- **Client Layer** (`cosmos_client.py`): Provides a high-level interface to CosmosDB operations
This separation makes the code more maintainable and testable, while providing a consistent user experience across all operations.
## Development
### Setup Development Environment
```bash
# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install development dependencies
pip install -e ".[dev]"
```
### Running Tests
```bash
# Using unittest discover (recommended)
python -m unittest discover tests/ -v
# Using make
make test
# Run specific test file
python -m unittest tests.test_cli -v
# Run test file directly
python tests/test_cli.py -v
# Run tests with coverage
make test-cov
```
### Code Quality
The project uses:
- `pylint` for code quality checks
- `coverage` for test coverage
- `black` for code formatting
## Release Workflow
This project uses GitHub Actions with environment protection for secure package publishing to PyPI.
### Release Process
1. **Create Release Branch**: Push to a branch named `release/X.Y.Z` (e.g., `release/1.2.3`)
2. **Automated Checks**: The workflow runs tests, builds the package, and publishes to Test PyPI
3. **Test Publication**: Package is published to Test PyPI for validation
4. **Production Publication**: After successful test publication, package is published to Production PyPI
5. **Release Tag**: A Git tag is created for the release
### Environment Setup
The workflow requires two GitHub environments to be configured:
- **`test-pypi`**: For publishing to Test PyPI
- **`production-pypi`**: For publishing to Production PyPI
See [Environment Setup Guide](docs/environment-setup.md) for detailed configuration instructions.
### Security Features
- **Environment Protection**: Each environment requires approval from designated reviewers
- **Sequential Publishing**: Test publication must succeed before production publication
- **Secret Isolation**: PyPI credentials are scoped to specific environments
- **Approval Process**: Production releases require explicit approval with optional wait timers
## Command Reference
### Quick Command Overview
```bash
# Test connection and list containers
cosmos-isolation-utils test -e <endpoint> -k <key> -d <database> [--create-database] [-f]
# Show container status and statistics
cosmos-isolation-utils status -e <endpoint> -k <key> -d <database> [--detailed]
# Dump containers to JSON file
cosmos-isolation-utils dump -e <endpoint> -k <key> -d <database> -c <containers> -o <output> [-b <batch-size>] [-p]
# Upload containers from JSON file
cosmos-isolation-utils upload -e <endpoint> -k <key> -d <database> -i <input> [-c <containers>] [-b <batch-size>] [-u] [-r] [-f] [--create-containers]
# Manage databases
cosmos-isolation-utils delete-db -e <endpoint> -k <key> -d <database> [-l] [-f]
```
### Environment Variables
You can also set connection parameters via environment variables:
```bash
export COSMOS_ENDPOINT="https://your-cosmosdb.documents.azure.com:443/"
export COSMOS_KEY="your-primary-key"
export COSMOS_DATABASE="your-database"
# Then run commands without -e, -k, -d flags
cosmos-isolation-utils test
cosmos-isolation-utils status --detailed
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Support
For issues and questions, please use the GitHub issue tracker or contact the maintainers.
Raw data
{
"_id": null,
"home_page": null,
"name": "cosmos-isolation-utils",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Starforge Worker <star.forge.worker@gmail.com>",
"keywords": "cosmosdb, azure, database, testing, isolation, nosql",
"author": null,
"author_email": "Starforge Worker <star.forge.worker@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f0/f6/f94c3e8d6fd9aecd0b33ec490c68ffbb3ff27906222b1188dbd892eb2621/cosmos_isolation_utils-0.0.4.tar.gz",
"platform": null,
"description": "# CosmosDB Isolation Utilities\n\nA unified command-line interface for managing Azure CosmosDB databases in isolation environments. This tool consolidates multiple utilities into a single CLI with consistent parameter handling and a clean separation between the interface and core implementation.\n\n## Features\n\n- **Unified CLI**: Single command-line tool with subcommands for all operations\n- **Connection Testing**: Test and validate CosmosDB connections\n- **Container Management**: View status, statistics, and manage containers\n- **Data Export/Import**: Dump containers to JSON and restore from JSON files\n- **Database Operations**: List and manage databases\n- **Rich Output**: Beautiful terminal output with progress bars and tables\n- **Safety Features**: Confirmation prompts and dry-run modes for destructive operations\n\n## Installation\n\n### From Source\n\n```bash\ngit clone <repository-url>\ncd cosmos-isolation-utils\npip install -e .\n```\n\n### Dependencies\n\nThe tool requires the following Python packages:\n- `azure-cosmos>=4.0.0` - Azure CosmosDB client\n- `click>=8.0.0` - CLI framework\n- `rich>=13.0.0` - Rich terminal output\n- `urllib3>=1.26.0` - HTTP client\n\n## Usage\n\nThe unified CLI tool provides several subcommands, all sharing common connection parameters:\n\n```bash\ncosmos-isolation-utils <subcommand> -e <endpoint> -k <key> -d <database> [options]\n```\n\n### Common Parameters\n\n- `-e, --endpoint`: CosmosDB endpoint URL (required)\n- `-k, --key`: CosmosDB primary key (required)\n- `-d, --database`: CosmosDB database name (required)\n- `-a, --allow-insecure`: Allow insecure HTTPS requests (suppress warnings)\n\n### Subcommands\n\n#### 1. Test Connection\n\nTest the connection to a CosmosDB database and list available containers:\n\n```bash\ncosmos-isolation-utils test -e <endpoint> -k <key> -d <database> [options]\n```\n\n**Options:**\n- `--create-database`: Create database if it doesn't exist\n- `-f, --force`: Skip confirmation prompts\n\n**Example:**\n```bash\ncosmos-isolation-utils test -e \"https://your-cosmosdb.documents.azure.com:443/\" \\\n -k \"your-primary-key\" \\\n -d \"testdb\" \\\n --create-database\n```\n\n#### 2. Container Status\n\nView the status and statistics of all containers in a database:\n\n```bash\ncosmos-isolation-utils status -e <endpoint> -k <key> -d <database> [options]\n```\n\n**Options:**\n- `--detailed`: Show detailed information for each container\n\n**Example:**\n```bash\ncosmos-isolation-utils status -e \"https://your-cosmosdb.documents.azure.com:443/\" \\\n -k \"your-primary-key\" \\\n -d \"testdb\" \\\n --detailed\n```\n\n#### 3. Dump Containers\n\nExport all entries from containers to a JSON file:\n\n```bash\ncosmos-isolation-utils dump -e <endpoint> -k <key> -d <database> [options]\n```\n\n**Options:**\n- `-c, --containers`: Comma-separated list of container names or \"all\"\n- `-o, --output`: Output JSON file path (required)\n- `-b, --batch-size`: Batch size for processing (default: 100)\n- `-p, --pretty`: Pretty print JSON output\n\n**Examples:**\n```bash\n# Dump all containers\ncosmos-isolation-utils dump -e \"https://your-cosmosdb.documents.azure.com:443/\" \\\n -k \"your-primary-key\" \\\n -d \"testdb\" \\\n -c all -o all_containers.json\n\n# Dump specific containers\ncosmos-isolation-utils dump -e \"https://your-cosmosdb.documents.azure.com:443/\" \\\n -k \"your-primary-key\" \\\n -d \"testdb\" \\\n -c \"users,orders\" -o selected_containers.json\n\n# Dump with pretty formatting\ncosmos-isolation-utils dump -e \"https://your-cosmosdb.documents.azure.com:443/\" \\\n -k \"your-primary-key\" \\\n -d \"testdb\" \\\n -c all -o all_containers.json -p\n```\n\n#### 4. Upload Entries\n\nRestore containers from a JSON dump file:\n\n```bash\ncosmos-isolation-utils upload -e <endpoint> -k <key> -d <database> [options]\n```\n\n**Options:**\n- `-i, --input`: Input JSON file path (required)\n- `-b, --batch-size`: Batch size for processing (default: 100)\n- `-u, --upsert`: Use upsert instead of create (overwrites existing items)\n- `-r, --dry-run`: Show what would be uploaded without actually uploading\n- `-f, --force`: Skip confirmation prompts\n- `--create-containers`: Automatically create containers if they don't exist\n- `-c, --containers`: Comma-separated list of specific containers to upload\n\n**Examples:**\n```bash\n# Upload all containers from dump\ncosmos-isolation-utils upload -e \"https://your-cosmosdb.documents.azure.com:443/\" \\\n -k \"your-primary-key\" \\\n -d \"testdb\" \\\n -i all_containers.json --create-containers\n\n# Upload specific containers with dry-run\ncosmos-isolation-utils upload -e \"https://your-cosmosdb.documents.azure.com:443/\" \\\n -k \"your-primary-key\" \\\n -d \"testdb\" \\\n -i all_containers.json -c \"users,orders\" --dry-run\n```\n\n#### 5. Database Management\n\nList and manage databases:\n\n```bash\ncosmos-isolation-utils delete-db -e <endpoint> -k <key> -d <database> [options]\n```\n\n**Options:**\n- `-l, --list-databases`: List all existing databases\n- `-f, --force`: Skip confirmation prompts for deletion\n\n**Examples:**\n```bash\n# List all databases\ncosmos-isolation-utils delete-db -e \"https://your-cosmosdb.documents.azure.com:443/\" \\\n -k \"your-primary-key\" \\\n -d \"testdb\" \\\n -l\n\n# Delete a database (with confirmation)\ncosmos-isolation-utils delete-db -e \"https://your-cosmosdb.documents.azure.com:443/\" \\\n -k \"your-primary-key\" \\\n -d \"testdb\"\n\n# Force delete a database (skip confirmation)\ncosmos-isolation-utils delete-db -e \"https://your-cosmosdb.documents.azure.com:443/\" \\\n -k \"your-primary-key\" \\\n -d \"testdb\" \\\n -f\n```\n\n## Project Structure\n\n```\ncosmos-isolation-utils/\n\u251c\u2500\u2500 cosmos_isolation_utils/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 __main__.py # Entry point for python -m\n\u2502 \u251c\u2500\u2500 __main__.py # CLI interface and subcommands\n\u2502 \u251c\u2500\u2500 cosmos_client.py # CosmosDB client wrapper\n\u2502 \u2514\u2500\u2500 core/ # Core implementation logic\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 connection.py # Connection testing\n\u2502 \u251c\u2500\u2500 status.py # Container status\n\u2502 \u251c\u2500\u2500 dump.py # Container export\n\u2502 \u251c\u2500\u2500 upload.py # Container import\n\u2502 \u2514\u2500\u2500 delete.py # Database deletion\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u2514\u2500\u2500 README.md # This file\n```\n\n## Architecture\n\nThe tool follows a clean separation of concerns:\n\n- **CLI Layer** (`__main__.py`): Handles command-line interface, parameter parsing, and user interaction\n- **Core Layer** (`core/`): Contains the actual business logic for each operation\n- **Client Layer** (`cosmos_client.py`): Provides a high-level interface to CosmosDB operations\n\nThis separation makes the code more maintainable and testable, while providing a consistent user experience across all operations.\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Create and activate virtual environment\npython3 -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install development dependencies\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\n# Using unittest discover (recommended)\npython -m unittest discover tests/ -v\n\n# Using make\nmake test\n\n# Run specific test file\npython -m unittest tests.test_cli -v\n\n# Run test file directly\npython tests/test_cli.py -v\n\n# Run tests with coverage\nmake test-cov\n```\n\n### Code Quality\n\nThe project uses:\n- `pylint` for code quality checks\n- `coverage` for test coverage\n- `black` for code formatting\n\n## Release Workflow\n\nThis project uses GitHub Actions with environment protection for secure package publishing to PyPI.\n\n### Release Process\n\n1. **Create Release Branch**: Push to a branch named `release/X.Y.Z` (e.g., `release/1.2.3`)\n2. **Automated Checks**: The workflow runs tests, builds the package, and publishes to Test PyPI\n3. **Test Publication**: Package is published to Test PyPI for validation\n4. **Production Publication**: After successful test publication, package is published to Production PyPI\n5. **Release Tag**: A Git tag is created for the release\n\n### Environment Setup\n\nThe workflow requires two GitHub environments to be configured:\n\n- **`test-pypi`**: For publishing to Test PyPI\n- **`production-pypi`**: For publishing to Production PyPI\n\nSee [Environment Setup Guide](docs/environment-setup.md) for detailed configuration instructions.\n\n### Security Features\n\n- **Environment Protection**: Each environment requires approval from designated reviewers\n- **Sequential Publishing**: Test publication must succeed before production publication\n- **Secret Isolation**: PyPI credentials are scoped to specific environments\n- **Approval Process**: Production releases require explicit approval with optional wait timers\n\n## Command Reference\n\n### Quick Command Overview\n\n```bash\n# Test connection and list containers\ncosmos-isolation-utils test -e <endpoint> -k <key> -d <database> [--create-database] [-f]\n\n# Show container status and statistics\ncosmos-isolation-utils status -e <endpoint> -k <key> -d <database> [--detailed]\n\n# Dump containers to JSON file\ncosmos-isolation-utils dump -e <endpoint> -k <key> -d <database> -c <containers> -o <output> [-b <batch-size>] [-p]\n\n# Upload containers from JSON file\ncosmos-isolation-utils upload -e <endpoint> -k <key> -d <database> -i <input> [-c <containers>] [-b <batch-size>] [-u] [-r] [-f] [--create-containers]\n\n# Manage databases\ncosmos-isolation-utils delete-db -e <endpoint> -k <key> -d <database> [-l] [-f]\n```\n\n### Environment Variables\n\nYou can also set connection parameters via environment variables:\n\n```bash\nexport COSMOS_ENDPOINT=\"https://your-cosmosdb.documents.azure.com:443/\"\nexport COSMOS_KEY=\"your-primary-key\"\nexport COSMOS_DATABASE=\"your-database\"\n\n# Then run commands without -e, -k, -d flags\ncosmos-isolation-utils test\ncosmos-isolation-utils status --detailed\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass\n6. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Support\n\nFor issues and questions, please use the GitHub issue tracker or contact the maintainers. \n",
"bugtrack_url": null,
"license": null,
"summary": "Utilities for Azure CosmosDB isolation and testing",
"version": "0.0.4",
"project_urls": {
"Bug Tracker": "https://github.com/starforge-universe/cosmos-isolation-utils/issues",
"Documentation": "https://cosmos-isolation-utils.readthedocs.io/",
"Homepage": "https://github.com/starforge-universe/cosmos-isolation-utils",
"Repository": "https://github.com/starforge-universe/cosmos-isolation-utils"
},
"split_keywords": [
"cosmosdb",
" azure",
" database",
" testing",
" isolation",
" nosql"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "26f574de84ac6840114f294ed1664e5b704273e4053bca3aa43e88ce4f6cc23b",
"md5": "a491fce69fa1b450afbc74e0ec29e31d",
"sha256": "b28b208ef16eb36be4947924d1cb31d0546d7d0ee49ba25176ca9588d17b9a83"
},
"downloads": -1,
"filename": "cosmos_isolation_utils-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a491fce69fa1b450afbc74e0ec29e31d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 29289,
"upload_time": "2025-09-01T21:18:37",
"upload_time_iso_8601": "2025-09-01T21:18:37.751053Z",
"url": "https://files.pythonhosted.org/packages/26/f5/74de84ac6840114f294ed1664e5b704273e4053bca3aa43e88ce4f6cc23b/cosmos_isolation_utils-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f0f6f94c3e8d6fd9aecd0b33ec490c68ffbb3ff27906222b1188dbd892eb2621",
"md5": "cae9fdb0a2ae2693f96bb80ffc276a64",
"sha256": "566e0cb86002a76ee340870d70786a6c12d7bc5a6c08cbb55bc74b0e2ce652e7"
},
"downloads": -1,
"filename": "cosmos_isolation_utils-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "cae9fdb0a2ae2693f96bb80ffc276a64",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 23470,
"upload_time": "2025-09-01T21:18:38",
"upload_time_iso_8601": "2025-09-01T21:18:38.970026Z",
"url": "https://files.pythonhosted.org/packages/f0/f6/f94c3e8d6fd9aecd0b33ec490c68ffbb3ff27906222b1188dbd892eb2621/cosmos_isolation_utils-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 21:18:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "starforge-universe",
"github_project": "cosmos-isolation-utils",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cosmos-isolation-utils"
}
JSON
