DESCRIBE POSTGRES INSTANCE¶

使用此命令可以执行以下操作：

在异步操作（如 ALTER、CREATE 或 FORK）期间监控实例的状态。
检索连接详细信息，例如主机名。
检查高可用性状态、Postgres 版本和自定义服务器设置等配置设置。
查看 origin 字段来识别分叉实例及其来源。

DESCRIBE 可以缩写为 DESC。

另请参阅：: CREATE POSTGRES INSTANCE, ALTER POSTGRES INSTANCE, DROP POSTGRES INSTANCE, SHOW POSTGRES INSTANCES

语法¶

{ DESC | DESCRIBE } POSTGRES INSTANCE <name>

参数¶

name

指定要描述的 Postgres 实例的标识符。

如果标识符包含空格或特殊字符，则整个字符串必须放在双引号内。放在双引号内的标识符也区分大小写。

有关更多信息，请参阅标识符要求。

输出¶

命令的输出包括以下列，它们描述了对象的属性和元数据：

该命令以属性/值格式返回结果，而不是列式输出。每个属性显示为单独的行及其相应的值。


属性	描述
`name`	Postgres 实例的名称。
`owner`	拥有 Postgres 实例的角色。
`owner_role_type`	所有者角色的类型（例如，ROLE 或 DATABASE_ROLE）。
`created_on`	Postgres 实例的创建日期和时间。
`updated_on`	上次更新 Postgres 实例的日期和时间。
`type`	Postgres 实例的类型（例如，PRIMARY）。
`host`	用于连接到 Postgres 实例的主机名。
`privatelink_service_identifier`	专用链接服务的标识符（如果为实例配置了专用链接）。
`compute_family`	Postgres 实例的 :doc:`计算系列 </user-guide/snowflake-postgres/postgres-instance-sizes>`（实例大小）。
`storage_size_gb`	分配给 Postgres 实例的存储大小（单位为 GB）。
`postgres_version`	实例上运行的 Postgres 主要版本。
`postgres_settings`	为实例配置的自定义 Postgres 服务器设置。
`high_availability`	是否为实例（`true` 或 `false`）启用了高可用性。
`authentication_authority`	用于实例的身份验证方法（当前为 `POSTGRES`）。
`maintenance_window_start`	一天中可以启动维护时段的小时数（0-23，UTC），如未设置则为 `None`。
`state`	实例的当前状态。可能的值：`CREATING`、`RESTORING`、`STARTING`、`REPLAYING`、`FINALIZING`、`READY`、`RESTARTING`、`RESUMING`、`SUSPENDING`、`SUSPENDED`。
`comment`	Postgres 实例的注释，如未设置则为 `None`。
`origin`	Postgres 实例的来源（例如，如果从另一个实例分叉而来），若非分叉实例，则为 `None`。
`replicas`	与实例关联的读取副本列表。
`operations`	针对实例的待处理操作或正在进行的操作（例如，调整大小、升级、HA 启用）。
`network_policy`	附加到实例中的网络策略，如未设置则为 `None`。
`storage_integration`	实例所用的存储集成，如未设置则为 `None`。
`certificate`	SSL certificate for secure connections to the Postgres instance.

访问控制要求¶

用于执行此操作的角色必须至少具有以下权限：


权限	对象	备注
OPERATE 或 OWNERSHIP	Postgres 实例

有关创建具有指定权限集的自定义角色的说明，请参阅创建自定义角色。

有关对安全对象执行 SQL 操作的相应角色和权限授予的一般信息，请参阅访问控制概述。

使用说明¶

要对该命令的输出进行后处理，可以使用管道运算符 (->>) 或 RESULT_SCAN 函数。这两种构造都将输出视为可以查询的结果集。

例如，您可使用管道操作符或 RESULT_SCAN 函数，从 SHOW 命令输出中选择特定列或筛选行数据。

引用输出列时，为列名使用双引号标识符。例如，选择输出列 type，指定 SELECT "type"。

必须使用双引号标识符，因为 SHOW 命令的输出列名均为小写格式。双引号确保 SELECT 列表或 WHERE 子句中的列名，与已扫描的 SHOW 命令输出中的列名完全匹配。

使用此命令可在创建、修改或其他异步操作过程中检查实例的状态。operations 字段是 JSON 字符串，反映了在 CREATE POSTGRES INSTANCE 或 ALTER POSTGRES INSTANCE 操作过程中发生的任何操作序列。您可以等待 operations 字段变为空，或等待其中一个任务的值变为 ready。以下示例展示了在 ALTER POSTGRES INSTANCE 操作（用于更改 COMPUTE_FAMILY 设置）接近尾声时，operations 字段的值。

 {
   "upgrade" : {
     "state" : "UPGRADING",
     "start" : "2026-02-16 14:13:58.371 -0800",
     "duration" : "3m36s",
     "compute_family" : "BURST_M",
     "tasks" : [ {
       "flavor" : "resize",
       "state" : "creating"
     }, {
       "flavor" : "resize",
       "state" : "finalizing"
     }, {
       "flavor" : "resize",
       "state" : "ready"
     } ]
   }
}

示例¶

描述 Postgres 实例：

DESCRIBE POSTGRES INSTANCE my_postgres;

下面显示了该命令的典型输出：

+------------------------------------------------------------------------+
| property                       | value                                 |
|--------------------------------+---------------------------------------|
| name                           | MY_TEST_INSTANCE                      |
| owner                          | ACCOUNTADMIN                          |
| owner_role_type                | ROLE                                  |
| created_on                     | 2026-01-29 10:04:59.485 -0800         |
| updated_on                     | 2026-02-16 13:21:58.018 -0800         |
| type                           | PRIMARY                               |
| host                           | my-instance-hostname.us-west-2.aws    |
|                                | .postgres.snowflake.pp                |
| privatelink_service_identifier | None                                  |
| compute_family                 | BURST_S                               |
| storage_size_gb                | 10                                    |
| postgres_version               | 18                                    |
| postgres_settings              | {}                                    |
| high_availability              | false                                 |
| authentication_authority       | POSTGRES                              |
| maintenance_window_start       | None                                  |
| state                          | READY                                 |
| comment                        | None                                  |
| origin                         | None                                  |
| replicas                       |                                       |
| operations                     | { }                                   |
| network_policy                 | None                                  |
| storage_integration            | None                                  |
| certificate                    | -----BEGIN CERTIFICATE-----           |
|                                | ... several lines of certificate ...  |
|                                | -----END CERTIFICATE-----             |
|                                |                                       |
+------------------------------------------------------------------------+

结合使用 SHOW 与流运算符来查找实例，然后对其进行描述：

-- Find instances in a specific state
SHOW POSTGRES INSTANCES
  ->> SELECT "name", "state", "postgres_version"
      FROM $1
      WHERE "state" = 'READY' AND "postgres_version" = '17';

-- Then describe a specific instance for full details
DESCRIBE POSTGRES INSTANCE my_postgres;

使用流运算符提取特定属性：

DESCRIBE POSTGRES INSTANCE my_postgres
  ->> SELECT "property", "value"
      FROM $1
      WHERE "property" IN ('name', 'state', 'host',
        'postgres_version', 'high_availability');

检查实例的连接主机名：

DESCRIBE POSTGRES INSTANCE my_postgres
  ->> SELECT "value" AS hostname
      FROM $1
      WHERE "property" = 'host';