Azure Cosmos DB Naming Conventions: Account, Database, and Container

An Azure Cosmos DB account name is a globally unique DNS endpoint (<name>.documents.azure.com), so it must be 3 to 44 characters, lowercase letters, numbers, and hyphens, and start with a letter or number: cosmos-payments-prod-eus-001. Hyphens are allowed here, unlike storage accounts. Databases and containers inside the account are far more relaxed.

Azure Cosmos DB naming splits into two very different problems, the same way SQL does. The account is a globally visible DNS endpoint with strict, globally-unique rules. The databases and containers inside it are privately scoped and generous. Get the account name right, and the rest is easy.

The account name is a global endpoint

The Cosmos DB account name becomes <name>.documents.azure.com, the endpoint your SDKs and connection strings point at. That is why it is globally unique and DNS-safe.

Rule	Detail
Min length	3 characters
Max length	44 characters
Allowed characters	Lowercase letters, numbers, and hyphens
Must start with	A lowercase letter or number
Uppercase	Not allowed
Scope of uniqueness	Global (across all of Azure)
CAF prefix	cosmos

The important contrast: hyphens are allowed, so unlike storage accounts and container registries you can use the readable hyphenated CAF pattern. The catch is the tight 44-character limit.

The CAF pattern

cosmos-{workload}-{environment}-{region}-{instance}

Examples:

Workload	Environment	Region	Account name
payments	prod	eus	cosmos-payments-prod-eus-001
catalog	dev	weu	cosmos-catalog-dev-weu-001
sessions	prod	eus	cosmos-sessions-prod-eus-001

cosmos-payments-prod-eus-001 is 28 characters, comfortably under 44. But with a 7-character cosmos- prefix you have 37 left, so a company prefix plus a long workload can overflow. If it does, drop the region or company before shortening the workload.

API-specific abbreviations

CAF assigns a different abbreviation depending on the Cosmos DB API you use, which keeps the account’s data model visible in its name:

API	CAF prefix	Example
NoSQL (Core)	cosno	cosno-payments-prod-eus-001
MongoDB	cosmon	cosmon-payments-prod-eus-001
Cassandra	coscas	coscas-payments-prod-eus-001
Table	costab	costab-payments-prod-eus-001
Gremlin	cosgrm	cosgrm-payments-prod-eus-001
PostgreSQL	cospos	cospos-payments-prod-eus-001

Using cosmos as a generic prefix is fine too. Pick one approach: the API-specific prefixes are more descriptive, the generic cosmos is simpler. Note that Cosmos DB for PostgreSQL allows up to 63 characters, the others cap at 44.

Databases and containers inside the account

The account name already carries workload, environment, and region. Repeating that in every database and container name just adds noise. Name them after their purpose:

cosmos-payments-prod-eus-001
├── orders          (database)
│   ├── active      (container)
│   └── archived    (container)
└── customers       (database)
    └── profiles    (container)

Database and container names are far more relaxed than the account (up to 255 characters, and case-sensitive), so keep them short, lowercase, and purpose-named. orders, not cosmos-payments-prod-orders.

A note on the region component

A Cosmos DB account is a globally distributed resource, it can span many regions. The region in the account name reflects the primary write region, not a single location. If you run a multi-region account and expect the write region to move, some teams omit the region component to avoid a name that becomes misleading after a failover. Either choice is fine, just be consistent.

Naming in Terraform

variable "workload"    { default = "payments" }
variable "environment" { default = "prod" }
variable "region"      { default = "eus" }

resource "azurerm_cosmosdb_account" "main" {
  name                = "cosmos-${var.workload}-${var.environment}-${var.region}-001"
  resource_group_name = azurerm_resource_group.main.name
  location            = azurerm_resource_group.main.location
  offer_type          = "Standard"
  kind                = "GlobalDocumentDB"

  consistency_policy { consistency_level = "Session" }
  geo_location {
    location          = azurerm_resource_group.main.location
    failover_priority = 0
  }
}

Hyphens are allowed, so no replace() is needed, but keep the name lowercase and watch the 44-character ceiling.

Common mistakes

Exceeding 44 characters. A company prefix plus a long workload plus region plus instance adds up fast. Design for the 44-character limit, and check the length before deploying.

Uppercase. Cosmos DB account names must be lowercase. Cosmos-Payments is rejected.

Putting a fixed region in a multi-region account. If the account spans regions and can fail over, a hardcoded region in the name can become a lie. Consider omitting it for globally distributed accounts.

Full CAF chains on containers. A container named cosmos-payments-prod-orders inside an account that already says cosmos-payments-prod repeats everything. Call it orders.

Summary

• Account names: 3 to 44 characters, lowercase letters, numbers, and hyphens, globally unique, they become documents.azure.com endpoints
• Hyphens are allowed, so the readable CAF pattern works, but the 44-character limit is tight
• Use API-specific prefixes (cosno, cosmon, coscas) or the generic cosmos
• Databases and containers inside the account: short and purpose-named

Full rules are on the Cosmos DB naming page. AzureNamer generates account names for every Cosmos DB API with the right constraints applied. See the SQL naming guide for the same DNS-endpoint pattern on relational databases, and the complete CAF guide for the fundamentals.