openapi: 3.2.0
info:
  title: Ubicloud Postgres Database API
  version: 0.1.0
  contact:
    url: https://www.ubicloud.com/
    email: support@ubicloud.com
  license:
    name: GNU Affero General Public License v3.0 (AGPL-3.0)
    url: https://www.gnu.org/licenses/agpl-3.0.en.html
  description: 'Operations tagged Postgres Database across 2 of this provider''s published API definitions: ubicloud-openapi.yml, ubicloud-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.ubicloud.com
security:
- BearerAuth: []
tags:
- description: Postgres Database Operations
  name: Postgres Database
paths:
  /project/{project_id}/location/{location}/postgres:
    get:
      operationId: listLocationPostgresDatabases
      summary: List PostgreSQL databases in a location
      parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/start_after'
      - $ref: '#/components/parameters/page_size'
      - $ref: '#/components/parameters/order_column'
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabases'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}:
    parameters:
    - $ref: '#/components/parameters/project_id'
    - $ref: '#/components/parameters/location'
    - $ref: '#/components/parameters/postgres_database_reference'
    delete:
      operationId: deletePostgresDatabase
      summary: Delete a PostgreSQL database
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    get:
      operationId: getPostgresDatabaseDetails
      summary: Get PostgreSQL database details
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    post:
      operationId: createPostgresDatabase
      summary: Create a new PostgreSQL database
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                flavor:
                  description: Deprecated. standard is the only flavor and the default, so omit this.
                  type: string
                  deprecated: true
                ha_type:
                  description: High availability type
                  type: string
                size:
                  description: Requested size for the underlying VM
                  type: string
                storage_size:
                  description: Requested storage size in GiB
                  type: integer
                version:
                  description: PostgreSQL version
                  type: string
                  enum:
                  - '16'
                  - '17'
                  - '18'
                restrict_by_default:
                  description: Whether to restrict access by default (if so, firewall rules must be added to access)
                  type: boolean
                private_subnet_name:
                  description: Name for the private subnet (if not provided, a name will be auto-generated)
                  type: string
                pg_config:
                  type: object
                  example:
                    max_connections: '100'
                  additionalProperties:
                    type: string
                pgbouncer_config:
                  type: object
                  example:
                    max_client_conn: '100'
                  additionalProperties:
                    type: string
                tags:
                  description: Tags for the Postgres Database
                  type: array
                  items:
                    $ref: '#/components/schemas/PostgresTag'
              additionalProperties: false
              required:
              - size
              - storage_size
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    patch:
      operationId: patchPostgresDatabase
      summary: Update a PostgreSQL database
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ha_type:
                  description: High availability type
                  type: string
                size:
                  description: Requested size for the underlying VM
                  type: string
                storage_size:
                  description: Requested storage size in GiB
                  type: integer
                tags:
                  description: Tags for the Postgres Database
                  type: array
                  items:
                    $ref: '#/components/schemas/PostgresTag'
              additionalProperties: false
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/backup:
    parameters:
    - $ref: '#/components/parameters/project_id'
    - $ref: '#/components/parameters/location'
    - $ref: '#/components/parameters/postgres_database_reference'
    get:
      operationId: listPostgresDatabaseBackups
      summary: List backups for a specific PostgreSQL database
      responses:
        '200':
          $ref: '#/components/responses/PostgresBackups'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/backup-credentials:
    parameters:
    - $ref: '#/components/parameters/project_id'
    - $ref: '#/components/parameters/location'
    - $ref: '#/components/parameters/postgres_database_reference'
    post:
      operationId: createPostgresDatabaseBackupCredentials
      summary: Create temporary, read-only credentials for downloading backups directly from…
      responses:
        '200':
          $ref: '#/components/responses/PostgresBackupCredentials'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/ca-certificates:
    parameters:
    - $ref: '#/components/parameters/project_id'
    - $ref: '#/components/parameters/location'
    - $ref: '#/components/parameters/postgres_database_reference'
    get:
      operationId: getPostgresCACertificatesByName
      summary: Download CA certificates for a PostgreSQL database
      responses:
        '200':
          description: CA certificate file in pem format
          headers:
            Content-Disposition:
              schema:
                type: string
                example: attachment; filename="postgres-ca-certificate.pem"
          content:
            application/x-pem-file:
              schema:
                type: string
                format: binary
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/cert/add-auth-user:
    parameters:
    - $ref: '#/components/parameters/project_id'
    - $ref: '#/components/parameters/location'
    - $ref: '#/components/parameters/postgres_database_reference'
    post:
      operationId: addCertAuthUser
      summary: Add provided name to list of users with certificate authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CertAuthUserRequest'
      responses:
        '200':
          $ref: '#/components/responses/CertAuthUserList'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/cert/create-client-keypair:
    parameters:
    - $ref: '#/components/parameters/project_id'
    - $ref: '#/components/parameters/location'
    - $ref: '#/components/parameters/postgres_database_reference'
    post:
      operationId: createClientCertKeypair
      summary: Create and return client certificate keypair with requested common name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                common_name:
                  description: CN for cert
                  type: string
                duration:
                  description: Duration before expiry, in seconds
                  type: integer
              additionalProperties: false
      responses:
        '200':
          description: certificate keypair file in pem format
          headers:
            Content-Disposition:
              schema:
                type: string
                example: attachment; filename="certificate-key.pem"
          content:
            application/x-pem-file:
              schema:
                type: string
                format: binary
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/cert/remove-auth-user:
    parameters:
    - $ref: '#/components/parameters/project_id'
    - $ref: '#/components/parameters/location'
    - $ref: '#/components/parameters/postgres_database_reference'
    post:
      operationId: removeCertAuthUser
      summary: Remove provided name from list of users with certificate authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CertAuthUserRequest'
      responses:
        '200':
          $ref: '#/components/responses/CertAuthUserList'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/config:
    parameters:
    - $ref: '#/components/parameters/project_id'
    - $ref: '#/components/parameters/location'
    - $ref: '#/components/parameters/postgres_database_reference'
    get:
      operationId: getPostgresDatabaseConfig
      summary: Get PostgreSQL database configuration
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostgresConfig'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    post:
      operationId: updatePostgresDatabaseConfig
      summary: Replace PostgreSQL database configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostgresConfig'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostgresConfig'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    patch:
      operationId: patchPostgresDatabaseConfig
      summary: Update PostgreSQL database configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostgresPatchConfig'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostgresConfig'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/logs:
    parameters:
    - $ref: '#/components/parameters/location'
    - $ref: '#/components/parameters/postgres_database_reference'
    - $ref: '#/components/parameters/project_id'
    get:
      operationId: getPostgresDatabaseLogs
      summary: Get PostgreSQL database logs
      parameters:
      - name: start
        in: query
        description: Start time for log query (rfc3339 format, default 30 minutes ago)
        required: false
        schema:
          type: string
          example: 2025-05-12 11:27:24+00:00
      - name: end
        in: query
        description: End time for log query (rfc3339 format, default now)
        required: false
        schema:
          type: string
          example: 2025-05-12 11:57:24+00:00
      - name: stream_name
        in: query
        description: Filter by log stream (postgres, pgbouncer, or upgrade)
        required: false
        schema:
          type: string
          example: postgres
          enum:
          - postgres
          - pgbouncer
          - upgrade
      - name: severity_level
        in: query
        description: Filter by log severity level
        required: false
        schema:
          type: string
          example: INFO
          enum:
          - DEBUG
          - INFO
          - WARN
          - ERROR
          - FATAL
      - name: server_role
        in: query
        description: Filter by server role (primary or standby)
        required: false
        schema:
          type: string
          example: primary
          enum:
          - primary
          - standby
      - name: query_pattern
        in: query
        description: Pattern for substring match against log message body
        required: false
        schema:
          type: string
      - name: max_log_lines
        in: query
        description: Number of log lines to return (default 50, max 500)
        required: false
        schema:
          type: integer
          default: 50
      - name: pagination_key
        in: query
        description: Pagination key returned from a previous response
        required: false
        schema:
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabaseLogs'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/metrics:
    parameters:
    - $ref: '#/components/parameters/location'
    - $ref: '#/components/parameters/postgres_database_reference'
    - $ref: '#/components/parameters/project_id'
    get:
      operationId: getPostgresDatabaseMetrics
      summary: Get PostgreSQL database metrics
      parameters:
      - name: start
        in: query
        description: Start time for metrics query (rfc3339 format)
        required: false
        schema:
          type: string
          example: 2025-05-12 11:57:24+00:00
          default: now-30m
      - name: end
        in: query
        description: End time for metrics query (rfc3339 format)
        required: false
        schema:
          type: string
          example: 2025-05-12 11:27:24+00:00
          default: now
      - name: key
        in: query
        description: Key of the specific metric to retrieve
        required: false
        schema:
          type: string
          example: cpu_usage
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabaseMetrics'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/promote:
    parameters:
    - $ref: '#/components/parameters/project_id'
    - $ref: '#/components/parameters/location'
    - $ref: '#/components/parameters/postgres_database_reference'
    post:
      operationId: promotePostgresDatabase
      summary: Promote a PostgreSQL read replica (deprecated, use promote-read-replica)
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      deprecated: true
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/promote-read-replica:
    parameters:
    - $ref: '#/components/parameters/project_id'
    - $ref: '#/components/parameters/location'
    - $ref: '#/components/parameters/postgres_database_reference'
    post:
      operationId: promoteReadReplicaPostgresDatabase
      summary: Promote a PostgreSQL read replica
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/read-replica:
    post:
      operationId: createPostgresDatabaseReadReplica
      summary: Create a read replica of the PostgreSQL database
      parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Name for the read replica
                  type: string
                pg_config:
                  type: object
                  example:
                    max_connections: '100'
                  additionalProperties:
                    type: string
                pgbouncer_config:
                  type: object
                  example:
                    max_client_conn: '100'
                  additionalProperties:
                    type: string
                tags:
                  description: Tags for the read replica
                  type: array
                  items:
                    $ref: '#/components/schemas/PostgresTag'
              additionalProperties: false
              required:
              - name
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/recycle:
    parameters:
    - $ref: '#/components/parameters/project_id'
    - $ref: '#/components/parameters/location'
    - $ref: '#/components/parameters/postgres_database_reference'
    post:
      operationId: recycle
      summary: Request primary to be recycled
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/rename:
    parameters:
    - $ref: '#/components/parameters/project_id'
    - $ref: '#/components/parameters/location'
    - $ref: '#/components/parameters/postgres_database_reference'
    post:
      operationId: renamePostgres
      summary: Rename a PostgreSQL database
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: New name for PostgreSQL database
                  type: string
              additionalProperties: false
              required:
              - name
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/reset-superuser-password:
    post:
      operationId: resetSuperuserPassword
      summary: Reset superuser password of the PostgreSQL database
      parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                password:
                  type: string
              additionalProperties: false
              required:
              - password
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/restart:
    parameters:
    - $ref: '#/components/parameters/project_id'
    - $ref: '#/components/parameters/location'
    - $ref: '#/components/parameters/postgres_database_reference'
    post:
      operationId: restartPostgresDatabase
      summary: Restart a PostgreSQL database
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/restore:
    post:
      operationId: restorePostgresDatabase
      summary: Restore a PostgreSQL database
      parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Name for the newly restored Postgres database.
                  type: string
                restore_target:
                  description: The RFC 3339-formatted timestamp for the point in time at which to recover.
                  type: string
                  format: date-time
                pg_config:
                  type: object
                  example:
                    max_connections: '100'
                  additionalProperties:
                    type: string
                pgbouncer_config:
                  type: object
                  example:
                    max_client_conn: '100'
                  additionalProperties:
                    type: string
                tags:
                  description: Tags for the Postgres Database
                  type: array
                  items:
                    $ref: '#/components/schemas/PostgresTag'
              additionalProperties: false
              required:
              - name
              - restore_target
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/servers:
    parameters:
    - $ref: '#/components/parameters/project_id'
    - $ref: '#/components/parameters/location'
    - $ref: '#/components/parameters/postgres_database_reference'
    get:
      operationId: listPostgresDatabaseServers
      summary: List servers for a specific PostgreSQL database
      responses:
        '200':
          $ref: '#/components/responses/PostgresServers'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/set-maintenance-window:
    post:
      operationId: setMaintenanceWindow
      summary: Set maintenance window for the PostgreSQL database
      parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                maintenance_window_start_at:
                  type: integer
                maintenance_window_days:
                  type: array
                  items:
                    $ref: '#/components/schemas/MaintenanceWindowDay'
              additionalProperties: false
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabase'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/postgres/{postgres_database_reference}/upgrade:
    parameters:
    - $ref: '#/components/parameters/project_id'
    - $ref: '#/components/parameters/location'
    - $ref: '#/components/parameters/postgres_database_reference'
    post:
      operationId: upgradePostgresDatabase
      summary: Upgrade a PostgreSQL database to the next major version
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabaseUpgradeStatus'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    get:
      operationId: getPostgresDatabaseUpgradeStatus
      summary: Get PostgreSQL database upgrade status
      parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/postgres_database_reference'
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabaseUpgradeStatus'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/postgres:
    get:
      operationId: listPostgresDatabases
      summary: List all PostgreSQL databases
      parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/tags'
      - $ref: '#/components/parameters/start_after'
      - $ref: '#/components/parameters/page_size'
      - $ref: '#/components/parameters/order_column'
      responses:
        '200':
          $ref: '#/components/responses/PostgresDatabases'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/postgres/capabilities:
    parameters:
    - $ref: '#/components/parameters/project_id'
    get:
      operationId: getPostgresCapabilities
      summary: Get available PostgreSQL provisioning options
      description: Returns a tree of valid option combinations for creating PostgreSQL databases, along with metadata describing each option value. The tree encodes dependency chains (e.g. which VM families are available per location, which storage sizes are valid per VM size).
      responses:
        '200':
          description: PostgreSQL capabilities tree and metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostgresCapabilities'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Postgres Database
    servers:
    - url: https://api.ubicloud.com
components:
  schemas:
    ResourceMetrics:
      type: object
      properties:
        metrics:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              key:
                description: Key of the metric
                type: string
                example: cpu_usage
              name:
                description: Name of the metric
                type: string
                example: CPU Usage
              description:
                description: Description of the metric
                type: string
                example: Percentage of CPU used by the system
              unit:
                description: Unit of measurement for the metric
                type:
                - string
                - 'null'
                example: percent
              series:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  properties:
                    labels:
                      description: Labels identifying the time series
                      type: object
                      example:
                        instance: pv9z3a26qkyy4qcxrhzg5f1bs8
                      additionalProperties:
                        type: string
                    values:
                      description: Array of timestamp-value pairs
                      type: array
                      items:
                        type: array
                        minItems: 2
                        maxItems: 2
                        items:
                          oneOf:
                          - type: number
                            description: Unix timestamp
                          - type: string
                            description: Sample value
                  required:
                  - labels
                  - values
            required:
            - name
            - unit
            - series
      additionalProperties: false
      required:
      - metrics
    CertAuthUserRequest:
      type: object
      properties:
        name:
          description: name of user
          type: string
      additionalProperties: false
      required:
      - name
    PostgresTag:
      type: object
      properties:
        key:
          description: Key of the Postgres tag
          type: string
        value:
          description: Value of the Postgres tag
          type: string
      additionalProperties: false
      required:
      - key
      - value
    PostgresPatchConfig:
      anyOf:
      - type: object
        properties:
          pg_config:
            type: object
            example:
              max_connections: '100'
            additionalProperties:
              type:
              - string
              - 'null'
          pgbouncer_config:
            type: object
            example:
              max_client_conn: '100'
            additionalProperties:
              type:
              - string
              - 'null'
        additionalProperties: false
        required:
        - pg_config
      - type: object
        properties:
          pgbouncer_config:
            type: object
            example:
              max_client_conn: '100'
            additionalProperties:
              type:
              - string
              - 'null'
        additionalProperties: false
        required:
        - pgbouncer_config
    MaintenanceWindowDay:
      type: string
      enum:
      - mon
      - tue
      - wed
      - thu
      - fri
      - sat
      - sun
    Error:
      type: object
      properties:
        error:
          type: object
          additionalProperties: false
          properties:
            code:
              type: integer
              example: 401
            message:
              type: string
              example: There was an error logging in
            type:
              type: string
              example: InvalidCredentials
            details:
              type:
              - object
              - 'null'
          required:
          - code
          - message
          - type
      additionalProperties: false
      required:
      - error
    PostgresBackup:
      type: object
      properties:
        key:
          description: Backup key/identifier
          type: string
        last_modified:
          description: Last modified timestamp of the backup
          type: string
          format: date-time
      additionalProperties: false
      required:
      - key
      - last_modified
    PostgresCapabilities:
      description: 'Tree of valid option combinations and metadata for each option value. The option_tree encodes parent-child dependencies: traverse from flavor -> location -> family -> size -> storage_size -> ha_type (with version branching from flavor). Only combinations present in the tree are valid for provisioning.'
      type: object
      properties:
        option_tree:
          description: Nested object where each level maps option values to their valid children.
          type: object
          additionalProperties: true
        metadata:
          description: Display info for option values referenced in the tree
          type: object
          additionalProperties: false
          properties:
            flavor:
              type: object
              additionalProperties:
                type: object
                additionalProperties: false
                properties:
                  display_name:
                    type: string
                required:
                - display_name
            location:
              type: object
              additionalProperties:
                type: object
                additionalProperties: false
                properties:
                  display_name:
                    type: string
                  ui_name:
                    type: string
                  provider:
                    type: string
                required:
                - display_name
                - ui_name
                - provider
            family:
              type: object
              additionalProperties:
                type: object
                additionalProperties: false
                properties:
                  display_name:
                    type: string
                  category:
                    type: string
                required:
                - display_name
                - category
            size:
              type: object
              additionalProperties:
                type: object
                additionalProperties: false
                properties:
                  vcpu:
                    type: integer
                  memory_gib:
                    type: integer
                required:
                - vcpu
                - memory_gib
            ha_type:
              type: object
              additionalProperties:
                type: object
                additionalProperties: false
                properties:
                  display_name:
                    type: string
                  standby_count:
                    type: integer
                required:
                - display_name
                - standby_count
          required:
          - flavor
          - location
          - family
          - size
          - ha_type
      additionalProperties: false
      required:
      - option_tree
      - metadata
    Reference:
      description: Resource ID or name
      type: string
      pattern: ^[a-z0-9](?:[a-z0-9\-]{0,61}[a-z0-9])?$
    CertAuthUserList:
      type: object
      properties:
        items:
          type: array
          items:
            type: string
      additionalProperties: false
      required:
      - items
    PostgresFirewallRule:
      type: object
      properties:
        cidr:
          description: CIDR of the firewall rule
          type: string
        description:
          description: Port information for the firewall rule
          type: string
        id:
          description: ID of the firewall rule
          type: string
          example: frmjgkgbktw62k53005jpx8tt7
          pattern: ^fr[0-9a-hj-km-np-tv-z]{24}$
        port:
          description: Port for the Postgres firewall rule
          type: integer
      additionalProperties: false
      required:
      - cidr
      - id
    PostgresBackupCredentials:
      type: object
      properties:
        bucket:
          description: Name of the bucket backups are stored in
          type: string
        endpoint:
          description: Object storage endpoint URL
          type: string
        region:
          description: Object storage region
          type: string
        access_key_id:
          description: Temporary access key ID
          type: string
        secret_access_key:
          description: Temporary secret access key
          type: string
        session_token:
          description: Temporary session token, required alongside the access key ID and secret access key
          type: string
        expiration:
          description: When these temporary credentials expire
          type: string
          format: date-time
      additionalProperties: false
      required:
      - bucket
      - endpoint
      - region
      - access_key_id
      - secret_access_key
      - session_token
      - expiration
    PostgresDatabaseLogEntry:
      type: object
      properties:
        timestamp:
          description: Log entry timestamp in RFC 3339 format
          type: string
          format: date-time
        stream_name:
          type: string
          enum:
          - postgres
          - pgbouncer
          - upgrade
        severity_level:
          description: Log severity level
          type: string
          enum:
          - UNSPECIFIED
          - DEBUG
          - INFO
          - WARN
          - ERROR
          - FATAL
        message:
          description: Log message body
          type: string
        server_ubid:
          description: UBID of the server that produced this log entry
          type: string
          pattern: ^pv[0-9a-hj-km-np-tv-z]{24}$
        server_role:
          type: string
          enum:
          - primary
          - standby
        context:
          description: Additional context fields parsed from the log entry (e.g. remote_host_port, dbname, pid, user)
          type: object
          additionalProperties:
            type: string
      additionalProperties: false
      required:
      - timestamp
      - stream_name
      - severity_level
      - message
      - server_ubid
      - server_role
    PostgresDatabase:
      type: object
      properties:
        flavor:
          description: Deprecated. Always standard.
          type: string
          deprecated: true
        ha_type:
          description: High availability type
          type: string
        target_server_count:
          description: Target number of servers (primary + standbys)
          type: integer
        id:
          description: ID of the Postgres database
          type: string
          example: pgn30gjk1d1e2jj34v9x0dq4rp
          pattern: ^pg[0-9a-hj-km-np-tv-z]{24}$
        location:
          description: Location of the Postgres database
          type: string
        name:
          description: Name of the Postgres database
          type: string
        state:
          description: State of the Postgres database
          type: string
        storage_size_gib:
          description: Storage size in GiB
          type: integer
        target_storage_size_gib:
          description: Desired storage size in GiB
          type: integer
        version:
          description: Current Postgres version
          type: string
          enum:
          - '16'
          - '17'
          - '18'
        target_version:
          description: Target Postgres version
          type: string
          enum:
          - '16'
          - '17'
          - '18'
        vm_size:
          description: Size of the underlying VM
          type: string
        target_vm_size:
          description: Desired VM size
          type: string
        ca_certificates:
          description: CA certificates of the root CA used to issue postgres server certificates
          type:
          - string
          - 'null'
        maintenance_window_start_at:
          description: Maintenance window start time
          type:
          - integer
          - 'null'
        maintenance_window_days:
          description: Days of the week the maintenance window applies to (empty list means every day)
          type: array
          items:
            $ref: '#/components/schemas/MaintenanceWindowDay'
        read_replica:
          description: If the database is a read replica or not
          type: boolean
        parent:
          description: Parent Postgres database
          type:
          - string
          - 'null'
        fallback_active:
          description: Whether the primary server is running on a fallback instance type
          type: boolean
        tags:
          description: Tags of the Postgres database
          type: array
          items:
            $ref: '#/components/schemas/PostgresTag'
        created_at:
          description: Creation timestamp of the Postgres database
          type: string
          format: date-time
      additionalProperties: false
      required:
      - flavor
      - ha_type
      - target_server_count
      - id
      - location
      - name
      - state
      - storage_size_gib
      - version
      - target_version
      - vm_size
      - maintenance_window_start_at
      - read_replica
      - fallback_active
      - tags
      - created_at
      x-go-name: PostgresDatabaseSchema
    PostgresServer:
      type: object
      properties:
        id:
          description: ID of the server
          type: string
        role:
          description: Role of the server (primary or standby)
          type: string
          enum:
          - primary
          - standby
        state:
          description: Current state of the server
          type: string
          enum:
          - running
          - creating
          - updating
          - unavailable
          - failing_over
          - restarting
          - synchronizing
          - deleting
        synchronization_status:
          description: Synchronization status of the server
          type: string
          enum:
          - ready
          - catching_up
        vm_size:
          description: Actual VM size of the server
          type: string
        fallback_active:
          description: Whether the server is running on a fallback instance type
          type: boolean
      additionalProperties: false
      required:
      - id
      - role
      - state
      - synchronization_status
    PostgresConfig:
      type: object
      properties:
        pg_config:
          type: object
          example:
            max_connections: '100'
          additionalProperties:
            anyOf:
            - type: string
            - type: number
        pgbouncer_config:
          type: object
          example:
            max_client_conn: '100'
          additionalProperties:
            anyOf:
            - type: string
            - type: number
        default_pg_config:
          description: System-computed configuration values based on instance size. User overrides in pg_config take precedence.
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
          readOnly: true
        message:
          description: Informational message about the configuration update, such as restart requirements.
          type: string
          readOnly: true
      additionalProperties: false
      required:
      - pg_config
      - pgbouncer_config
  parameters:
    start_after:
      description: Pagination - Start after
      in: query
      name: start_after
      required: false
      schema:
        type: string
    project_id:
      description: ID of the project
      in: path
      name: project_id
      required: true
      schema:
        type: string
        example: pjkkmx0f2vke4h36nk9cm8v8q0
        pattern: ^pj[0-9a-hj-km-np-tv-z]{24}$
    tags:
      description: Filter by tags in key:value format (comma-separated for multiple tags)
      in: query
      name: tags
      required: false
      schema:
        type: string
        example: environment:production,team:backend
    page_size:
      description: Pagination - Page size
      in: query
      name: page_size
      required: false
      schema:
        type: integer
        default: 10
    postgres_database_reference:
      description: Postgres database ID or name
      examples:
        id:
          value: pgn30gjk1d1e2jj34v9x0dq4rp
        name:
          value: postgres-database-name
      in: path
      name: postgres_database_reference
      required: true
      schema:
        $ref: '#/components/schemas/Reference'
    location:
      description: The Ubicloud location/region
      in: path
      name: location
      required: true
      schema:
        type: string
        example: eu-central-h1
    order_column:
      description: Pagination - Order column
      in: query
      name: order_column
      required: false
      schema:
        type: string
        default: id
  responses:
    CertAuthUserList:
      description: full list of users using client certificate authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CertAuthUserList'
    PostgresDatabaseLogs:
      description: Log entries for a Postgres Database
      content:
        application/json:
          schema:
            type: object
            properties:
              logs:
                type: array
                items:
                  $ref: '#/components/schemas/PostgresDatabaseLogEntry'
              pagination_key:
                description: Pass as pagination_key to retrieve the next page of results
                type: string
                pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
            additionalProperties: false
            required:
            - logs
    PostgresBackupCredentials:
      description: Temporary, read-only credentials for downloading backups directly from object storage
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PostgresBackupCredentials'
    PostgresDatabase:
      description: A Postgres Database
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            allOf:
            - $ref: '#/components/schemas/PostgresDatabase'
            - additionalProperties: false
              properties:
                connection_string:
                  description: Connection string to the Postgres database
                  type:
                  - string
                  - 'null'
                private_connection_string:
                  description: Private connection string to the Postgres database, accessible from connected subnets
                  type:
                  - string
                  - 'null'
                username:
                  description: Username for the Postgres database
                  type:
                  - string
                  - 'null'
                password:
                  description: Password for the Postgres database
                  type:
                  - string
                  - 'null'
                hostname:
                  description: Hostname for the Postgres database
                  type:
                  - string
                  - 'null'
                earliest_restore_time:
                  description: Earliest restore time (if primary)
                  type:
                  - string
                  - 'null'
                firewall_rules:
                  description: List of Postgres firewall rules
                  type: array
                  items:
                    $ref: '#/components/schemas/PostgresFirewallRule'
                latest_restore_time:
                  description: Latest restore time (if primary)"
                  type: string
                primary:
                  description: Is the database primary
                  type: boolean
                maintenance_window_start_at:
                  description: Maintenance window start time
                  type:
                  - integer
                  - 'null'
                tags:
                  description: Tags of the Postgres database
                  type: array
                  items:
                    $ref: '#/components/schemas/PostgresTag'
              required:
              - connection_string
              - private_connection_string
              - username
              - password
              - hostname
              - earliest_restore_time
              - firewall_rules
              - latest_restore_time
              - primary
              - maintenance_window_start_at
              - tags
    Delete:
      description: An empty response after successful resource delete
    PostgresDatabases:
      description: A list of Postgres Databases
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/PostgresDatabase'
            additionalProperties: false
            required:
            - count
            - items
    Error:
      description: An error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PostgresDatabaseUpgradeStatus:
      description: A Postgres Database Upgrade Status
      content:
        application/json:
          schema:
            type: object
            properties:
              current_version:
                type: string
                enum:
                - '16'
                - '17'
                - '18'
              target_version:
                type: string
                enum:
                - '16'
                - '17'
                - '18'
              upgrade_status:
                type: string
              upgrade_stage:
                type:
                - string
                - 'null'
            additionalProperties: false
            required:
            - current_version
            - target_version
            - upgrade_status
    PostgresBackups:
      description: A list of Postgres Database Backups
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/PostgresBackup'
            additionalProperties: false
            required:
            - count
            - items
    PostgresDatabaseMetrics:
      description: Metrics data for a Postgres Database
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceMetrics'
    PostgresServers:
      description: A list of Postgres Database Servers
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/PostgresServer'
            additionalProperties: false
            required:
            - count
            - items
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
x-refined-from:
- ubicloud-openapi.yml
- ubicloud-openapi.yml