Skills azure-cosmos-db-py
📦

azure-cosmos-db-py

Safe

Build Azure Cosmos DB Services with Python

Implement production-grade Azure Cosmos DB NoSQL services with proper authentication, clean architecture, and test-driven development. This skill provides templates and patterns for secure database integration in FastAPI applications.

Supports: Claude Codex Code(CC)
📊 71 Adequate
1

Download the skill ZIP

2

Upload in Claude

Go to Settings → Capabilities → Skills → Upload skill

3

Toggle on and start using

Test it

Using "azure-cosmos-db-py". Create a Cosmos DB client module with dual authentication

Expected outcome:

A complete cosmos.py file with get_container() singleton function, _is_emulator_endpoint() detection helper, and support for both DefaultAzureCredential and emulator key authentication modes.

Using "azure-cosmos-db-py". Build a ProjectService with CRUD operations

Expected outcome:

Service class with get_by_id, create, update, and delete methods using async wrappers, proper Pydantic model conversion, and graceful degradation returning None when Cosmos is unavailable.

Security Audit

Safe
v1 • 2/24/2026

All 37 static analysis findings are false positives. The scanned file (SKILL.md) is a documentation file containing code examples in markdown format, not executable code. External command detections are bash examples in documentation blocks. Network and environment variable references are configuration templates for Azure Cosmos DB connectivity. The skill demonstrates proper security practices including RBAC via DefaultAzureCredential, parameterized queries, and secure secret management.

1
Files scanned
245
Lines analyzed
0
findings
1
Total audits
No security issues found
Audited by: claude

Quality Score

38
Architecture
100
Maintainability
87
Content
31
Community
100
Security
91
Spec Compliance

What You Can Build

Backend Developer Building SaaS Application

Implement multi-tenant data storage using Cosmos DB with partition key isolation per workspace, leveraging DefaultAzureCredential for secure production deployment.

DevOps Engineer Setting Up Development Environment

Configure local development with Cosmos DB emulator, using environment variables for endpoint configuration and test fixtures for CI/CD pipelines.

Solution Architect Designing Cloud-Native Applications

Apply clean architecture patterns with repository and service layers, ensuring separation of business logic from database implementation for long-term maintainability.

Try These Prompts

Basic: Set Up Cosmos DB Client 
Create a Cosmos DB client module with singleton pattern that uses DefaultAzureCredential for production and emulator key for local development. Include SSL configuration and container initialization.
Intermediate: Create Service Layer 
Build a service class for Project entity with CRUD operations. Use five-tier Pydantic model pattern and implement graceful degradation when Cosmos DB is unavailable.
Advanced: Write Parameterized Queries 
Implement Cosmos DB SQL queries using @parameter syntax for filtering projects by workspace_id and name. Include proper error handling for CosmosResourceNotFoundError.
Expert: Set Up Testing Infrastructure 
Create pytest fixtures for mocking Cosmos DB container operations. Include async test examples for service layer methods with proper mocking of get_container function.

Best Practices

  • Always use DefaultAzureCredential in production environments - never hardcode keys or secrets in source code
  • Use parameterized queries with @parameter syntax to prevent SQL injection in Cosmos DB queries
  • Implement graceful degradation by returning None or empty lists when Cosmos DB is unavailable instead of throwing exceptions

Avoid

  • Hardcoding connection keys or secrets directly in source code instead of using environment variables or managed identity
  • Using string concatenation to build queries instead of parameterized query syntax with @parameter placeholders
  • Creating new CosmosClient instances per request instead of using singleton pattern for connection pooling

Frequently Asked Questions

What is the difference between DefaultAzureCredential and emulator key authentication?
DefaultAzureCredential uses managed identity or Azure CLI credentials for production environments with RBAC. Emulator key authentication uses a well-known key for local development only and should never be used in production.
How do I handle Cosmos DB unavailability gracefully?
Implement a _use_cosmos() check in your service layer that returns False when the container is None. Service methods return None for single items or empty lists for queries instead of raising exceptions.
Why use async wrappers for synchronous Cosmos SDK calls?
The Azure Cosmos DB Python SDK is synchronous. Using starlette's run_in_threadpool prevents blocking the FastAPI event loop, maintaining async performance characteristics.
What is the five-tier model pattern?
It uses ProjectBase for shared fields, ProjectCreate for creation requests, ProjectUpdate for partial updates, Project for API responses, and ProjectInDB for internal documents with docType metadata.
How do I choose a partition key for Cosmos DB?
Select a partition key that provides even data distribution and aligns with query patterns. For multi-tenant apps, workspace_id is common. Validate partition key access matches user authorization to enforce data boundaries.
Can I use this skill with other Azure Cosmos DB APIs like MongoDB or SQL?
This skill focuses specifically on the NoSQL API with native Cosmos SDK. MongoDB and SQL APIs require different client libraries and query patterns, though the service layer architecture principles remain applicable.

Developer Details

Author

sickn33

License

MIT

Repository

https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/azure-cosmos-db-py

Ref

main

File structure

📄 SKILL.md