docs: Database Instance Operations #223
Conversation
Documentation on how to start, stop, and restart database instances using the control plane PLAT-325
mmols
left a comment
mmols
left a comment
There was a problem hiding this comment.
Thanks for this - I've left a few comments to adjust to align with other nearby docs. Once we address that, we can send to Susan for final review.
docs/using/database-instances.md
Outdated
| @@ -0,0 +1,93 @@ | |||
| # Database Instances | |||
There was a problem hiding this comment.
I suggest renaming this to "Managing Database Instances". You will also need to place it in the mkdocs.yml file so that it's rendered in the menu under "Using Control Plane". I suggest placing it below Read Replicas.
docs/using/database-instances.md
Outdated
| @@ -0,0 +1,93 @@ | |||
| # Database Instances | |||
|
|
|||
| A database instance is: | |||
There was a problem hiding this comment.
I would revise this top section to keep it short - its likely we need additional articles on managing users and port selection. I would write a few paragraphs that re-iterate what Instances are, and why you might need to manage them. You can pull from the Concepts page for some wording.
docs/using/database-instances.md
Outdated
| * Must remain consistent across all instances | ||
| * Cannot conflict with system users | ||
|
|
||
| States |
There was a problem hiding this comment.
I would pull this information into a subheading "Monitoring Instances" and show the user how you can fetch this information using the GetDatabase endpoint. The user will need to find the instance IDs to use the rest of the operations below.
You can also speak to the postgres status information under each instance, notably the pending_restart field which highlights if a configuration change is pending that requires a restart.
docs/using/database-instances.md
Outdated
|
|
||
|
|
||
|
|
||
| # Database Instance Operations |
There was a problem hiding this comment.
There should be only 1 top level header per page, so I would remove this and just have:
- Monitoring Instances
- Stopping Instances
- Starting Instances
- Restarting Instances
docs/using/database-instances.md
Outdated
|
|
||
|
|
||
| ```sh | ||
| curl http://host-3:3000/v1/databases/example/instances/n1/stop |
There was a problem hiding this comment.
Each of these sample requests is a POST. This might work with a GET, but we should follow the spec accordingly.
docs/using/database-instances.md
Outdated
| * Other instances remain unaffected | ||
| * A stopped instance continues to appear under list-databases with state: "stopped" | ||
|
|
||
| Example: Stop a database “example” whose instance ID is “n1” |
There was a problem hiding this comment.
The Instance IDs are always generated - they look something like this: example-n1-689qacsi, which is <database-id>-<node-name>-<host-id-hash> - let's follow this here and have carry through from our other docs pages that use example.
📝 WalkthroughWalkthroughAdds a new documentation guide describing PostgreSQL database instance concepts, lifecycle vs. stable DBs, instance states, monitoring response shape, and stop/start/restart operations with examples; also updates site navigation to include the new guide. (34 words) Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
In @docs/using/database-instances.md:
- Around line 99-101: The curl example for stopping an instance currently omits
the HTTP method and will default to GET; update the example to explicitly use
POST (e.g., add -X POST) so the stop operation mirrors the start/restart
examples and correctly invokes the state-changing endpoint
(/v1/databases/example/instances/n1/stop).
- Line 21: Fix the typos in the sentence that reads "modifying certain
POstgresSQL parameters... (eg shared_buffers)" by changing "POstgresSQL" to
"PostgreSQL" and replacing "eg" with the proper abbreviation "e.g.,", and apply
the same "eg" → "e.g.," correction to the earlier occurrence on line 12; update
the sentence text so it reads e.g., "(e.g., shared_buffers)" and "PostgreSQL"
exactly as spelled.
- Around line 69-82: The instance states list is missing the `stopped` state
referenced elsewhere; update the "Instance States" enumeration under the
"Instance States" heading to include `stopped` alongside `available`,
`starting`, `stopping`, `restarting`, `failed`, `error`, and `unknown` so it
matches the references in the "Stopping Instances" section and the rest of the
document.
- Around line 96-101: Update the instance operation examples to use POST and the
correct endpoint suffixes and full instance IDs: replace the stop example curl
with a POST to /v1/databases/example/instances/example-n1-689qacsi/stop-instance
(not GET /.../n1/stop), and change the start and restart examples to POST to
/v1/databases/example/instances/example-n1-689qacsi/start-instance and
/v1/databases/example/instances/example-n1-689qacsi/restart-instance
respectively; ensure the examples use the full instance ID (example-n1-689qacsi)
rather than the node_name (n1) and include -X POST in each curl invocation.
🧹 Nitpick comments (1)
docs/using/database-instances.md (1)
1-4: Remove excessive blank lines.There are multiple consecutive blank lines throughout the document (lines 2-4, and similar patterns elsewhere). Consider consolidating to single blank lines for cleaner formatting.
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/using/database-instances.mdmkdocs.yml
🧰 Additional context used
🪛 LanguageTool
docs/using/database-instances.md
[grammar] ~21-~21: Ensure spelling is correct
Context: ...fecycle. For example, modifying certain POstgresSQL parameters can require a restart to tak...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Codacy Static Code Analysis
🔇 Additional comments (4)
docs/using/database-instances.md (3)
26-67: LGTM!The monitoring section clearly documents the GetDatabase endpoint, response fields, and the significance of
pending_restart.
104-120: LGTM!The start operation documentation is clear, uses explicit POST method, and documents the state transition correctly.
129-131: Clarify restart blocking conditions.The blocking condition "No configuration changes require a restart" seems counterintuitive—users might want to restart for reasons other than configuration changes (e.g., to recover from errors, as mentioned in line 126). Consider clarifying whether this restriction applies and under what circumstances.
Also, consider using a bulleted list for better readability:
Suggested formatting improvement
-* Restart is blocked if: No configuration changes require a restart, Another update is in progress, or Instance is not stable +* Restart is blocked if: + * Another update is in progress + * Instance is not in a stable statemkdocs.yml (1)
81-81: LGTM!The navigation entry is correctly formatted and logically placed within the "Using Control Plane" section.
mmols
changed the title
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@docs/using/database-instances.md`:
- Line 69: Update the descriptive sentence to match the curl example by
referring to the full instance ID used in the command (example-n1-689qacsi)
instead of just "n1"; e.g., change the phrase "stops an instance named 'n1'" to
"stops the instance with ID 'example-n1-689qacsi'" so the description and the
curl example are consistent.
🧹 Nitpick comments (1)
docs/using/database-instances.md (1)
96-100: Consider improving readability of blocking conditions.The blocking conditions are currently formatted as a continuous sentence. Converting them to a bulleted list would improve readability and make them easier to scan.
♻️ Proposed refactor
* If no scheduled_at is provided → restart immediately. * Transition: available → restarting → available -* Restart is blocked if: No configuration changes require a restart, Another update is in progress, or Instance is not stable - +* Restart is blocked if: + * No configuration changes require a restart + * Another update is in progress + * Instance is not stable
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@docs/using/database-instances.md`:
- Around line 2-6: Update the opening line "A Database instance is:" to use
sentence case ("A database instance is:") and replace the term "Postgres" with
"PostgreSQL" throughout the document (notably the first bullet currently reading
"A running Postgres server") so capitalization and product name are consistent
with later sections; search for the exact strings "A Database instance is:" and
"Postgres" and replace them with "A database instance is:" and "PostgreSQL"
respectively.
- Around line 2-7: The examples for database ID and instance ID are
inconsistent—update the instance ID example and all API examples (the standalone
"instance ID example" and the later "API examples" blocks referenced around
lines 15-21 and 69-74) to use the same database ID format across the doc (either
use a UUID-style DB ID everywhere or use "example" everywhere) so the
relationship between database ID and instance ID is clear; pick one style,
replace the mismatched IDs accordingly (e.g., if choosing "example", change
68f50878-... to "example" and adjust instance IDs to "example-n1-689qacsi", or
vice versa), and ensure all three sections use the chosen pattern consistently.
| A Database instance is: | ||
| * A running Postgres server | ||
| * Bound to a specific host | ||
| * Identified by a node name (e.g. n1) | ||
| * Identified globally by an instance ID (e.g., 68f50878-44d2-4524-a823-e31bd478706d-n1-689qacsi) |
There was a problem hiding this comment.
Tighten introductory wording and capitalization.
Consider changing “A Database instance is:” to “A database instance is:” and using “PostgreSQL” consistently with later sections for polish.
🤖 Prompt for AI Agents
In `@docs/using/database-instances.md` around lines 2 - 6, Update the opening line
"A Database instance is:" to use sentence case ("A database instance is:") and
replace the term "Postgres" with "PostgreSQL" throughout the document (notably
the first bullet currently reading "A running Postgres server") so
capitalization and product name are consistent with later sections; search for
the exact strings "A Database instance is:" and "Postgres" and replace them with
"A database instance is:" and "PostgreSQL" respectively.
| A Database instance is: | ||
| * A running Postgres server | ||
| * Bound to a specific host | ||
| * Identified by a node name (e.g. n1) | ||
| * Identified globally by an instance ID (e.g., 68f50878-44d2-4524-a823-e31bd478706d-n1-689qacsi) | ||
|
|
There was a problem hiding this comment.
Align database/instance ID examples to avoid confusion.
The instance ID example on Line 6 uses a UUID-like database ID, but the later API examples use example as the database ID and example-n1-689qacsi as the instance ID. Please make these examples consistent (either use a UUID database ID everywhere or use example everywhere) so readers can see the ID relationship clearly.
Also applies to: 15-21, 69-74
🤖 Prompt for AI Agents
In `@docs/using/database-instances.md` around lines 2 - 7, The examples for
database ID and instance ID are inconsistent—update the instance ID example and
all API examples (the standalone "instance ID example" and the later "API
examples" blocks referenced around lines 15-21 and 69-74) to use the same
database ID format across the doc (either use a UUID-style DB ID everywhere or
use "example" everywhere) so the relationship between database ID and instance
ID is clear; pick one style, replace the mismatched IDs accordingly (e.g., if
choosing "example", change 68f50878-... to "example" and adjust instance IDs to
"example-n1-689qacsi", or vice versa), and ensure all three sections use the
chosen pattern consistently.
There was a problem hiding this comment.
The UUID format (68f50878-44d2-4524-a823-e31bd478706d-n1-689qacsi) is shown only as an illustrative example of what a globally unique instance ID could look like in the conceptual introduction, not as the actual ID used in the API examples specific to the example database being referenced.
There was a problem hiding this comment.
@GabriellePoncey, thank you for the clarification! I understand now—the UUID-based instance ID in the introduction serves as a conceptual illustration of the ID format and structure, while the API examples use "example" as the database ID for practical demonstration purposes. That distinction makes sense for documentation, and having both the conceptual format and concrete examples is helpful for readers.
| In the following example, the `curl` command stops an instance named "example-n1-689qacsi" for a database named "example": | ||
|
|
||
| === "curl" | ||
| ```sh |
There was a problem hiding this comment.
The code blocks here require an additional indent to render correctly - if you run make docs you will see that they don't match up.
Summary
Adds a new docs page that documents how to start, stop, and restart database instances using the control plane
PLAT-325
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.