Shared database throughput is a Cosmos DB option where several containers draw from one database-level pool of request units. Instead of giving every container its own reserved RU/s, the database has a shared budget. This can reduce cost for many quiet containers, but it also means one busy container can affect others. It is useful for advanced or transitional scenarios where predictable per-container performance is less important than simpler provisioning. For most production workloads with distinct traffic patterns, dedicated container throughput is the safer and clearer design.
Cosmos DB shared database throughput, database-level throughput, shared RU/s database, Cosmos DB database throughput, shared throughput database
Difficulty
intermediate
CLI mappings
5
Last verified
2026-05-24
Microsoft Learn
Shared database throughput in Azure Cosmos DB means RU/s are provisioned at the database level and shared by containers in that database. Microsoft recommends container-level throughput for most workloads because shared throughput can create unpredictable performance and scale behavior across containers.
Technically, shared database throughput is provisioned on an Azure Cosmos DB database. Containers created under that database can consume the shared RU/s unless they are created with dedicated container throughput. The setting sits in the Cosmos DB data platform and affects partitioning, rate limiting, metrics, cost, autoscale or manual throughput, and capacity planning. Operators inspect database throughput, container list, partition keys, normalized RU consumption, throttled requests, storage growth, and whether any container has its own throughput. It is a database-level performance and billing decision, not just a naming convention.
Why it matters
Shared database throughput matters because it looks economical and simple, but it changes workload isolation. A set of low-volume containers may run cheaply from one RU/s pool, yet a sudden burst from one tenant, feature, import job, or bad partition key can throttle other containers. Microsoft now recommends container-level throughput for most workloads because dedicated capacity gives more predictable performance and cleaner scaling. Shared database throughput still has a place in migrations, low-traffic deployment stamps, and advanced multitenant designs where teams understand the tradeoffs. The important lesson is to connect the throughput model to business impact. If one container's behavior must not harm another, shared throughput is probably the wrong default. That is why the model needs explicit graduation criteria early.
⌁
Where you see it
Signals, screens, and Azure surfaces where this term usually becomes operational.
Signal 01
In the Cosmos DB database scale settings, throughput appears on the database rather than on each container, indicating a shared RU/s pool for containers. during capacity planning reviews. during capacity planning reviews.
Signal 02
In Azure CLI output, database throughput show returns the pool configuration while container throughput show may be absent for shared containers during isolation reviews. during architecture reviews. before migrations. before scale changes are approved.
Signal 03
In Azure Monitor metrics, throttled requests or normalized RU consumption can reveal one container pressuring the shared database throughput pool during traffic bursts. during throttling investigations and reviews. during incident triage and reviews.
✦
When this becomes relevant
Specific situations where this term helps solve real Azure design, operations, migration, security, reliability, cost, or governance problems.
Run many low-traffic Cosmos DB containers in one database when dedicated minimum RU/s per container would waste budget.
Support an early migration from clustered NoSQL collections while traffic stabilizes before choosing dedicated container throughput.
Operate low-volume deployment stamps where tenant containers are quiet and predictable enough to share capacity temporarily.
Investigate noisy-neighbor throttling when one container's burst affects other containers in the same database.
Decide when a growing container should move from shared database throughput to dedicated container throughput for isolation.
◆
Real-world case studies
Different enterprise-style examples that show the term being used to hit measurable objectives.
Case study 01
IoT pilot pools quiet device containers before scale-up
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
A building automation vendor piloted Cosmos DB for 40 small customer sites. Each site used its own container, but most sent only intermittent thermostat and occupancy events during the first rollout.
🎯Business/Technical Objectives
Keep the pilot affordable while maintaining separate customer containers.
Detect noisy sites before they affected the rest of the pool.
Define when a customer container should move to dedicated throughput.
Avoid overengineering capacity before real traffic was known.
✅Solution Using Shared database throughput
The architecture team created a shared-throughput Cosmos DB database for pilot containers and documented that it was a temporary pooling model. Azure CLI scripts showed database throughput, listed containers, and exported partition-key information before each customer onboarding. Azure Monitor alerts watched normalized RU consumption and throttled requests by container. When one site began sending high-frequency telemetry after a firmware change, operators identified it as the noisy neighbor, moved that customer to a dedicated-throughput container, and left the quiet sites in the shared pool. The pilot review included cost and throttling data before the product team chose its standard production model.
📈Results & Business Impact
Pilot RU/s spend was 61 percent lower than assigning dedicated minimum throughput to every site.
The noisy firmware site was isolated within 45 minutes of the first 429 alert.
Thirty-six low-volume sites remained in the shared pool with no customer-visible latency breach.
The production design adopted dedicated throughput for sites exceeding a defined event-rate threshold.
💡Key Takeaway for Glossary Readers
Shared database throughput can be a smart pilot tool when monitoring and exit criteria are in place before real scale arrives.
Case study 02
Publishing group stabilizes a NoSQL migration
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
A digital publishing group migrated dozens of legacy collections from a self-hosted MongoDB cluster to Azure Cosmos DB. Traffic patterns were unclear because old reporting mixed all collection activity together.
🎯Business/Technical Objectives
Move collections quickly without guessing dedicated RU/s for each one.
Measure real Cosmos DB request-unit demand after migration.
Prevent high-traffic editorial workloads from starving archive workloads.
Create a staged plan for container-level throughput.
✅Solution Using Shared database throughput
The migration team initially used shared database throughput for groups of low-risk containers that came from the same legacy cluster. Azure CLI created the databases, set database-level throughput, and exported container inventory after each migration wave. For the first month, dashboards tracked RU consumption, throttled requests, and query latency per container. Two editorial-search containers showed bursty fan-out queries during publishing deadlines, so they were recreated with dedicated throughput and optimized partition keys. Archive and reference containers stayed in the shared database because their usage remained low and predictable. The team documented which collections were temporary shared candidates and which required isolation.
📈Results & Business Impact
Initial migration capacity planning time dropped by 40 percent because teams did not size every container upfront.
Deadline-hour throttling on editorial containers fell by 93 percent after dedicated throughput migration.
Low-use archive containers stayed 54 percent cheaper than the dedicated-throughput estimate.
The migration board received per-container RU evidence instead of relying on legacy cluster averages.
💡Key Takeaway for Glossary Readers
Shared database throughput can simplify migration discovery, but real traffic data should quickly decide which containers deserve dedicated capacity.
Case study 03
SaaS platform tunes low-traffic deployment stamps
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
A compliance SaaS provider used deployment stamps for small regional customer groups. Early stamps had many tenant containers, but most tenants logged in only during monthly evidence collection windows.
🎯Business/Technical Objectives
Reduce minimum Cosmos DB spend for quiet regional stamps.
Protect larger tenants from monthly evidence-upload bursts.
Give operations a repeatable way to review noisy-neighbor risk.
Keep tenant data separated while capacity remained pooled.
✅Solution Using Shared database throughput
The platform team used shared database throughput for new low-traffic stamps and dedicated throughput for established high-volume tenants. CLI inventory jobs listed containers, database throughput, and tags for every stamp each week. Metrics flagged containers with repeated 429 responses, high normalized RU consumption, or rapid storage growth. When a tenant crossed the promotion threshold, automation created a dedicated-throughput container and scheduled a controlled data move. Security review confirmed that access boundaries remained container-based, while architecture review focused on performance coupling. FinOps dashboards showed the shared pool cost separately from dedicated tenant containers so owners could see why promotions happened.
📈Results & Business Impact
New-stamp Cosmos DB spend decreased by 46 percent during the first six months of customer onboarding.
Three growing tenants were promoted before their monthly upload bursts affected smaller tenants.
429 incidents across shared stamps fell from 22 in one quarter to five after promotion rules were enforced.
Capacity reviews shifted from opinion-based arguments to weekly RU and throttling evidence.
💡Key Takeaway for Glossary Readers
Shared database throughput works best in SaaS stamps when fairness is measured constantly and growing tenants are promoted before they hurt others.
Why use Azure CLI for this?
I use Azure CLI for shared database throughput because the portal view can hide the relationship between the database pool and individual containers. CLI lets me show database throughput, list containers, check which containers have dedicated throughput, compare partition keys, and export evidence during cost or throttling reviews. When a team complains that Cosmos DB is slow, I want to see whether a noisy container is consuming the shared pool before recommending more RU/s. CLI also helps automate migration from manual to autoscale or from shared database throughput to dedicated container throughput. Ten years in Azure teaches you that throughput settings need repeatable inventory, not assumptions. It keeps scale changes honest. It keeps capacity debates evidence-based.
CLI use cases
Show database throughput to confirm whether RU/s is provisioned at the database level.
List containers and identify which ones share the database pool versus which have dedicated throughput.
Update or migrate database throughput between manual and autoscale during a planned capacity change.
Export container names, partition keys, and metrics before a noisy-neighbor incident review.
Create a shared-throughput database for a controlled migration or low-traffic stamp with documented exit criteria.
Before you run CLI
Confirm account name, resource group, database name, API type, region, and subscription before changing throughput.
Know whether the command affects the whole database pool or one dedicated container because blast radius differs.
Check current RU/s, autoscale state, throttling metrics, and cost owner before increasing capacity.
Coordinate with application teams before migrating throughput type or moving containers to dedicated throughput.
Use JSON output and save current settings so rollback and post-change comparison are possible.
What output tells you
Database throughput output shows manual or autoscale RU/s, minimums, and whether scaling changes are pending.
Container list output identifies every workload that may be affected by a database-level throughput change.
Container throughput output helps distinguish containers with dedicated RU/s from containers using the shared pool.
Metric output connects 429 responses, normalized RU consumption, and latency to possible noisy-neighbor behavior.
Resource IDs and tags identify ownership, environment, and budget context for capacity decisions.
az cosmosdb sql database throughputoperateDatabases
az cosmosdb sql container list --account-name <account-name> --resource-group <resource-group> --database-name <database-name> --output table
az cosmosdb sql containerdiscoverDatabases
Architecture context
Architecturally, shared database throughput is a pooling pattern for Cosmos DB RU/s. I consider it only when containers are small, traffic is low, tenant isolation is not strict, and the team has strong monitoring. It can simplify early migrations from clustered databases where many collections share capacity, or support low-traffic deployment stamps where paying minimum RU/s per container is wasteful. The tradeoff is noisy-neighbor behavior and less predictable performance for any single container. A mature architecture defines exit criteria: when a container grows, becomes business-critical, receives bursty imports, or needs an SLA, move it to dedicated throughput. Partition-key quality and monitoring are nonnegotiable. Review this before tenant launch. Define graduation triggers early.
Security
Security impact is indirect because shared database throughput does not grant identity or network access. The risk appears when performance isolation is confused with access isolation. Containers may have separate data and permissions, but they still compete for one RU/s pool. A malicious, compromised, or buggy workload with legitimate access can consume shared throughput and create denial-of-service pressure for other containers. Security reviews should still cover keys, managed identities, RBAC, private endpoints, firewall rules, customer-managed keys, and diagnostic logs. For regulated or tenant-sensitive workloads, ask whether one tenant's workload can throttle another. That is an availability and fairness risk even when data access controls are correctly configured. Document ownership before combining workloads.
Cost
Cost impact is the main attraction. Shared database throughput can reduce minimum RU/s spend when many containers have tiny, intermittent workloads. It can also simplify early migration planning because one pool covers several collections. The cost risk is that a single growing container forces the entire database pool upward, making small containers pay for capacity they do not need. Autoscale can help with burst patterns, but the shared pool still needs monitoring and budget ownership. FinOps reviews should compare database-level RU/s cost with dedicated container alternatives, throttling incidents, support hours, and the number of containers sharing the pool. Cheap pooling is only successful if it stays fair and observable. Review savings against support effort and throttling risk.
Reliability
Reliability impact is direct because shared throughput couples containers together. If one container runs a heavy query, import, or hot-partition workload, other containers may see 429 rate limiting or slower responses even though their own code did not change. Reliable use requires clear container count limits, good partition keys, retry logic, RU monitoring, and alerting on throttled requests per container. Teams should rehearse what happens when a container outgrows the shared pool: increase database throughput, migrate that container to dedicated throughput, or redesign the workload. Avoid placing critical and experimental containers in the same shared database. Reliability improves when exit criteria and rollback are defined before growth happens. Test bulk jobs before business hours. Test import windows before production launch.
Performance
Performance is the central tradeoff. Cosmos DB measures work in request units, and shared database throughput means containers contend for the same RU/s allocation. A hot logical partition, fan-out query, bulk import, or sudden tenant burst can reduce throughput available to quieter containers. The result often appears as 429 responses, higher latency, or inconsistent query times. Performance testing must include all containers that share the database, not just one happy-path container. Monitor RU consumption, throttled requests, partition-key distribution, and storage growth per container. If one workload needs predictable low latency, give it dedicated throughput. Shared database throughput should be measured as a pool, not assumed to be fair. Measure mixed traffic during tests. Measure by container, partition, and user path.
Operations
Operators manage shared database throughput by watching the pool and every container using it. Daily tasks include showing database throughput, listing containers, checking dedicated versus shared settings, reviewing partition keys, monitoring normalized RU consumption, and investigating throttled requests. During incidents, operators should identify which container or partition consumed the pool before simply raising RU/s. Runbooks need steps for temporary throughput increases, autoscale migration, container isolation, and post-incident cost review. Documentation should state why the database uses shared throughput and which containers are allowed to join. Without that discipline, teams add containers casually until performance becomes unpredictable and ownership becomes political. Review ownership before adding containers to pools again. Keep container ownership and graduation thresholds visible in operational reviews.
Common mistakes
Using shared database throughput as the default for production containers that need predictable performance.
Adding containers to a shared database without checking whether existing workloads have compatible traffic patterns.
Increasing the database RU/s repeatedly instead of isolating the one container causing throttling.
Forgetting that containers in a shared-throughput database have no guaranteed individual RU/s share.
Mixing critical tenant data and experimental workloads in the same shared database pool.