From 52295be7b888ceece0f5b5dc6eb05dcbad2970d5 Mon Sep 17 00:00:00 2001 From: Gabrielle Poncey Date: Tue, 16 Dec 2025 14:04:08 -0800 Subject: [PATCH 1/2] Docs: Database Instance Operations Documentation on how to start, stop, and restart database instances using the control plane PLAT-325 --- docs/using/database-instances.md | 93 ++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 docs/using/database-instances.md diff --git a/docs/using/database-instances.md b/docs/using/database-instances.md new file mode 100644 index 00000000..110b28bf --- /dev/null +++ b/docs/using/database-instances.md @@ -0,0 +1,93 @@ +# Database Instances + +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 +(eg 68f50878-44d2-4524-a823-e31bd478706d-n1-689qacsi) +
+ +Each instance maps to exactly one physical host, but a host can run multiple database instances as long as ports do not clash. +
+ +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. + +Instances and port ownership +* Ports are unique per host +* Stopping an instance does not “free” the port +* Restarting preserves the same port +* Changing ports requires a plan update and a restart +* Port conflicts cause update failure + + +Users in the database spec: +* Are reconciled onto each instance +* Get created / updated / dropped during instance configuration +* Must remain consistent across all instances +* Cannot conflict with system users + +States +Instances can be in different states as a result of database operations (start/stop/restart/etc): + +* `available` +* `starting` +* `stopping` +* `restarting` +* `failed` +* `error` +* `unknown` +

+ + + +# Database Instance Operations +## Stop Instance +Stopping an instance shuts down the Postgres process for that specific instance by scaling it to zero. The instance no longer accepts connections and is taken out of service, but its data and configuration are preserved. Other instances in the same database can continue running. +As Stop Instance removes a database instance from service without deleting it, it can be used to isolate an instance not currently in use but that is expected to be restarted later. + +* Transition: available → stopping → stopped +* Port remains reserved for this instance +* 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” + +=== "curl" + + + ```sh + curl http://host-3:3000/v1/databases/example/instances/n1/stop + ``` + + +## Start Instance +Starts a specific instance within a database by scaling it back up. This operation is only valid when the instance is in a stopped state. A successful start instance operation will transition an instance state from stopped to starting to available, allowing normal access and use to continue and restarting any activities +* Transition: stopped → starting → available +* Retains same port as before stop +* Fails if port is already taken (a safety check) + +Example: Start a database “example” whose instance ID is “n1” + +=== "curl" + + ```sh + curl http://host-3:3000/v1/databases/example/instances/n1/start + ``` +## Restart Instance +Restarting an instance stops and then starts the same Postgres instance, either immediately or at a scheduled time. This is typically used to recover from errors or apply changes that require a restart. The instance keeps its identity and data, but experiences a brief downtime during the restart. +* 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 +Instance is not stable + +Example: Start a database “example” whose instance ID is “n1” +=== "curl" + + + ```sh + curl http://host-3:3000/v1/databases/example/instances/n1/restart + ``` + From 68d8e8ff9e0cecc39600acf8fe4a683296ef2148 Mon Sep 17 00:00:00 2001 From: Gabrielle Poncey Date: Tue, 13 Jan 2026 10:29:49 -0800 Subject: [PATCH 2/2] Revise Managing Database Instances documentation to align with other nearby docs --- docs/using/database-instances.md | 142 ++++++++++++++++++++----------- mkdocs.yml | 1 + 2 files changed, 95 insertions(+), 48 deletions(-) diff --git a/docs/using/database-instances.md b/docs/using/database-instances.md index 110b28bf..212746a3 100644 --- a/docs/using/database-instances.md +++ b/docs/using/database-instances.md @@ -1,34 +1,76 @@ -# Database Instances +# Managing Database Instances + + + + +A Database instance is: + -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 -(eg 68f50878-44d2-4524-a823-e31bd478706d-n1-689qacsi) -
+* Identified globally by an instance ID (eg 68f50878-44d2-4524-a823-e31bd478706d-n1-689qacsi) + Each instance maps to exactly one physical host, but a host can run multiple database instances as long as ports do not clash. -
-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. -Instances and port ownership -* Ports are unique per host -* Stopping an instance does not “free” the port -* Restarting preserves the same port -* Changing ports requires a plan update and a restart -* Port conflicts cause update failure - +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. + + + + +## Monitoring Instances + + +To access important information about a database instance, call the GetDatabase endpoint by specifying its database ID as shown below for a database "example". + + +In the following example, the `curl` command retrieves database information for a database named "example": + + +```sh +curl http://host-3:3000/v1/databases/example +``` + + +The endpoint will return the following information pertaining to the database. + + +* `created_at`: Timestamp when the database was created +* `id`: Database identifier +* `instances`: Array of instance objects containing instance-specific information +* `spec`: Database specification +* `state`: Current state of the database +* `updated_at`: Timestamp of last update + -Users in the database spec: -* Are reconciled onto each instance -* Get created / updated / dropped during instance configuration -* Must remain consistent across all instances -* Cannot conflict with system users +### Finding Instance IDs + + +The `instances` array contains information about a database instance, specifically: + + +* `id`: The instance identifier (e.g., `storefront-n1-689qacsi`) required for instance operations +* `node_name`: The node this instance belongs to (e.g., `n1`) +* `host_id`: The host where this instance runs +* `state`: Current operational state of the instance +* `postgres`: Postgres status information, including the `pending_restart` field which indicates if a configuration change requires a restart +* `connection_info`: Connection details for this instance +* `created_at` and `updated_at`: Instance timestamps + + +The `pending_restart` field within the `postgres` object is particularly important—when `true`, it signals that configuration changes have been applied that will only take effect after the instance is restarted. + + +### Instance States + + +Postgres instances can be in different states as a result of database operations (start/stop/restart/etc): -States -Instances can be in different states as a result of database operations (start/stop/restart/etc): * `available` * `starting` @@ -37,57 +79,61 @@ Instances can be in different states as a result of database operations (start/s * `failed` * `error` * `unknown` -

+## Stopping Instances + + +Stopping an instance shuts down the Postgres process for that specific instance by scaling it to zero. The instance no longer accepts connections and is taken out of service, but its data and configuration are preserved. Other instances in the same database can continue running. As Stop Instance removes a database instance from service without deleting it, it can be used to isolate an instance not currently in use but that is expected to be restarted later. -# Database Instance Operations -## Stop Instance -Stopping an instance shuts down the Postgres process for that specific instance by scaling it to zero. The instance no longer accepts connections and is taken out of service, but its data and configuration are preserved. Other instances in the same database can continue running. -As Stop Instance removes a database instance from service without deleting it, it can be used to isolate an instance not currently in use but that is expected to be restarted later. * Transition: available → stopping → stopped * Port remains reserved for this instance * 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” -=== "curl" +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 - ``` +```sh +curl http://host-3:3000/v1/databases/example/instances/n1/stop +``` + + +## Starting Instances + + +Starts a specific instance within a database by scaling it back up. This operation is only valid when the instance is in a stopped state. A successful start instance operation will transition an instance state from stopped to starting to available, allowing normal access and use to continue and restarting any activities. -## Start Instance -Starts a specific instance within a database by scaling it back up. This operation is only valid when the instance is in a stopped state. A successful start instance operation will transition an instance state from stopped to starting to available, allowing normal access and use to continue and restarting any activities * Transition: stopped → starting → available * Retains same port as before stop * Fails if port is already taken (a safety check) -Example: Start a database “example” whose instance ID is “n1” -=== "curl" +In the following example, the `curl` command starts an instance with ID "example-n1-689qacsi" for a database named "example": + + +```sh +curl -X POST http://host-3:3000/v1/databases/example/instances/example-n1-689qacsi/start +``` + + +## Restarting Instances + - ```sh - curl http://host-3:3000/v1/databases/example/instances/n1/start - ``` -## Restart Instance Restarting an instance stops and then starts the same Postgres instance, either immediately or at a scheduled time. This is typically used to recover from errors or apply changes that require a restart. The instance keeps its identity and data, but experiences a brief downtime during the restart. + + * 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 -Instance is not stable +* Restart is blocked if: No configuration changes require a restart, Another update is in progress, or Instance is not stable -Example: Start a database “example” whose instance ID is “n1” -=== "curl" +In the following example, the `curl` command restarts an instance with ID "example-n1-689qacsi" for a database named "example": - ```sh - curl http://host-3:3000/v1/databases/example/instances/n1/restart - ``` +```sh +curl -X POST http://host-3:3000/v1/databases/example/instances/example-n1-689qacsi/restart +``` diff --git a/mkdocs.yml b/mkdocs.yml index 09c97c07..6cb523d3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -78,6 +78,7 @@ nav: - Backup & Restore: using/backup-restore.md - Tasks & Logs: using/tasks-logs.md - Read Replicas: using/read-replicas.md + - Managing Database Instances: using/database-instances.md - Deleting a Database: using/delete-db.md - Migrating a Database: using/migrate-db.md - API: