SphereDB on the DocumentDB engine
SphereDB built on the open-source DocumentDB engine: a document database that runs in your environment, next to the services that use it. Pick an instance type, and every service in the environment gets its connection string as MONGODB_URI.
The DocumentDB engine is the open-source, MongoDB-compatible engine built on PostgreSQL.
It runs in US East (Virginia) and EU (Sweden), like every SphereDB database.
Limits
- Change streams aren't supported.
- Free has 500 MB of storage that can't grow. One Free database per account on this engine; change to a paid size for more.
- Storage grows, doesn't shrink. Paid sizes include storage; storage beyond the included amount is billed per GB, up to 2048 GB.
- Engine updates restart the database. They're applied in place and keep your data; without high availability a database is unavailable for about a minute, with high availability it sees brief interruptions.
- No public access. The host is private to the environment.
- No extensions, no collation on indexes.
connectionStatusdoesn't list your user's roles.
What you configure
| Field | What it does |
|---|---|
| Name | Lowercase letters, digits, and hyphens, up to 40 characters. Unique in the environment. |
| Engine | DocumentDB (documentdb in the API). |
| Instance type | CPU and memory. See Instance types. |
| High availability | None, or a standby in another zone. From 1 vCPU. |
| Inject | On by default: every service in the environment gets MONGODB_URI. |
| Storage | Paid sizes: from the size's included storage up to 2048 GB. Storage grows and can't shrink. Free: 500 MB, fixed. |
The owner's username and password are generated for you. To give an app or a person its own sign-in, add database users.
Instance types
The DocumentDB engine has its own instance types. Their names match SphereDB PostgreSQL's (Standard 1, Plus 2, ...), but their API ids start with docdb-.
| Family | Sizes |
|---|---|
| Free | One per account on the DocumentDB engine (a Free PostgreSQL-engine database doesn't count against it). 500 MB storage, fixed. |
| Flex | 512 MB or 1 GB of memory. |
| Standard | Standard 1, 2, 4, and 8: that many vCPU. |
| Plus | Plus 1, 2, and 4: that many vCPU, twice the memory of Standard. |
The console lists every size offered in the environment's region with its monthly price; in the API, GET /v2/databases/instance-types?environment_id=….
Create a database
In your environment, create a new SphereDB database and choose DocumentDB as the engine. Pick an instance type and, from 1 vCPU, high availability. The database is ready in a few minutes; its page shows its status.
Connect from a service
With injection on, every service in the environment gets the connection string as MONGODB_URI and restarts to pick it up. The injected string already points at the CA certificate inside your services, so drivers verify the connection with no extra setup.
The database has one route, for your app, tools, and migrations: the engine pools connections itself. Connections need TLS and directConnection=true, and sign in with SCRAM-SHA-256 only. The connection string sets all three; if your driver builds its own connection, set them there too.
To connect from elsewhere in the environment, the database's Connect card in the console has the connection string, Download CA certificate, and client setup for the command line, Python, and Node.js. In the API, GET /v2/databases/{id}/connection returns the string and the CA certificate (ca_certificate); the password is masked unless you pass reveal=true.
Database users
Besides the owner, a database can have up to 20 users, each with its own sign-in. A user has one of two access levels:
- Read-only (
read): can query data. - Read and write (
readWrite): can also change it.
Only project admins and account owners and admins can add or change users. Anyone with access to the project can see the list.
A user's name uses lowercase letters, digits, and underscores, starts with a letter, and is up to 63 characters. It can't be the owner's name, and a few names are reserved for the platform and are refused.
The password is shown only once, when you add the user or rotate its password. Copy it then; if you lose it, rotate the password. The injected MONGODB_URI and the Connect card sign in as the owner. To connect as a user, use the same connection string with the user's name and password.
On the database's Settings tab, the Database users card lists each user with its access and state. A new user shows Setting up for a moment, then Ready.
- Add user: pick a name and an access level, then copy the password.
- From a user's ⋯ menu:
- Change access: switch between Read-only and Read and write. The password stays the same.
- Rotate password: you get a new password and the old one stops working, so apps that use it can't connect until you update them. If the change can't be applied, the old password keeps working.
- Delete user: apps that sign in as that user lose access.
A user that couldn't be set up shows Failed; delete it and add it again.
Backups and restore
Backups and restore work as they do for SphereDB PostgreSQL. A restore creates a new database on the same engine and never overwrites the original. The new database starts with the owner only; add its other users again.