From 52295be7b888ceece0f5b5dc6eb05dcbad2970d5 Mon Sep 17 00:00:00 2001 From: Gabrielle Poncey Date: Tue, 16 Dec 2025 14:04:08 -0800 Subject: [PATCH 1/8] 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/8] 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: From 5505b1a168638850b6d4fd80b34463ea3877917b Mon Sep 17 00:00:00 2001 From: Gabrielle Poncey Date: Wed, 21 Jan 2026 13:44:46 -0800 Subject: [PATCH 3/8] Revision to allign with coderabbit feedback --- docs/using/database-instances.md | 55 +++++++------------------------- 1 file changed, 11 insertions(+), 44 deletions(-) diff --git a/docs/using/database-instances.md b/docs/using/database-instances.md index 212746a3..cffaab3a 100644 --- a/docs/using/database-instances.md +++ b/docs/using/database-instances.md @@ -1,45 +1,28 @@ # Managing 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) - +* Identified globally by an instance ID (e.g., 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. - -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. ## 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": - +=== "curl" ```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 @@ -47,13 +30,10 @@ The endpoint will return the following information pertaining to the database. * `state`: Current state of the database * `updated_at`: Timestamp of last update - ### 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 @@ -62,70 +42,57 @@ The `instances` array contains information about a database instance, specifical * `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): - * `available` * `starting` * `stopping` +* `stopped` * `restarting` * `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. - * 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" - In the following example, the `curl` command stops an instance named "n1" for a database named "example": - +=== "curl" ```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 +``` ## 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. - * Transition: stopped → starting → available * Retains same port as before stop * Fails if port is already taken (a safety check) - In the following example, the `curl` command starts an instance with ID "example-n1-689qacsi" for a database named "example": - +=== "curl" ```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 ``` - ## Restarting Instances - 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, or Instance is not stable @@ -133,7 +100,7 @@ Restarting an instance stops and then starts the same Postgres instance, either In the following example, the `curl` command restarts an instance with ID "example-n1-689qacsi" for a database named "example": - +=== "curl" ```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 ``` From d2441c0ef940c0105d0fd7d0a19e7fdda934b10c Mon Sep 17 00:00:00 2001 From: Gabrielle Poncey Date: Wed, 21 Jan 2026 14:41:45 -0800 Subject: [PATCH 4/8] Revision to allign with final coderabbit feedback- corrected database id --- docs/using/database-instances.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/using/database-instances.md b/docs/using/database-instances.md index cffaab3a..c367af36 100644 --- a/docs/using/database-instances.md +++ b/docs/using/database-instances.md @@ -66,7 +66,7 @@ Stopping an instance shuts down the Postgres process for that specific instance * Other instances remain unaffected * A stopped instance continues to appear under list-databases with state: "stopped" -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 named "example-n1-689qacsi" for a database named "example": === "curl" ```sh From 8369bddb56bcfe36f36de86c6fc6c2eef1c621b9 Mon Sep 17 00:00:00 2001 From: susan-pgedge <130390403+susan-pgedge@users.noreply.github.com> Date: Tue, 27 Jan 2026 10:31:35 -0500 Subject: [PATCH 5/8] Update database-instances.md --- docs/using/database-instances.md | 137 ++++++++++++++++++++----------- 1 file changed, 90 insertions(+), 47 deletions(-) diff --git a/docs/using/database-instances.md b/docs/using/database-instances.md index c367af36..29eb780b 100644 --- a/docs/using/database-instances.md +++ b/docs/using/database-instances.md @@ -1,52 +1,73 @@ # Managing 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 (e.g., 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. +* a running Postgres server. +* bound to a specific host. +* identified by a node name (for example, n1). +* identified globally by an instance ID + (for example, 68f50878-44d2-4524-a823-e31bd478706d-n1-689qacsi). -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. +Each instance maps to exactly one physical host, but a host can run +multiple database instances as long as ports do not clash. -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. +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. -## 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". +Managing a database instance involves handling various operational needs +throughout its lifecycle. For example, modifying certain Postgres 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. -In the following example, the `curl` command retrieves database information for a database named "example": +## Monitoring Instances +To access important information about a database instance, call the +`GetDatabase` endpoint by specifying its database ID. In the following +command, `curl` retrieves database information for a database named `example`: === "curl" ```sh curl http://host-3:3000/v1/databases/example ``` -The endpoint will return the following information pertaining to the database. +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 +* `created_at` is the timestamp when the database was created. +* `id` is the database identifier. +* `instances` is an array of instance objects containing instance-specific + information. +* `spec` contains the database specification. +* `state` shows the current state of the database. +* `updated_at` is the timestamp of the last update. ### Finding Instance IDs -The `instances` array contains information about a database instance, specifically: +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 +* `id` is the instance identifier (e.g., `storefront-n1-689qacsi`) required + for instance operations. +* `node_name` is the node this instance belongs to (e.g., `n1`). +* `host_id` is the host where this instance runs. +* `state` is the current operational state of the instance. +* `postgres` contains Postgres status information, including the + `pending_restart` field which indicates if a configuration change requires a + restart. +* `connection_info` contains connection details for this instance. +* `created_at` and `updated_at` are 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. +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): +Postgres instances can be in different states as a result of database +operations; Postgres states may be: * `available` * `starting` @@ -59,48 +80,70 @@ Postgres instances can be in different states as a result of database operations ## 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. +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. -* 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" +!!! note -In the following example, the `curl` command stops an instance named "example-n1-689qacsi" for a database named "example": + As `Stop Instance` removes a database instance from service without + deleting it, it can be used toisolate an instance not currently in use but that is expected to be restarted later. + +* The transition is: available → stopping → stopped. +* The port remains reserved for this instance. +* Other instances remain unaffected. +* A stopped instance continues to appear under list-databases in a + `stopped` state. + +In the following example, the `curl` command stops an instance named +"example-n1-689qacsi" for a database named "example": === "curl" ```sh -curl -X POST http://host-3:3000/v1/databases/example/instances/example-n1-689qacsi/stop-instance - +curl -X POST \ + http://host-3:3000/v1/databases/example/instances/example-n1-689qacsi/stop-instance ``` ## 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. +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) +* The transition is: stopped → starting → available. +* The instance retains the same port as before stop. +* The operation fails if the port is already taken (a safety check). -In the following example, the `curl` command starts an instance with ID "example-n1-689qacsi" for a database named "example": +In the following example, the `curl` command starts an instance with the ID +`example-n1-689qacsi` for a database named `example`: === "curl" ```sh -curl -X POST http://host-3:3000/v1/databases/example/instances/example-n1-689qacsi/start-instance +curl -X POST \ + http://host-3:3000/v1/databases/example/instances/example-n1-689qacsi/start-instance ``` ## Restarting Instances -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. +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, or Instance is not stable +* If no `scheduled_at` is provided, the restart happens immediately. +* The transition is: available → restarting → available. +* Restart is blocked if no configuration changes require a restart, another + update is in progress, or the instance is not stable. -In the following example, the `curl` command restarts an instance with ID "example-n1-689qacsi" for a database named "example": +In the following example, the `curl` command restarts an instance with ID +`example-n1-689qacsi` for a database named `example`: === "curl" ```sh -curl -X POST http://host-3:3000/v1/databases/example/instances/example-n1-689qacsi/restart-instance +curl -X POST \ + http://host-3:3000/v1/databases/example/instances/example-n1-689qacsi/restart-instance ``` From 7f2fb00adcfe285862f23b81be043dfca2aa6de8 Mon Sep 17 00:00:00 2001 From: susan-pgedge <130390403+susan-pgedge@users.noreply.github.com> Date: Tue, 27 Jan 2026 10:35:56 -0500 Subject: [PATCH 6/8] Update database-instances.md One more formatting fix... --- docs/using/database-instances.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/using/database-instances.md b/docs/using/database-instances.md index 29eb780b..4af0fc49 100644 --- a/docs/using/database-instances.md +++ b/docs/using/database-instances.md @@ -97,7 +97,7 @@ instances in the same database can continue running. `stopped` state. In the following example, the `curl` command stops an instance named -"example-n1-689qacsi" for a database named "example": +`example-n1-689qacsi` for a database named `example`: === "curl" ```sh From fe59703d54c1262762ff33cd6d3169eb2dfb9689 Mon Sep 17 00:00:00 2001 From: Gabrielle Poncey Date: Tue, 27 Jan 2026 22:31:19 -0800 Subject: [PATCH 7/8] Revision to allign with curl indentation feedback --- docs/using/database-instances.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/using/database-instances.md b/docs/using/database-instances.md index 4af0fc49..73e858e9 100644 --- a/docs/using/database-instances.md +++ b/docs/using/database-instances.md @@ -100,10 +100,10 @@ In the following example, the `curl` command stops an instance named `example-n1-689qacsi` for a database named `example`: === "curl" -```sh -curl -X POST \ - http://host-3:3000/v1/databases/example/instances/example-n1-689qacsi/stop-instance -``` + + ```sh + curl -X POST http://host-3:3000/v1/databases/example/instances/example-n1-689qacsi/stop-instance + ``` ## Starting Instances @@ -121,10 +121,10 @@ In the following example, the `curl` command starts an instance with the ID `example-n1-689qacsi` for a database named `example`: === "curl" -```sh -curl -X POST \ - http://host-3:3000/v1/databases/example/instances/example-n1-689qacsi/start-instance -``` + + ```sh + curl -X POST http://host-3:3000/v1/databases/example/instances/example-n1-689qacsi/start-instance + ``` ## Restarting Instances @@ -143,7 +143,7 @@ In the following example, the `curl` command restarts an instance with ID `example-n1-689qacsi` for a database named `example`: === "curl" -```sh -curl -X POST \ - http://host-3:3000/v1/databases/example/instances/example-n1-689qacsi/restart-instance -``` + + ```sh + curl -X POST http://host-3:3000/v1/databases/example/instances/example-n1-689qacsi/restart-instance + ``` From a2659ec0d74e359733058d380b1d1e83d613568a Mon Sep 17 00:00:00 2001 From: Gabrielle Poncey Date: Wed, 28 Jan 2026 07:25:10 -0800 Subject: [PATCH 8/8] typo --- docs/using/database-instances.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/using/database-instances.md b/docs/using/database-instances.md index 73e858e9..e970824f 100644 --- a/docs/using/database-instances.md +++ b/docs/using/database-instances.md @@ -88,7 +88,7 @@ instances in the same database can continue running. !!! note As `Stop Instance` removes a database instance from service without - deleting it, it can be used toisolate an instance not currently in use but that is expected to be restarted later. + deleting it, it can be used to isolate an instance not currently in use but that is expected to be restarted later. * The transition is: available → stopping → stopped. * The port remains reserved for this instance.