What This Skill Does
The Azure Cosmos DB Python skill provides AI agents with production-grade patterns for implementing NoSQL database services using Microsoft's globally distributed database platform. Unlike basic SDK usage guides, this skill teaches architectural patterns, security best practices, and test-driven development approaches for building robust Cosmos DB integrations.
This skill emphasizes clean code architecture through a three-layer design: a singleton client module handling authentication and connections, service layer classes implementing business logic and model conversions, and Pydantic models ensuring type safety and validation. Agents learn to build maintainable database services that gracefully handle failures, support both cloud and emulator environments, and follow modern Python development practices.
The approach prioritizes security through role-based access control with DefaultAzureCredential, prevents SQL injection via parameterized queries, and enforces partition key isolation for multi-tenant applications. Combined with comprehensive testing patterns and performance optimization strategies, this skill enables agents to build enterprise-ready Cosmos DB services rather than throwaway prototypes.
Getting Started
Before implementing Cosmos DB services, ensure you have an Azure Cosmos DB account with a database and container created. For local development, install the Cosmos DB emulator which provides a compatible endpoint for testing without cloud costs. The skill supports seamless switching between emulator and production environments through configuration.
Install the azure-cosmos and azure-identity packages to access the client SDK and credential providers. The identity package enables DefaultAzureCredential, which automatically discovers credentials from Azure CLI, managed identities, or environment variables depending on your runtime environment.
Environment variables configure your Cosmos endpoint, database name, container ID, and optionally the emulator key for local development. This configuration approach separates deployment concerns from application code, enabling the same codebase to run locally and in production.
The skill's architecture starts with a singleton client module that initializes the Cosmos container client once and reuses it across requests. This module detects emulator endpoints automatically and applies appropriate SSL verification settings, providing dual authentication support without cluttering your service layer code.
Key Features
Dual Authentication Strategy — Automatically selects DefaultAzureCredential for Azure deployments or key-based authentication for local emulator environments. Detection happens based on endpoint URLs, enabling developers to switch between environments by changing configuration without code modifications.
Five-Tier Model Pattern — Separates concerns through distinct Pydantic model classes: Base models contain shared fields, Create models define creation requests, Update models allow partial modifications, standard models represent API responses, and InDB models include internal fields like document types. This hierarchy enables schema evolution and clear API contracts.
Service Layer Architecture — Encapsulates all database operations within service classes that handle business logic, document-to-model conversions, error handling, and graceful degradation. Services provide clean interfaces to routers while isolating Cosmos-specific code for easier testing and maintenance.
Graceful Degradation — Services check container availability before operations and return None or empty lists when Cosmos is unavailable rather than crashing. This pattern enables applications to function partially during database outages, providing better user experiences than hard failures.
Partition Key Strategies — Guides proper partition key selection and enforcement for multi-tenant scenarios. Services validate that partition keys match user authorization, preventing cross-tenant data leakage and ensuring queries remain efficient by avoiding expensive cross-partition operations.
Async Compatibility — Wraps synchronous Cosmos SDK calls with run_in_threadpool to prevent blocking FastAPI's event loop. This approach maintains async benefits in web frameworks while working with the current SDK's synchronous interface.
Test-Driven Development — Provides comprehensive testing patterns using pytest and mocking frameworks. Fixtures simplify Cosmos container mocking, enabling unit tests to run quickly without real database connections while integration tests validate against emulator environments.
Usage Examples
Creating the client module establishes your database connection infrastructure. The module exports a get_container function that returns a singleton container client, initializing it on first access. Endpoint detection logic chooses between credential types automatically based on whether the URL references localhost.
Defining Pydantic models creates your data contracts. Start with base models containing common fields, then extend for creation, update, and response scenarios. Use Field aliases to map between Python's snake_case conventions and JSON's camelCase standards. Include validation rules like minimum lengths or format constraints to enforce data quality.
Service classes implement your database operations following single-responsibility principles. Methods like get_by_id retrieve documents by ID and partition key, converting Cosmos documents to Pydantic models. Create methods accept model instances, convert to document dictionaries, and insert into Cosmos. Update methods merge partial changes with existing documents.
Document conversion methods transform between Cosmos's dictionary format and your Pydantic models. The doc_to_model method validates incoming data against your schema and handles missing or extra fields gracefully. The model_to_doc method serializes models to dictionaries, excluding None values and adding internal fields like document types.
Testing follows arrange-act-assert patterns with comprehensive mocking. Fixtures create mock container clients that intercept Cosmos calls. Tests arrange mock return values, act by calling service methods, and assert both the returned results and that mocks received expected calls. This approach validates logic without requiring running databases.
Best Practices
Always use DefaultAzureCredential for authentication in Azure deployments rather than embedding access keys in code or environment variables. Managed identities enable applications running in Azure to authenticate without credential management, while Azure CLI credentials support local development seamlessly. Reserve key-based authentication exclusively for the emulator's well-known public key.
Parameterize all queries using the parameter syntax rather than string concatenation or interpolation. Cosmos DB's parameterized queries prevent injection attacks and improve query plan caching. Pass query values as separate parameter dictionaries rather than embedding them in query strings.
Validate partition key values match user authorization before executing queries. In multi-tenant applications, partition keys often represent workspace or organization IDs. Services should verify that authenticated users have access to requested partition key values, preventing unauthorized cross-tenant data access.
Implement graceful degradation in services by checking container availability before operations. When Cosmos is unavailable during startup or experiences transient failures, return null or empty results rather than propagating exceptions. Log degraded operation warnings for monitoring while maintaining application functionality.
Choose partition keys carefully based on access patterns and cardinality. Good partition keys distribute data evenly, appear in most query filters, and align with authorization boundaries. Avoid partition keys with few unique values that create hot partitions or keys requiring frequent cross-partition queries that hurt performance.
Write tests before implementing service methods following test-driven development principles. Define expected behavior through tests first, then implement code to satisfy tests. This approach catches edge cases early, documents intended behavior, and prevents regressions as features evolve.
Use async/await consistently even though Cosmos SDK currently provides synchronous methods. Wrap synchronous calls with run_in_threadpool to maintain FastAPI's async benefits. This future-proofs code for when SDK adds native async support and prevents blocking event loops.
When to Use This Skill
Use this skill when building web APIs or services that need flexible schema storage with global distribution capabilities. Applications requiring low-latency database access across multiple regions benefit from Cosmos DB's replication features, while this skill's patterns ensure implementations follow production-ready practices.
Multi-tenant SaaS applications leverage partition key strategies for tenant isolation and query efficiency. User profile services, session stores, catalog systems, and configuration management all fit Cosmos DB's document model naturally, and this skill's service layer patterns provide clean implementation templates.
Projects emphasizing test-driven development benefit from the mocking and testing patterns. Applications built with FastAPI or other async Python frameworks gain from the async compatibility guidance. Teams prioritizing security appreciate the DefaultAzureCredential integration and parameterized query requirements.
Development teams working across local and cloud environments value the dual authentication strategy that seamlessly switches between emulator and production. The graceful degradation patterns help build resilient applications that handle database unavailability appropriately.
When NOT to Use This Skill
Avoid this skill for simple scripts or one-off data migrations where architectural patterns add unnecessary complexity. Basic SDK usage without service layers suffices for utility scripts, admin tools, or prototypes that won't evolve into production services.
Don't use Cosmos DB for workloads requiring complex joins, transactions across documents, or strict ACID guarantees across multiple entities. Relational databases better serve normalized data models with complex relationships. This skill can't overcome Cosmos DB's document-oriented design.
Skip the five-tier model pattern for simple CRUD applications with static schemas and minimal business logic. The pattern's benefits emerge when schemas evolve, APIs have different internal and external representations, or validation requirements differ across operations. Simple applications may find three tiers sufficient.
Avoid Cosmos DB for primarily append-only workloads like logging or time-series data where Azure Data Explorer or Application Insights provide better performance and cost efficiency. While Cosmos can store such data, specialized services optimize for those patterns.
Related Skills
Explore azure-cosmos-java for implementing similar patterns in Java applications, maintaining consistency in architecture across polyglot microservices.
Check azure-identity-py for deeper understanding of credential providers, managed identities, and authentication patterns that support the client module's dual authentication strategy.
Consider azure-functions-py for serverless implementations that consume Cosmos DB services, leveraging managed identities and container-based triggers for event-driven architectures.
Source
Provider: Microsoft
Category: Cloud & Azure
Package: azure-cosmos
Official Documentation: Azure Cosmos DB SDK for Python