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.
📝 WalkthroughWalkthroughA new documentation guide for PostgreSQL database instance management was added, covering instance definitions, lifecycle concepts, states, monitoring endpoints, operational workflows, and API examples. The navigation configuration was updated to include the new guide. 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. ✨ Finishing touches
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.
| While a database is stable and persistent, database instances are runtime components with states that are not "identity-critical". This allows rolling updates, automatic failovers, and safe restarts. | ||
|
|
||
|
|
||
| Managing a database instance involves handling various operational needs throughout its lifecycle. For example, modifying certain POstgresSQL parameters can require a restart to take effect (eg shared_buffers), as the Control Plane does not automatically restart instances on a user’s behalf. Additionally, managing instances allows you to control costs by stopping unused development or test environments, troubleshoot issues when systems become unresponsive, and coordinate system updates in a controlled manner to minimize disruption to your applications. |
There was a problem hiding this comment.
Fix typo: "POstgresSQL" → "PostgreSQL".
Proposed fix
-Managing a database instance involves handling various operational needs throughout its lifecycle. For example, modifying certain POstgresSQL parameters can require a restart to take effect (eg shared_buffers), as the Control Plane does not automatically restart instances on a user's behalf. Additionally, managing instances allows you to control costs by stopping unused development or test environments, troubleshoot issues when systems become unresponsive, and coordinate system updates in a controlled manner to minimize disruption to your applications.
+Managing a database instance involves handling various operational needs throughout its lifecycle. For example, modifying certain PostgreSQL parameters can require a restart to take effect (e.g., shared_buffers), as the Control Plane does not automatically restart instances on a user's behalf. Additionally, managing instances allows you to control costs by stopping unused development or test environments, troubleshoot issues when systems become unresponsive, and coordinate system updates in a controlled manner to minimize disruption to your applications.Also note: "eg" should be "e.g.," (with periods and comma) for proper abbreviation formatting, appearing both here and on line 12.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Managing a database instance involves handling various operational needs throughout its lifecycle. For example, modifying certain POstgresSQL parameters can require a restart to take effect (eg shared_buffers), as the Control Plane does not automatically restart instances on a user’s behalf. Additionally, managing instances allows you to control costs by stopping unused development or test environments, troubleshoot issues when systems become unresponsive, and coordinate system updates in a controlled manner to minimize disruption to your applications. | |
| Managing a database instance involves handling various operational needs throughout its lifecycle. For example, modifying certain PostgreSQL parameters can require a restart to take effect (e.g., shared_buffers), as the Control Plane does not automatically restart instances on a user's behalf. Additionally, managing instances allows you to control costs by stopping unused development or test environments, troubleshoot issues when systems become unresponsive, and coordinate system updates in a controlled manner to minimize disruption to your applications. |
🧰 Tools
🪛 LanguageTool
[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)
🤖 Prompt for AI Agents
In @docs/using/database-instances.md at 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.
| ### Instance States | ||
|
|
||
|
|
||
| Postgres instances can be in different states as a result of database operations (start/stop/restart/etc): | ||
|
|
||
|
|
||
| * `available` | ||
| * `starting` | ||
| * `stopping` | ||
| * `restarting` | ||
| * `failed` | ||
| * `error` | ||
| * `unknown` | ||
|
|
There was a problem hiding this comment.
Missing "stopped" state in the enumeration.
The "Stopping Instances" section (line 90, 93) references a stopped state, but it's not included in this list of possible instance states.
Proposed fix
* `available`
* `starting`
* `stopping`
+* `stopped`
* `restarting`
* `failed`
* `error`
* `unknown`📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### Instance States | |
| Postgres instances can be in different states as a result of database operations (start/stop/restart/etc): | |
| * `available` | |
| * `starting` | |
| * `stopping` | |
| * `restarting` | |
| * `failed` | |
| * `error` | |
| * `unknown` | |
| ### Instance States | |
| Postgres instances can be in different states as a result of database operations (start/stop/restart/etc): | |
| * `available` | |
| * `starting` | |
| * `stopping` | |
| * `stopped` | |
| * `restarting` | |
| * `failed` | |
| * `error` | |
| * `unknown` |
🤖 Prompt for AI Agents
In @docs/using/database-instances.md around lines 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.
| In the following example, the `curl` command stops an instance named "n1" for a database named "example": | ||
|
|
||
|
|
||
| ```sh | ||
| curl http://host-3:3000/v1/databases/example/instances/n1/stop | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's look at the database-instances.md file to see the actual examples
head -150 docs/using/database-instances.md | tail -70Repository: pgEdge/control-plane
Length of output: 2646
🏁 Script executed:
# Also get lines around 115-119 to see the start example
sed -n '90,130p' docs/using/database-instances.mdRepository: pgEdge/control-plane
Length of output: 1598
🏁 Script executed:
# Look for API route definitions or implementation that handles instance operations
fd -e go -e js -e ts -e py | xargs grep -l "instances.*stop\|instances.*start" 2>/dev/null | head -20Repository: pgEdge/control-plane
Length of output: 289
🏁 Script executed:
# Search for API endpoint definitions that handle instance operations
rg "instances.*\{.*\}/stop|instances.*\{.*\}/start" --type yaml --type json --type goRepository: pgEdge/control-plane
Length of output: 1693
🏁 Script executed:
# Search for node_name handling in instance operations
rg "node_name|node.name" api/apiv1/ --type go | grep -i "stop\|start\|instance" | head -20Repository: pgEdge/control-plane
Length of output: 996
🏁 Script executed:
# Check the actual handler implementations for instance operations
fd -e go -path "*/workflows/*" | xargs grep -l "stop.*instance\|StopInstance" 2>/dev/null | head -5Repository: pgEdge/control-plane
Length of output: 232
🏁 Script executed:
# Look for route parameter handling
rg "instance_id|instanceID" api/apiv1/design/api.go -A 3 -B 3Repository: pgEdge/control-plane
Length of output: 3228
Fix multiple API endpoint inconsistencies in instance operation examples.
The documentation has several errors in the API endpoint examples:
- Stop example: Uses incorrect HTTP method (GET instead of POST), wrong path (
/stopinstead of/stop-instance), and wrong identifier format (n1instead of full instance ID) - Start and restart examples: Use incorrect path suffixes (
/startand/restartinstead of/start-instanceand/restart-instance)
All three operations must use POST method and the full instance ID (e.g., example-n1-689qacsi). The node_name field (like n1) is metadata only and cannot be used in URL paths.
Proposed fixes
Stop example:
-In the following example, the `curl` command stops an instance named "n1" for a database named "example":
+In the following example, the `curl` command stops an instance with ID "example-n1-689qacsi" for a database named "example":
```sh
-curl http://host-3:3000/v1/databases/example/instances/n1/stop
+curl -X POST http://host-3:3000/v1/databases/example/instances/example-n1-689qacsi/stop-instance
Start example:
```diff
```sh
-curl -X POST http://host-3:3000/v1/databases/example/instances/example-n1-689qacsi/start
+curl -X POST http://host-3:3000/v1/databases/example/instances/example-n1-689qacsi/start-instance
Restart example:
```diff
```sh
-curl -X POST http://host-3:3000/v1/databases/example/instances/example-n1-689qacsi/restart
+curl -X POST http://host-3:3000/v1/databases/example/instances/example-n1-689qacsi/restart-instance
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
In @docs/using/database-instances.md around lines 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.
</details>
<!-- fingerprinting:phantom:poseidon:ocelot -->
<!-- This is an auto-generated comment by CodeRabbit -->
| ```sh | ||
| curl http://host-3:3000/v1/databases/example/instances/n1/stop | ||
| ``` |
There was a problem hiding this comment.
Add explicit HTTP method for stop operation.
The stop operation modifies state and should use POST (like start and restart). Without -X POST, curl defaults to GET, which may not work correctly for this endpoint.
Proposed fix
-curl http://host-3:3000/v1/databases/example/instances/n1/stop
+curl -X POST http://host-3:3000/v1/databases/example/instances/n1/stop🤖 Prompt for AI Agents
In @docs/using/database-instances.md around lines 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).
mmols
changed the title
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.