### Create Table on pgEdge Node

Source: https://github.com/pgedge/control-plane/blob/main/docs/installation/quickstart.md

Create a new table named 'example' on a specified pgEdge node. This command is part of the replication testing setup.

```bash
PGPASSWORD=password psql -h localhost -p 6432 -U admin example -c "CREATE TABLE example (id int primary key, data text);"
```

--------------------------------

### Verify Replication on pgEdge Node

Source: https://github.com/pgedge/control-plane/blob/main/docs/installation/quickstart.md

Select all rows from the 'example' table on a specified pgEdge node to verify that data has been replicated.

```bash
PGPASSWORD=password psql -h localhost -p 6432 -U admin example -c "SELECT * FROM example;"
```

--------------------------------

### Start pgEdge Control Plane

Source: https://github.com/pgedge/control-plane/blob/main/docs/installation/quickstart.md

Runs the pgEdge Control Plane as a Docker container. It configures essential environment variables, mounts necessary volumes (including the data directory and Docker socket), and uses host networking.

```bash
docker run --detach \
    --env PGEDGE_HOST_ID=host-1 \
    --env PGEDGE_DATA_DIR=${HOME}/pgedge/control-plane \
    --volume ${HOME}/pgedge/control-plane:${HOME}/pgedge/control-plane \
    --volume /var/run/docker.sock:/var/run/docker.sock \
    --network host \
    --name host-1 \
    ghcr.io/pgedge/control-plane \
    run
```

--------------------------------

### Insert Row into pgEdge Table

Source: https://github.com/pgedge/control-plane/blob/main/docs/installation/quickstart.md

Insert a row of data into the 'example' table on a specified pgEdge node. This action is used to test replication.

```bash
PGPASSWORD=password psql -h localhost -p 6433 -U admin example -c "INSERT INTO example (id, data) VALUES (1, 'Hello, pgEdge!');"
```

--------------------------------

### Install Project-Level Tools

Source: https://github.com/pgedge/control-plane/blob/main/docs/development/e2e-tests.md

Installs the necessary project-level tools required for various operations, including setting up test fixtures. This command should be run before proceeding with other setup or test execution steps.

```shell
make install-tools
```

--------------------------------

### List pgEdge Databases via Control Plane API

Source: https://github.com/pgedge/control-plane/blob/main/docs/installation/quickstart.md

Send a GET request to the pgEdge control plane API to list all active database instances. Used to monitor deletion progress.

```curl
curl http://localhost:3000/v1/databases
```

--------------------------------

### Initialize Control Plane Cluster

Source: https://github.com/pgedge/control-plane/blob/main/docs/installation/quickstart.md

Initializes the pgEdge Control Plane cluster. This command is typically used to generate a join token for adding more hosts to the cluster. For this quickstart, it's used to start the initialization process.

```bash
curl http://localhost:3000/v1/cluster/init
```

--------------------------------

### Example Control Plane Service Definition with Etcd Client Mode

Source: https://github.com/pgedge/control-plane/blob/main/docs/installation/installation.md

An example of a Docker Compose service definition for a pgedge Control Plane server configured to run in Etcd client mode. It includes essential environment variables, volume mounts, network configuration, and deployment constraints.

```yaml
  host-4:
    image: ghcr.io/pgedge/control-plane:<< control_plane_version >>
    command: run
    environment:
      - PGEDGE_HOST_ID=host-4
      - PGEDGE_DATA_DIR=/data/pgedge/control-plane
      - PGEDGE_ETCD_MODE=client
    volumes:
      - /data/pgedge/control-plane:/data/pgedge/control-plane
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - host
    deploy:
      placement:
        constraints:
          - node.id==g0nw8mhfox4hox1ny2fgk4x6h
```

--------------------------------

### Start Database Instance (Bash)

Source: https://context7.com/pgedge/control-plane/llms.txt

Starts a database instance that has been previously stopped. This operation is straightforward and requires only the instance identifier. The response confirms the task initiation.

```bash
curl -X POST "http://localhost:3000/v1/databases/storefront/instances/storefront-n1-689qacsi/start-instance"

# Response
{
  "task": {
    "task_id": "019783f4-75f4-71e7-85a3-c9b96b345d77",
    "type": "start_instance",
    "status": "pending"
  }
```

--------------------------------

### Local Development Commands (Bash)

Source: https://github.com/pgedge/control-plane/blob/main/CLAUDE.md

Commands for starting, building, stopping, and tearing down the local Docker Compose development environment. These facilitate rapid iteration during development.

```bash
# Start local Docker compose-based development environment in foreground with hot reload
make dev-watch

# Rebuild and restart after changes
make dev-build

# Stop development environment
make dev-down

# Complete teardown (removes databases, networks, data)
make dev-teardown
```

--------------------------------

### Prerequisites: Initialize Buildx Builder and Start Local Registry

Source: https://github.com/pgedge/control-plane/blob/main/docs/development/cluster-tests.md

Commands to set up the necessary environment for running tests. This includes starting a local container registry and initializing the buildx builder, which are essential for building and managing container images.

```shell
make start-local-registry
make buildx-init
```

--------------------------------

### List Database Containers

Source: https://github.com/pgedge/control-plane/blob/main/docs/installation/quickstart.md

Retrieve container IDs for pgEdge database instances. This is a prerequisite for connecting via `docker exec`.

```sh
docker ps --filter label=pgedge.database.id=example
```

--------------------------------

### Docker Swarm Placement Constraint Example

Source: https://github.com/pgedge/control-plane/blob/main/docs/installation/installation.md

This snippet demonstrates how to use the `deploy: placement: constraints` property within a Docker Swarm service definition. It specifies that a service should only run on a node matching the provided `node.id`, ensuring controlled deployment across the cluster.

```yaml
deploy:
  placement:
    constraints:
      - node.id==our0m7sn7gjops9klp7j1nvu7
```

--------------------------------

### Start Local Docker Registry (Shell)

Source: https://github.com/pgedge/control-plane/blob/main/docs/development/development.md

Command to start a local Docker registry, which is a prerequisite for building and publishing pre-release control plane images to a local environment.

```shell
make start-local-registry
```

--------------------------------

### Example Usage of Gather E2E DB Info Script

Source: https://github.com/pgedge/control-plane/blob/main/hack/gather-e2e-db-info.md

Provides a concrete example of executing the `gather-e2e-db-info.sh` script. It shows the command with a sample path to `test_config.yaml` and a database ID ('storefront'), illustrating how to invoke the script for a specific E2E fixture.

```shell
./hack/gather-e2e-db-info.sh ./e2e/fixtures/outputs/ec2.test_config.yaml storefront
```

--------------------------------

### Start Database Instance

Source: https://github.com/pgedge/control-plane/blob/main/docs/using/database-instances.md

Starts a specific database instance that is in a stopped state, making it available for connections again.

```APIDOC
## POST /v1/databases/{database_id}/instances/{instance_id}/start-instance

### Description
Starts a specific database instance that is in a 'stopped' state. This operation transitions the instance state from 'stopped' to 'starting' and then to 'available', allowing normal access and use.

### Method
POST

### Endpoint
/v1/databases/{database_id}/instances/{instance_id}/start-instance

### Parameters
#### Path Parameters
- **database_id** (string) - Required - The identifier of the database containing the instance.
- **instance_id** (string) - Required - The identifier of the instance to start.

### Request Example
```sh
curl -X POST http://host-3:3000/v1/databases/example/instances/example-n1-689qacsi/start-instance
```

### Response
#### Success Response (200)
Indicates that the start instance operation was successful. The response body may contain updated instance status.

#### Response Example
```json
{
  "message": "Instance example-n1-689qacsi started successfully."
}
```
```

--------------------------------

### Install Bruno API Client (macOS)

Source: https://github.com/pgedge/control-plane/blob/main/docs/development/running-locally.md

Installs the Bruno API client on macOS using the Homebrew package manager. This is a prerequisite for using the Bruno collection and its features.

```shell
brew install bruno
```

--------------------------------

### Install Development Environment Prerequisites with Homebrew

Source: https://github.com/pgedge/control-plane/blob/main/hack/dev-env.md

Installs essential command-line tools required for the development environment using the Homebrew package manager. These tools include `jq`, `yq`, `coreutils`, `sk`, `restish`, and `etcd`.

```shell
brew install \
    jq \
    yq \
    coreutils \
    sk \
    rest-sh/tap/restish \
    etcd
```

--------------------------------

### Install Prerequisites for Gather E2E DB Info

Source: https://github.com/pgedge/control-plane/blob/main/hack/gather-e2e-db-info.md

Installs the necessary tools (`jq`, `yq`, `coreutils`) required by the `gather-e2e-db-info.sh` script using Homebrew. These tools are essential for processing YAML files and other system utilities.

```shell
brew install jq yq coreutils
```

--------------------------------

### Build and Serve Documentation Locally

Source: https://github.com/pgedge/control-plane/blob/main/README.md

This command initiates the local documentation server using Make. It requires Make to be installed and configured for the project. The server will typically be accessible at http://localhost:8000.

```sh
make docs
```

--------------------------------

### Remove pgEdge Data Directory

Source: https://github.com/pgedge/control-plane/blob/main/docs/installation/quickstart.md

Remove the pgEdge data directory created during installation using the `rm -rf` command.

```sh
rm -rf ~/pgedge/control-plane
```

--------------------------------

### Connect to Database Instance using psql

Source: https://github.com/pgedge/control-plane/blob/main/docs/installation/quickstart.md

Connects to a specific node of the pgEdge database cluster using the `psql` command-line client. Requires the password, host (localhost), port, username, and database name.

```bash
# To connect to the 'n1' node's instance:
PGPASSWORD=password psql -h localhost -p 6432 -U admin example

# To connect to the 'n2' node's instance:
PGPASSWORD=password psql -h localhost -p 6433 -U admin example
```

--------------------------------

### Create Data Directory

Source: https://github.com/pgedge/control-plane/blob/main/docs/installation/quickstart.md

Creates a directory to store Control Plane's internal database files and Postgres data directories. This directory path must be consistent between the host and the container.

```bash
mkdir -p ~/pgedge/control-plane
```

--------------------------------

### Connect to pgEdge Node using psql

Source: https://github.com/pgedge/control-plane/blob/main/docs/installation/quickstart.md

Connect to a specific pgEdge node's database instance using the psql client. Requires PGPASSWORD environment variable for authentication.

```bash
PGPASSWORD=password psql -h localhost -p 6434 -U admin example
```

--------------------------------

### Initialize Cluster and Create Database using Restish

Source: https://github.com/pgedge/control-plane/blob/main/docs/development/running-locally.md

Demonstrates initializing a new cluster and creating a new database using the 'restish' command-line tool. This involves a sequence of commands to set up nodes and define database properties, including users and their attributes.

```shell
restish control-plane-local-1 init-cluster
restish control-plane-local-2 join-cluster "$(restish control-plane-local-1 get-join-token)"
restish control-plane-local-3 join-cluster "$(restish control-plane-local-1 get-join-token)"
restish control-plane-local-4 join-cluster "$(restish control-plane-local-1 get-join-token)"
restish control-plane-local-5 join-cluster "$(restish control-plane-local-1 get-join-token)"
restish control-plane-local-6 join-cluster "$(restish control-plane-local-1 get-join-token)"
restish control-plane-local-1 create-database '{
  "id": "storefront",
  "spec": {
    "database_name": "storefront",
    "database_users": [
      {
        "username": "admin",
        "password": "password",
        "db_owner": true,
        "attributes": ["SUPERUSER", "LOGIN"]
      },
      {
        "username": "app",
        "password": "password",
        "attributes": ["LOGIN"],
        "roles": ["pgedge_application"]
      }
    ],
    "nodes": [
      { "name": "n1", "host_ids": ["host-1", "host-4"] },
      { "name": "n2", "host_ids": ["host-2", "host-5"] },
      { "name": "n3", "host_ids": ["host-3", "host-6"] }
    ]
  }
}'
```

--------------------------------

### Load Northwind Sample Dataset into pgEdge

Source: https://github.com/pgedge/control-plane/blob/main/docs/installation/quickstart.md

Load the Northwind sample dataset into a pgEdge database instance using `curl` to download the SQL dump and piping it to `psql`.

```bash
curl https://downloads.pgedge.com/platform/examples/northwind/northwind.sql \
    | PGPASSWORD=password psql -h localhost -p 6432 -U admin example
```

--------------------------------

### Fetch Control Plane Join Token (curl)

Source: https://github.com/pgedge/control-plane/blob/main/docs/installation/installation.md

Retrieves the join token for a Control Plane cluster by making a GET request to the /v1/cluster/join-token endpoint. This token can be used to add new nodes to the cluster.

```curl
curl http://node_ip_address:3000/v1/cluster/join-token
```

--------------------------------

### Generate Root CA and Server/Client Certificates with step CLI

Source: https://github.com/pgedge/control-plane/blob/main/docs/installation/mtls.md

This snippet shows how to use the 'step' CLI to generate a root CA certificate and key, followed by certificates for individual hosts (servers) and a client. It configures Subject Alternative Names (SANs) with IP addresses and sets Extended Key Usage for server and client authentication. The generated keys are passwordless for simplicity in this tutorial.

```shell
# Generate a root certificate authority. This command will prompt for a password
# to encrypt the CA key.
step certificate create tutorial ./ca.crt ./ca.key \
  --profile=root-ca \
  --not-after 8760h

# Generate certificates for each server. These commands will prompt for the CA
# key, but each new key is passwordless. Note that we're using the hostname as
# the Common Name (CN) and including the IP address as a Subject Alternative
# Name (SAN). The step CLI's 'leaf' profile includes both server and client
# authentication in the Extended Key Usage (EKU).
step certificate create host-1 host-1.crt host-1.key \
  --san '192.168.105.2' \
  --no-password \
  --insecure \
  --profile leaf \
  --not-after 2160h \
  --ca ./ca.crt \
  --ca-key ./ca.key

step certificate create host-2 host-2.crt host-2.key \
  --san '192.168.105.3' \
  --no-password \
  --insecure \
  --profile leaf \
  --not-after 2160h \
  --ca ./ca.crt \
  --ca-key ./ca.key

step certificate create host-3 host-3.crt host-3.key \
  --san '192.168.105.4' \
  --no-password \
  --insecure \
  --profile leaf \
  --not-after 2160h \
  --ca ./ca.crt \
  --ca-key ./ca.key

# Generate the client certificate. We're also using a passwordless key here for
# simplicity, but this will depend on your use case.
step certificate create client client.crt client.key \
  --no-password \
  --insecure \
  --profile leaf \
  --not-after 2160h \
  --ca ./ca.crt \
  --ca-key ./ca.key
```

--------------------------------

### Initialize Control Plane Cluster (curl)

Source: https://github.com/pgedge/control-plane/blob/main/docs/installation/installation.md

Initializes a new Control Plane cluster by making a GET request to the /v1/cluster/init endpoint. This operation returns a join token and server URL necessary for other nodes to join the cluster.

```curl
curl http://node_ip_address:3000/v1/cluster/init
```

--------------------------------

### Start Control Plane Development Environment

Source: https://github.com/pgedge/control-plane/blob/main/docs/development/running-locally.md

Builds and runs the Control Plane in a development environment using Docker Compose in watch mode. This command assumes you are in the root of the 'control-plane' repository and have Docker Desktop installed and configured.

```sh
make dev-watch
```

--------------------------------

### Run E2E Tests with Docker Compose

Source: https://github.com/pgedge/control-plane/blob/main/docs/development/e2e-tests.md

Starts the Control Plane servers using the 'dev-watch' make target and then runs the end-to-end tests using the 'test-e2e' make target in a separate terminal. This setup is for local testing with Docker Compose.

```shell
make dev-watch
make test-e2e
```

--------------------------------

### Connect to pgEdge Node using docker exec

Source: https://github.com/pgedge/control-plane/blob/main/docs/installation/quickstart.md

Connect to a specific pgEdge node's database instance from within its container using `docker exec`. Requires the container ID obtained from `docker ps`.

```sh
docker exec -it <container ID> psql -U admin example
```

--------------------------------

### Install pgedge-cp-env Oh My Zsh Plugin

Source: https://github.com/pgedge/control-plane/blob/main/hack/dev-env.md

This script installs the `pgedge-cp-env` Oh My Zsh plugin, which displays the current `${CP_ENV}` value in the prompt. It requires Oh My Zsh to be installed and uses the `ZSH_CUSTOM` environment variable to determine the installation path.

```shell
# ZSH_CUSTOM is where you can install custom themes and plugins for Oh My Zsh.
# We need to propagate this variable to the script when we run it.
ZSH_CUSTOM=$ZSH_CUSTOM ./hack/pgedge-cp-env.install.zsh
```

--------------------------------

### Install Restish CLI Tool

Source: https://github.com/pgedge/control-plane/blob/main/docs/development/running-locally.md

Installs the Restish command-line interface tool using Homebrew. Restish is used to interact with REST APIs that expose an OpenAPI specification, such as the Control Plane API. Ensure Homebrew is installed before running this command.

```sh
brew install rest-sh/tap/restish
```

--------------------------------

### Create pgEdge Database Cluster

Source: https://github.com/pgedge/control-plane/blob/main/docs/installation/quickstart.md

Creates a new pgEdge Distributed Postgres database with a specified ID and configuration. It defines database users, nodes, and their ports. The creation is asynchronous.

```bash
curl -X POST http://localhost:3000/v1/databases \
    -H 'Content-Type:application/json' \
    --data '{ \
        "id": "example", \
        "spec": { \
            "database_name": "example", \
            "database_users": [ \
                { \
                    "username": "admin", \
                    "password": "password", \
                    "db_owner": true, \
                    "attributes": ["SUPERUSER", "LOGIN"] \
                } \
            ], \
            "nodes": [ \
                { "name": "n1", "port": 6432, "host_ids": ["host-1"] }, \
                { "name": "n2", "port": 6433, "host_ids": ["host-1"] }, \
                { "name": "n3", "port": 6434, "host_ids": ["host-1"] } \
            ] \
        } \
    }'
```

--------------------------------

### GET /v1/databases/{database_id} - Get Database Status

Source: https://github.com/pgedge/control-plane/blob/main/docs/using/update-db.md

Retrieve the current status and configuration of a specific database.

```APIDOC
## GET /v1/databases/{database_id}

### Description
Retrieves the current status and configuration of a specific database. This is useful for monitoring the state of the database after an update or for general status checks.

### Method
GET

### Endpoint
`/v1/databases/{database_id}`

### Parameters
#### Path Parameters
- **database_id** (string) - Required - The unique identifier of the database to retrieve.

#### Query Parameters
None

#### Request Body
None

### Request Example
```sh
curl http://localhost:3000/v1/databases/example
```

### Response
#### Success Response (200)
- **status** (string) - The current status of the database (e.g., 'running', 'updating', 'failed').
- **spec** (object) - The current specification of the database (similar to the update request body).

#### Response Example
```json
{
  "status": "running",
  "spec": {
    "database_name": "example",
    "database_users": [
      {
        "username": "admin",
        "db_owner": true,
        "attributes": ["SUPERUSER", "LOGIN"]
      }
    ],
    "port": 5432,
    "nodes": [
      { "name": "n1", "host_ids": ["host-1"] },
      { "name": "n2", "host_ids": ["host-2"] },
      { "name": "n3", "host_ids": ["host-3"] },
      { "name": "n4", "host_ids": ["host-4"] }
    ]
  }
}
```
```

--------------------------------

### Go Client Usage Example

Source: https://context7.com/pgedge/control-plane/llms.txt

Demonstrates how to use the pgEdge Control Plane Go client library to interact with the API, including listing, creating databases, and managing tasks.

```APIDOC
## Go Client Usage

The Control Plane provides a Go client library for programmatic access to the API.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "net/url"

    "github.com/pgEdge/control-plane/client"
    api "github.com/pgEdge/control-plane/api/apiv1/gen/control_plane"
)

func main() {
    // Create client configuration
    serverURL, _ := url.Parse("http://localhost:3000")
    cfg := client.NewHTTPServerConfig("host-1", serverURL)

    // Create client
    c := client.NewClient(cfg)
    ctx := context.Background()

    // List databases
    databases, err := c.ListDatabases(ctx)
    if err != nil {
        log.Fatal(err)
    }

    for _, db := range databases.Databases {
        fmt.Printf("Database: %s, State: %s\n", db.ID, db.State)
    }

    // Create a new database
    createResp, err := c.CreateDatabase(ctx, &api.CreateDatabaseRequest{
        ID: "my-app",
        Spec: &api.DatabaseSpec{
            DatabaseName: "my_app",
            Port:         5432,
            DatabaseUsers: []*api.DatabaseUserSpec{
                {
                    Username:   "admin",
                    Password:   "secure_password",
                    DbOwner:    true,
                    Attributes: []string{"LOGIN", "SUPERUSER"},
                },
            },
            Nodes: []*api.DatabaseNodeSpec{
                {Name: "n1", HostIds: []string{"us-east-1"}},
                {Name: "n2", HostIds: []string{"ap-south-1"}},
            },
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    // Wait for the task to complete
    task, err := c.WaitForDatabaseTask(ctx, &api.GetDatabaseTaskPayload{
        DatabaseID: "my-app",
        TaskID:     createResp.Task.TaskID,
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Task %s completed with status: %s\n", task.TaskID, task.Status)
}
```
```

--------------------------------

### Install Lima VM Runner

Source: https://github.com/pgedge/control-plane/blob/main/docs/development/e2e-tests.md

Installs Lima, a virtual machine runner that is well-suited for macOS. This is a prerequisite for setting up the test fixtures.

```shell
# Installation through homebrew

brew install lima
```

--------------------------------

### Initialize Docker Swarm

Source: https://github.com/pgedge/control-plane/blob/main/docs/installation/quickstart.md

Initializes Docker Swarm mode on the Docker daemon. This is a prerequisite for running pgEdge Control Plane in a clustered environment.

```bash
docker swarm init
```

--------------------------------

### Install Ansible with pipx

Source: https://github.com/pgedge/control-plane/blob/main/docs/development/e2e-tests.md

Installs Ansible and its dependencies using pipx. It also injects specific versions of botocore and boto3, which are required for certain functionalities.

```shell
pipx install --include-deps ansible
pipx inject ansible 'botocore>=1.34.0'
pipx inject ansible 'boto3>=1.34.0'
```

--------------------------------

### Create Database (Bash)

Source: https://context7.com/pgedge/control-plane/llms.txt

Creates a new database with specified configurations, including nodes and users. This POST request to `/v1/databases` allows for minimal setup or more complex configurations like S3 backups or restoring from backups. Requires a JSON payload with database ID and specifications.

```bash
# Minimal database creation
curl -X POST "http://localhost:3000/v1/databases" \
  -H "Content-Type: application/json" \
  -d '{ \
    "id": "storefront", \
    "spec": { \
      "database_name": "storefront", \
      "port": 5432, \
      "database_users": [ \
        { \
          "username": "admin", \
          "password": "secure_password", \
          "db_owner": true, \
          "attributes": ["LOGIN", "SUPERUSER"] \
        } \
      ], \
      "nodes": [ \
        {"name": "n1", "host_ids": ["us-east-1"]}, \
        {"name": "n2", "host_ids": ["ap-south-1"]}, \
        {"name": "n3", "host_ids": ["eu-central-1"]} \
      ] \
    } \
  }'

# Response
{
  "database": {
    "id": "storefront",
    "state": "creating",
    "created_at": "2025-06-18T16:52:05Z",
    "updated_at": "2025-06-18T16:52:05Z",
    "spec": {
      "database_name": "storefront",
      "port": 5432,
      "postgres_version": "17.6",
      "spock_version": "5",
      "nodes": [
        {"name": "n1", "host_ids": ["us-east-1"]},
        {"name": "n2", "host_ids": ["ap-south-1"]},
        {"name": "n3", "host_ids": ["eu-central-1"]}
      ]
    }
  },
  "task": {
    "task_id": "019783f4-75f4-71e7-85a3-c9b96b345d77",
    "database_id": "storefront",
    "type": "create",
    "status": "pending",
    "created_at": "2025-06-18T16:52:05Z"
  }
}
```

```bash
# Create Database with S3 Backups
curl -X POST "http://localhost:3000/v1/databases" \
  -H "Content-Type: application/json" \
  -d '{ \
    "id": "storefront", \
    "spec": { \
      "database_name": "storefront", \
      "port": 5432, \
      "database_users": [ \
        { \
          "username": "admin", \
          "password": "password", \
          "db_owner": true, \
          "attributes": ["LOGIN", "SUPERUSER"] \
        } \
      ], \
      "nodes": [ \
        { \
          "name": "n1", \
          "host_ids": ["us-east-1"], \
          "backup_config": { \
            "repositories": [{ \
              "type": "s3", \
              "s3_bucket": "storefront-db-backups-us-east-1", \
              "s3_region": "us-east-1" \
            }] \
          } \
        }, \
        { \
          "name": "n2", \
          "host_ids": ["ap-south-1"], \
          "backup_config": { \
            "repositories": [{ \
              "type": "s3", \
              "s3_bucket": "storefront-db-backups-ap-south-1" \
            }] \
          } \
        } \
      ] \
    } \
  }'
```

```bash
# Create Database from Backup
curl -X POST "http://localhost:3000/v1/databases" \
  -H "Content-Type: application/json" \
  -d '{ \
    "id": "storefront-staging", \
    "spec": { \
      "database_name": "storefront", \
      "port": 5432, \
      "database_users": [ \
        { \
          "username": "admin", \
          "password": "password", \
          "db_owner": true, \
          "attributes": ["LOGIN", "SUPERUSER"] \
        } \
      ], \
      "restore_config": { \
        "source_database_id": "storefront", \
        "source_database_name": "storefront", \
        "source_node_name": "n1", \
        "repository": { \
          "type": "s3", \
          "s3_bucket": "storefront-db-backups-us-east-1" \
        } \
      }, \
      "nodes": [ \
        {"name": "n1", "host_ids": ["us-east-1"]}, \
        {"name": "n2", "host_ids": ["ap-south-1"]} \
      ] \
    } \
  }'
```

--------------------------------

### Create Control Plane Database Instance (curl)

Source: https://github.com/pgedge/control-plane/blob/main/docs/using/migrate-db.md

Creates a new single-instance Control Plane database with specified name and user roles. This command configures the database name, admin and app user credentials, and initial node setup.

```curl
curl -X POST http://host-1:3000/v1/databases \
    -H 'Content-Type:application/json' \
    --data '{\
        "id": "myapp",\
        "spec": {\
            "database_name": "myapp",\
            "database_users": [\
                {\"username\": \"admin\",\
                 \"password\": \"password\",\
                 \"db_owner\": true,\
                 \"attributes\": [\"SUPERUSER\", \"LOGIN\"]\
                },\
                {\"username\": \"app\",\
                 \"password\": \"password\",\
                 \"db_owner\": false,\
                 \"attributes\": [\"LOGIN\"]\
                }\
            ],\
            "nodes": [\
                { \"name\": \"n1\", \"host_ids\": [\"host-1\"], \"port\": 5432 }\
            ]\
        }
    }'
```

--------------------------------

### GET /v1/databases/{database_id} - Get Database Status

Source: https://github.com/pgedge/control-plane/blob/main/docs/using/create-db.md

Retrieve the current status of a database by its ID. Inspect the 'state' field for the database's current status.

```APIDOC
## GET /v1/databases/{database_id}

### Description
Retrieves the current status and specification of a specific database.

### Method
GET

### Endpoint
/v1/databases/{database_id}

### Parameters
#### Path Parameters
- **database_id** (string) - Required - The unique identifier of the database to retrieve.

### Response
#### Success Response (200)
- **state** (string) - The current state of the database (e.g., "RUNNING", "CREATING", "FAILED").
- **database_spec** (object) - The specification of the database.

#### Response Example
```json
{
  "state": "RUNNING",
  "database_spec": {
    "id": "example",
    "spec": {
      "database_name": "example",
      "database_users": [
        {
          "username": "admin",
          "password": "password",
          "db_owner": true,
          "attributes": ["SUPERUSER", "LOGIN"]
        }
      ],
      "port": 5432,
      "nodes": [
        { "name": "n1", "host_ids": ["host-1"] },
        { "name": "n2", "host_ids": ["host-2"] },
        { "name": "n3", "host_ids": ["host-3"] }
      ]
    }
  }
}
```
```

--------------------------------

### Install socket_vmnet for x86_64 Emulation

Source: https://github.com/pgedge/control-plane/blob/main/docs/development/e2e-tests.md

Installs socket_vmnet, which is required for x86_64 emulation within Lima. This involves downloading the latest release, extracting it, and configuring sudoers for Lima.

```shell
VERSION="$(curl -fsSL https://api.github.com/repos/lima-vm/socket_vmnet/releases/latest | jq -r .tag_name)"
FILE="socket_vmnet-${VERSION:1}-$(uname -m).tar.gz"

# Download the binary archive
curl -OSL "https://github.com/lima-vm/socket_vmnet/releases/download/${VERSION}/${FILE}"

# Install /opt/socket_vmnet from the binary archive
sudo tar Cxzvf / "${FILE}" opt/socket_vmnet

# Add lima entries to sudoers so that it can invoke socket_vmnet
limactl sudoers | sudo tee /etc/sudoers.d/lima
```

--------------------------------

### Documentation Build Command (Bash)

Source: https://github.com/pgedge/control-plane/blob/main/CLAUDE.md

Command to build and serve the project's documentation locally. This allows developers to preview documentation changes before committing.

```bash
# Build and serve documentation locally at http://localhost:8000
make docs
```