Configuration Reference¶

All configuration flows through MulticloudDbClientConfig or a .properties file. Select a provider and supply its connection and auth properties.

Common Properties¶

Property	Description	Example
`multiclouddb.provider`	Provider ID	`cosmos`, `dynamo`, `spanner`
`multiclouddb.feature.*`	Feature flags	Provider-specific opt-ins

Azure Cosmos DB¶

Emulator (local)Azure Cloud (key-based)Azure Identity (Entra ID) - Recommended

multiclouddb.provider=cosmos
multiclouddb.connection.endpoint=https://localhost:8081
multiclouddb.connection.key=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
multiclouddb.connection.connectionMode=gateway

# ⚠ Not recommended for production - use Entra ID (see next tab)
multiclouddb.provider=cosmos
multiclouddb.connection.endpoint=https://your-account.documents.azure.com:443/
multiclouddb.connection.key=your-master-key
multiclouddb.connection.connectionMode=direct

multiclouddb.provider=cosmos
multiclouddb.connection.endpoint=https://your-account.documents.azure.com:443/
# No key - uses DefaultAzureCredential (Managed Identity, Azure CLI, etc.)
# multiclouddb.connection.tenantId=your-tenant-id   # optional, for multi-tenant

Key	Description
`multiclouddb.connection.endpoint`	Cosmos DB account URI or emulator URI
`multiclouddb.connection.key`	Master key (omit for Azure Identity auth)
`multiclouddb.connection.connectionMode`	`gateway` (default) or `direct`
`multiclouddb.connection.tenantId`	Azure AD tenant ID (optional, for Entra ID)

Authentication Modes¶

Recommended: Use identity-based authentication

Key-based / shared-key authentication is supported for local development and emulator use. For production workloads, always use identity-based auth (Entra ID for Cosmos DB, IAM roles for DynamoDB, GCP service accounts for Spanner).

Azure Identity / Entra ID (recommended) - when no key is provided, uses DefaultAzureCredential (supporting Managed Identity, Azure CLI, environment variables, and the full Azure credential chain)
Master key - when connection.key is provided, uses shared-key authentication. Suitable for local emulator development only.

Connection Modes¶

Gateway (default) - HTTP-based routing through the Cosmos DB gateway. Required for the emulator.
Direct - TCP-based direct connectivity. Better performance for production workloads.

Amazon DynamoDB¶

DynamoDB LocalAWS Cloud

multiclouddb.provider=dynamo
multiclouddb.connection.endpoint=http://localhost:8000
multiclouddb.connection.region=us-east-1
multiclouddb.auth.accessKeyId=fakeMyKeyId
multiclouddb.auth.secretAccessKey=fakeSecretAccessKey

# ⚠ Static credentials shown for reference - use IAM roles in production
multiclouddb.provider=dynamo
# No endpoint - uses the AWS default endpoint for the region
multiclouddb.connection.region=us-east-1
multiclouddb.auth.accessKeyId=your-access-key
multiclouddb.auth.secretAccessKey=your-secret-key

Key	Description
`multiclouddb.connection.endpoint`	DynamoDB Local URI (omit for AWS)
`multiclouddb.connection.region`	AWS region (e.g., `us-east-1`)
`multiclouddb.auth.accessKeyId`	AWS access key ID
`multiclouddb.auth.secretAccessKey`	AWS secret access key

DynamoDB table naming

DynamoDB has no native "database" concept. The ResourceAddress database and collection are composed into a single table name using the pattern database__collection (double underscore separator).

Google Cloud Spanner¶

Maven artifact coming soon

The Spanner provider source code and conformance tests are included in the repository, but Maven artifacts are not yet published. You can build from source to use the Spanner provider today.

EmulatorGCP Cloud

multiclouddb.provider=spanner
multiclouddb.connection.projectId=test-project
multiclouddb.connection.instanceId=test-instance
multiclouddb.connection.databaseId=test-database
multiclouddb.connection.emulatorHost=localhost:9010

multiclouddb.provider=spanner
multiclouddb.connection.projectId=my-gcp-project
multiclouddb.connection.instanceId=my-instance
multiclouddb.connection.databaseId=my-database

Key	Description
`multiclouddb.connection.projectId`	GCP project ID
`multiclouddb.connection.instanceId`	Spanner instance ID
`multiclouddb.connection.databaseId`	Spanner database ID
`multiclouddb.connection.emulatorHost`	Emulator host:port (omit for GCP)

Programmatic Configuration¶

You can also configure the client programmatically using the builder:

MulticloudDbClientConfig config = MulticloudDbClientConfig.builder()
    .provider(ProviderId.COSMOS)
    .connection("endpoint", "https://localhost:8081")
    .connection("key", "your-key")
    .connection("connectionMode", "gateway")
    .build();

MulticloudDbClient client = MulticloudDbClientFactory.create(config);

Resource Provisioning¶

The SDK can provision databases and containers/tables automatically:

// Define your schema: database name → list of collection/table names
Map<String, List<String>> schema = Map.of(
    "admin-db",    List.of("tenants"),
    "acme-risk-db", List.of("portfolios", "positions", "risk_metrics")
);

// Single call - SDK handles parallel creation internally
client.provisionSchema(schema);

Provider	Database Phase	Container/Table Phase
Cosmos DB	Creates databases in parallel	Creates containers in parallel
DynamoDB	No-op (no native database concept)	Creates tables in parallel, waits for ACTIVE
Spanner	No-op (database set at client construction)	Creates tables in parallel

See the Developer Guide for the full provisioning reference.

Custom User-Agent¶

Append your own identifier to the SDK user-agent for downstream diagnostics:

MulticloudDbClientConfig config = MulticloudDbClientConfig.builder()
    .provider(ProviderId.COSMOS)
    .connection("endpoint", "https://my-account.documents.azure.com:443/")
    .userAgentSuffix("my-app/1.2.3")
    .build();

Results in: multiclouddb-sdk-java/0.1.0-beta.1 (17.0.5; Windows 11) my-app/1.2.3