{"owner":"neondatabase","repo":"neon","hasSpec":true,"specFile":"compute_tools/src/http/openapi_spec.yaml","branch":"HEAD","format":"yaml","version":"3.x (YAML)","title":"neon","description":"","endpoints":[],"spec":"openapi: \"3.0.2\"\ninfo:\n  title: Compute node control API\n  version: \"1.0\"\n\nservers:\n  - url: \"http://localhost:3080\"\n\npaths:\n  /status:\n    get:\n      tags:\n      - Info\n      summary: Get compute node internal status.\n      description: \"\"\n      operationId: getComputeStatus\n      responses:\n        200:\n          description: ComputeState\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ComputeState\"\n\n  /metrics.json:\n    get:\n      tags:\n      - Info\n      summary: Get compute node startup metrics in JSON format.\n      description: \"\"\n      operationId: getComputeMetricsJSON\n      responses:\n        200:\n          description: ComputeMetrics\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ComputeMetrics\"\n\n  /metrics:\n    get:\n      tags:\n      - Info\n      summary: Get compute node metrics in text format.\n      description: \"\"\n      operationId: getComputeMetrics\n      responses:\n        200:\n          description: ComputeMetrics\n          content:\n            text/plain:\n              schema:\n                type: string\n                description: Metrics in text format.\n  /insights:\n    get:\n      tags:\n      - Info\n      summary: Get current compute insights in JSON format.\n      description: |\n        Note, that this doesn't include any historical data.\n      operationId: getComputeInsights\n      responses:\n        200:\n          description: Compute insights\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ComputeInsights\"\n\n  /dbs_and_roles:\n    get:\n      tags:\n        - Info\n      summary: Get databases and roles in the catalog.\n      description: \"\"\n      operationId: getDbsAndRoles\n      responses:\n        200:\n          description: Compute schema objects\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/DbsAndRoles\"\n\n  /promote:\n    post:\n      tags:\n        - Promotion\n      summary: Promote secondary replica to primary\n      description: \"\"\n      operationId: promoteReplica\n      requestBody:\n        description: Promote requests data\n        required: true\n        content:\n          application/json:\n            schema:\n              $ref: \"#/components/schemas/ComputeSchemaWithLsn\"\n      responses:\n        200:\n          description: Promote succeeded or wasn't started\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/PromoteState\"\n        500:\n          description: Promote failed\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/PromoteState\"\n\n  /lfc/prewarm:\n    post:\n      summary: Request LFC Prewarm\n      parameters:\n        - name: from_endpoint\n          in: query\n          schema:\n            type: string\n      description: \"\"\n      operationId: lfcPrewarm\n      responses:\n        202:\n          description: LFC prewarm started\n        429:\n          description: LFC prewarm ongoing\n    get:\n      tags:\n        - Prewarm\n      summary: Get LFC prewarm state\n      description: \"\"\n      operationId: getLfcPrewarmState\n      responses:\n        200:\n          description: Prewarm state\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/LfcPrewarmState\"\n    delete:\n      tags:\n        - Prewarm\n      summary: Cancel ongoing LFC prewarm\n      description: \"\"\n      operationId: cancelLfcPrewarm\n      responses:\n        202:\n          description: Prewarm cancelled\n\n  /lfc/offload:\n    post:\n      summary: Request LFC offload\n      description: \"\"\n      operationId: lfcOffload\n      responses:\n        202:\n          description: LFC offload started\n        429:\n          description: LFC offload ongoing\n    get:\n      tags:\n        - Prewarm\n      summary: Get LFC offloading state\n      description: \"\"\n      operationId: getLfcOffloadState\n      responses:\n        200:\n          description: Offload state\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/LfcOffloadState\"\n\n  /database_schema:\n    get:\n      tags:\n        - Info\n      summary: Get schema dump\n      parameters:\n        - name: database\n          in: query\n          description: Database name to dump.\n          required: true\n          schema:\n            type: string\n          example: \"postgres\"\n      description: Get schema dump in SQL format.\n      operationId: getDatabaseSchema\n      responses:\n        200:\n          description: Schema dump\n          content:\n            text/plain:\n              schema:\n                type: string\n                description: Schema dump in SQL format.\n        404:\n          description: Non existing database.\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/GenericError\"\n\n  /grants:\n    post:\n      tags:\n        - Grants\n      summary: Apply grants to the database.\n      description: \"\"\n      operationId: setRoleGrants\n      requestBody:\n        description: Grants request.\n        required: true\n        content:\n          application/json:\n            schema:\n                $ref: \"#/components/schemas/SetRoleGrantsRequest\"\n      responses:\n        200:\n          description: Grants applied.\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/SetRoleGrantsResponse\"\n        412:\n          description: |\n            Compute is not in the right state for processing the request.\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/GenericError\"\n        500:\n          description: Error occurred during grants application.\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/GenericError\"\n\n  /check_writability:\n    post:\n      tags:\n      - Check\n      summary: Check that we can write new data on this compute.\n      description: \"\"\n      operationId: checkComputeWritability\n      responses:\n        200:\n          description: Check result\n          content:\n            text/plain:\n              schema:\n                type: string\n                description: Error text or 'true' if check passed.\n                example: \"true\"\n\n  /extensions:\n    post:\n      tags:\n        - Extensions\n      summary: Install extension if possible.\n      description: \"\"\n      operationId: installExtension\n      requestBody:\n        description: Extension name and database to install it to.\n        required: true\n        content:\n          application/json:\n            schema:\n              $ref: \"#/components/schemas/ExtensionInstallRequest\"\n      responses:\n        200:\n          description: Result from extension installation\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ExtensionInstallResult\"\n        412:\n          description: |\n            Compute is in the wrong state for processing the request.\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/GenericError\"\n        500:\n          description: Error during extension installation.\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/GenericError\"\n\n  /configure:\n    post:\n      tags:\n      - Configure\n      summary: Perform compute node configuration.\n      description: |\n        This is a blocking API endpoint, i.e. it blocks waiting until\n        compute is finished configuration and is in `Running` state.\n        Optional non-blocking mode could be added later.\n      operationId: configureCompute\n      requestBody:\n        description: Configuration request.\n        required: true\n        content:\n          application/json:\n            schema:\n              $ref: \"#/components/schemas/ComputeSchema\"\n      responses:\n        200:\n          description: Compute configuration finished.\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/ComputeState\"\n        400:\n          description: Provided spec is invalid.\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/GenericError\"\n        412:\n          description: |\n            It's not possible to do live-configuration of the compute.\n            It's either in the wrong state, or compute doesn't use pull\n            mode of configuration.\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/GenericError\"\n        500:\n          description: |\n            Compute configuration request was processed, but error\n            occurred. Compute will likely shutdown soon.\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/GenericError\"\n  /extension_server:\n    post:\n      tags:\n      - Extension\n      summary: Download extension from S3 to local folder.\n      description: \"\"\n      operationId: downloadExtension\n      responses:\n        200:\n          description: Extension downloaded\n          content:\n            text/plain:\n              schema:\n                type: string\n                description: Error text or 'OK' if download succeeded.\n                example: \"OK\"\n        400:\n          description: Request is invalid.\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/GenericError\"\n        500:\n          description: Extension download request failed.\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/GenericError\"\n\n  /terminate:\n    post:\n      tags:\n      - Terminate\n      summary: Terminate Postgres and wait for it to exit\n      description: \"\"\n      operationId: terminate\n      parameters:\n        - name: mode\n          in: query\n          description: \"Terminate mode: fast (wait 30s before returning) and immediate\"\n          required: false\n          schema:\n            type: string\n            enum: [\"fast\", \"immediate\"]\n            default: fast\n      responses:\n        200:\n          description: Result\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/TerminateResponse\"\n        201:\n          description: Result if compute is already terminated\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/TerminateResponse\"\n        412:\n          description: \"wrong state\"\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/GenericError\"\n        500:\n          description: \"Unexpected error\"\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/GenericError\"\n\ncomponents:\n  securitySchemes:\n    JWT:\n      type: http\n      scheme: bearer\n      bearerFormat: JWT\n\n  schemas:\n    ComputeMetrics:\n      type: object\n      description: Compute startup metrics.\n      required:\n        - wait_for_spec_ms\n        - sync_safekeepers_ms\n        - basebackup_ms\n        - config_ms\n        - total_startup_ms\n      properties:\n        wait_for_spec_ms:\n          type: integer\n        sync_safekeepers_ms:\n          type: integer\n        basebackup_ms:\n          type: integer\n        config_ms:\n          type: integer\n        total_startup_ms:\n          type: integer\n\n    DbsAndRoles:\n      type: object\n      description: Databases and Roles\n      required:\n        - roles\n        - databases\n      properties:\n        roles:\n          type: array\n          items:\n            $ref: \"#/components/schemas/Role\"\n        databases:\n          type: array\n          items:\n            $ref: \"#/components/schemas/Database\"\n\n    Database:\n      type: object\n      description: Database\n      required:\n        - name\n        - owner\n        - restrict_conn\n        - invalid\n      properties:\n        name:\n          type: string\n        owner:\n          type: string\n        options:\n          type: array\n          items:\n            $ref: \"#/components/schemas/GenericOption\"\n        restrict_conn:\n          type: boolean\n        invalid:\n          type: boolean\n\n    Role:\n      type: object\n      description: Role\n      required:\n        - name\n      properties:\n        name:\n          type: string\n        encrypted_password:\n          type: string\n        options:\n          type: array\n          items:\n            $ref: \"#/components/schemas/GenericOption\"\n\n    GenericOption:\n      type: object\n      description: Schema Generic option\n      required:\n        - name\n        - vartype\n      properties:\n        name:\n          type: string\n        value:\n          type: string\n        vartype:\n          type: string\n\n    ComputeState:\n      type: object\n      required:\n        - start_time\n        - status\n      properties:\n        start_time:\n          type: string\n          description: |\n            Time when compute was started. If initially compute was started in the `empty`\n            state and then provided with valid spec, `start_time` will be reset to the\n            moment, when spec was received.\n          example: \"2022-10-12T07:20:50.52Z\"\n        status:\n          $ref: \"#/components/schemas/ComputeStatus\"\n        last_active:\n          type: string\n          description: |\n            The last detected compute activity timestamp in UTC and RFC3339 format.\n            It could be empty if compute was never used by user since start.\n          example: \"2022-10-12T07:20:50.52Z\"\n        error:\n          type: string\n          description: Text of the error during compute startup or reconfiguration, if any.\n          example: \"\"\n        tenant:\n          type: string\n          description: Identifier of the current tenant served by compute node, if any.\n          example: c9269c359e9a199fad1ea0981246a78f\n        timeline:\n          type: string\n          description: Identifier of the current timeline served by compute node, if any.\n          example: ece7de74d4b8cbe5433a68ce4d1b97b4\n\n    ComputeInsights:\n      type: object\n      properties:\n        pg_stat_statements:\n          description: Contains raw output from pg_stat_statements in JSON format.\n          type: array\n          items:\n            type: object\n\n    ComputeStatus:\n      type: string\n      enum:\n        - empty\n        - configuration_pending\n        - init\n        - running\n        - configuration\n        - failed\n        - termination_pending_fast\n        - termination_pending_immediate\n        - terminated\n      example: running\n\n    ExtensionInstallRequest:\n      type: object\n      required:\n        - extension\n        - database\n        - version\n      properties:\n        extension:\n          type: string\n          description: Extension name.\n          example: \"pg_session_jwt\"\n        version:\n          type: string\n          description: Version of the extension.\n          example: \"1.0.0\"\n        database:\n          type: string\n          description: Database name.\n          example: \"neondb\"\n\n    ExtensionInstallResult:\n      type: object\n      properties:\n        extension:\n          description: Name of the extension.\n          type: string\n          example: \"pg_session_jwt\"\n        version:\n          description: Version of the extension.\n          type: string\n          example: \"1.0.0\"\n\n    ComputeSchema:\n      type: object\n      required:\n        - spec\n      properties:\n        spec:\n          type: object\n    ComputeSchemaWithLsn:\n      type: object\n      required:\n        - spec\n        - wal_flush_lsn\n      properties:\n        spec:\n          $ref: \"#/components/schemas/ComputeState\"\n        wal_flush_lsn:\n          type: string\n          description: \"last WAL flush LSN\"\n          example: \"0/028F10D8\"\n\n    LfcPrewarmState:\n      type: object\n      required:\n        - status\n      properties:\n        status:\n          description: LFC prewarm status\n          enum: [not_prewarmed, prewarming, completed, failed, skipped]\n          type: string\n        error:\n          description: LFC prewarm error, if any\n          type: string\n        total:\n          description: Total pages processed\n          type: integer\n        prewarmed:\n          description: Total pages prewarmed\n          type: integer\n        skipped:\n          description: Pages processed but not prewarmed\n          type: integer\n        state_download_time_ms:\n          description: Time it takes to download LFC state to compute\n          type: integer\n        uncompress_time_ms:\n          description: Time it takes to uncompress LFC state\n          type: integer\n        prewarm_time_ms:\n          description: Time it takes to prewarm LFC state in Postgres\n          type: integer\n\n    LfcOffloadState:\n      type: object\n      required:\n        - status\n      properties:\n        status:\n          description: LFC offload status\n          enum: [not_offloaded, offloading, completed, skipped, failed]\n          type: string\n        error:\n          description: LFC offload error, if any\n          type: string\n        state_query_time_ms:\n          description: Time it takes to get LFC state from Postgres\n          type: integer\n        compress_time_ms:\n          description: Time it takes to compress LFC state\n          type: integer\n        state_upload_time_ms:\n          description: Time it takes to upload LFC state to endpoint storage\n          type: integer\n\n\n    PromoteState:\n      type: object\n      required:\n        - status\n      properties:\n        status:\n          description: Promote result\n          enum: [not_promoted, completed, failed]\n          type: string\n        error:\n          description: Promote error, if any\n          type: string\n        lsn_wait_time_ms:\n          description: Time it takes for secondary to catch up with primary WAL flush LSN\n          type: integer\n        pg_promote_time_ms:\n          description: Time it takes to call pg_promote on secondary\n          type: integer\n        reconfigure_time_ms:\n          description: Time it takes to reconfigure promoted secondary\n          type: integer\n\n    SetRoleGrantsRequest:\n      type: object\n      required:\n        - database\n        - schema\n        - privileges\n        - role\n      properties:\n        database:\n          type: string\n          description: Database name.\n          example: \"neondb\"\n        schema:\n          type: string\n          description: Schema name.\n          example: \"public\"\n        privileges:\n          type: array\n          items:\n            type: string\n          description: List of privileges to set.\n          example: [\"SELECT\", \"INSERT\"]\n        role:\n          type: string\n          description: Role name.\n          example: \"neon\"\n\n    TerminateResponse:\n      type: object\n      required:\n        - lsn\n      properties:\n        lsn:\n          type: string\n          nullable: true\n          description: \"last WAL flush LSN\"\n          example: \"0/028F10D8\"\n\n    SetRoleGrantsResponse:\n      type: object\n      required:\n        - database\n        - schema\n        - privileges\n        - role\n      properties:\n        database:\n          type: string\n          description: Database name.\n          example: \"neondb\"\n        schema:\n          type: string\n          description: Schema name.\n          example: \"public\"\n        privileges:\n          type: array\n          items:\n            type: string\n          description: List of privileges set.\n          example: [\"SELECT\", \"INSERT\"]\n        role:\n          type: string\n          description: Role name.\n          example: \"neon\"\n\n    #\n    # Errors\n    #\n\n    GenericError:\n      type: object\n      required:\n        - error\n      properties:\n        error:\n          type: string\n\nsecurity:\n  - JWT: []\n"}