Merge pull request #620 from bbiggerr/dbaas-mysql-patch

[New] Managed MySQL Database Patch

Author: bbiggerr

openapi.yaml

@@ -3272,7 +3272,17 @@ paths:
         * Entering an empty array (`[]`) blocks all connections (both public and private) to the Managed Database.
         * **Note**: Updates to the `allow_list` may take a short period of time to complete, making this command inappropriate for rapid successive updates to this property.
 
-        All Managed Databases include automatic, daily backups. Up to seven backups are stored for each Managed Database, providing restore points for each day of the past week.
+        All Managed Databases include automatic, daily backups. Up to seven backups are automatically stored for each Managed Database, providing restore points for each day of the past week.
+
+        All Managed Databases include automatic patch updates.
+
+        * By default, the maintenance window is set to start *every week* on *Sunday* at *20:00 UTC* and lasts for 3 hours.
+
+        * If your database cluster is configured with a single node, you will experience downtime during this maintenance window when any updates occur. It's recommended that you adjust this window to match a time that will be the least disruptive for your application and users. You may also want to consider upgrading to a high availability plan to avoid any downtime due to maintenance.
+
+        * Currently, these automatic updates do not include major releases for the database engine software (DBMS). To upgrade to a new major version (such as upgrading MySQL 8.0.26 to 9.0.0), consider deploying a new Managed Database with your preferred version. Then, once it's deployed, you can [migrate your database](/docs/products/databases/managed-databases/guides/migrate-mysql/).
+
+        * To modify update the maintenance window for a Database, use the **Managed MySQL Database Update** ([PUT /databases/mysql/instances/{instanceId}](/docs/api/databases/#managed-mysql-database-update)) command.
 
         **Beta**: This endpoint is in **open** beta. During the beta period, Managed Databases will not incur any charges.
         If you deploy a Managed Database during this time, you will receive a notice with pricing details in advance of the
@@ -3449,6 +3459,14 @@ paths:
         * Entering an empty array (`[]`) blocks all connections (both public and private) to the Managed Database.
         * **Note**: Updates to the `allow_list` may take a short period of time to complete, making this command inappropriate for rapid successive updates to this property.
 
+        All Managed Databases include automatic patch updates. The maintenance window for these updates is configured with the Managed Database `updates` property.
+
+        * By default, the maintenance window is set to start *every week* on *Sunday* at *20:00 UTC* and lasts for 3 hours.
+
+        * If your database cluster is configured with a single node, you will experience downtime during this maintenance window when any updates occur. It's recommended that you adjust this window to match a time that will be the least disruptive for your application and users. You may also want to consider upgrading to a high availability plan to avoid any downtime due to maintenance.
+
+        * Currently, these automatic updates do not include major releases for the database engine software (DBMS). To upgrade to a new major version (such as upgrading MySQL 8.0.26 to 9.0.0), consider deploying a new Managed Database with your preferred version. Then, once it's deployed, you can [migrate your database](/docs/products/databases/managed-databases/guides/migrate-mysql/).
+
         **Beta**: This endpoint is in **open** beta. During the beta period, Managed Databases will not incur any charges.
         If you deploy a Managed Database during this time, you will receive a notice with pricing details in advance of the
         GA (general availability) release.
@@ -3471,6 +3489,8 @@ paths:
                   $ref: '#/components/schemas/DatabaseMySQLRequest/properties/label'
                 allow_list:
                   $ref: '#/components/schemas/DatabaseMySQLRequest/properties/allow_list'
+                updates:
+                  $ref: '#/components/schemas/DatabaseMySQLRequest/properties/updates'
       responses:
         '200':
           description: Managed Database updated successfully.
@@ -3490,15 +3510,27 @@ paths:
                   "allow_list": [
                     "203.0.113.1",
                     "192.0.1.0/24"
-                  ]
+                  ],
+                  "updates" = {
+                    "frequency": "monthly",
+                    "duration": 3,
+                    "hour_of_day": 12,
+                    "day_of_week": 4,
+                    "week_of_month": 3,
+                  }
               }' \
               https://api.linode.com/v4beta/databases/mysql/instances/123
       - lang: CLI
         source: >
           linode-cli databases mysql-update 123 \
             --label example-db \
             --allow_list 203.0.113.1 \
-            --allow_list 192.0.1.0/24
+            --allow_list 192.0.1.0/24 \
+            --updates.frequency monthly \
+            --updates.duration 3 \
+            --updates.hour_of_day 12 \
+            --updates.day_of_week 4 \
+            --updates.week_of_month 3
   /databases/mysql/instances/{instanceId}/backups:
     x-linode-cli-command: databases
     parameters:
@@ -3917,6 +3949,63 @@ paths:
       - lang: CLI
         source: >
           linode-cli databases mysql-ssl-cert 123
+  /databases/mysql/instances/{instanceId}/patch:
+    x-linode-cli-command: databases
+    parameters:
+      - name: instanceId
+        in: path
+        description: The ID of the Managed MySQL Database.
+        required: true
+        schema:
+          type: integer
+    post:
+      tags:
+      - Databases
+      summary: Managed MySQL Database Patch
+      operationId: postDatabasesMySQLInstancePatch
+      servers:
+      - url: https://api.linode.com/v4beta
+      x-linode-cli-action: mysql-patch
+      x-linode-grant: unrestricted only
+      description: |
+        Update the minor patch version of the Managed MySQL Database.
+
+        The Database must have an `active` status to perform this command.
+
+        Only unrestricted Users can access this command, and have access regardless of the acting token's OAuth scopes.
+
+        **Note**
+
+        * If your database cluster is configured with a single node, you will experience downtime during this maintenance. Consider upgrading to a high availability plan to avoid any downtime due to maintenance.
+
+        * Currently, patching does not include major releases for the database engine software (DBMS). To patch to a new major version (such as upgrading MySQL 8.0.26 to 9.0.0), consider deploying a new Managed Database with your preferred version. Then, once it's deployed, you can [migrate your database](/docs/products/databases/managed-databases/guides/migrate-mysql/).
+
+        **Beta**: This endpoint is in **open** beta. During the beta period, Managed Databases will not incur any charges.
+        If you deploy a Managed Database during this time, you will receive a notice with pricing details in advance of the
+        GA (general availability) release.
+        When accessing this endpoint, please make sure to prepend all requests with `/v4beta` instead of `/v4`, and be
+        aware that this endpoint may receive breaking updates in the future. This notice will be removed when this
+        endpoint is out of beta.
+      security:
+      - personalAccessToken: []
+      - oauth: []
+      responses:
+        '200':
+          description: Managed Database instance patch request successful.
+          content:
+            application/json:
+              schema:
+                type: object
+        default:
+          $ref: '#/components/responses/ErrorResponse'
+      x-code-samples:
+      - lang: Shell
+        source: >
+          curl -H "Authorization: Bearer $TOKEN" \
+              -X POST https://api.linode.com/v4beta/databases/mysql/instances/123/patch
+      - lang: CLI
+        source: >
+          linode-cli databases mysql-patch 123
   /databases/types:
     x-linode-cli-command: databases
     get:
@@ -17759,6 +17848,7 @@ components:
           - restoring
           - failed
           - degraded
+          - updating
           description: The operating status of the Managed Database.
           example: active
           x-linode-filterable: true
@@ -17770,6 +17860,8 @@ components:
             restoring: yellow
             failed: red
             degraded: red
+            updating: yellow
+            default_: white
           readOnly: true
         encrypted:
           type: boolean
@@ -17978,10 +18070,55 @@ components:
 
             Must be `asynch` or `semi_synch` for a high availability cluster.
           x-linode-cli-display: 99
+        port:
+          type: integer
+          description: The access port for this Managed Database.
+          example: 3306
+          x-linode-cli-display: 98
         created:
           $ref: '#/components/schemas/Database/properties/created'
         updated:
           $ref: '#/components/schemas/Database/properties/updated'
+        updates:
+          type: object
+          description: Configuration settings for automated patch update maintenance for the Managed Database.
+          properties:
+            frequency:
+              type: string
+              enum:
+              - weekly
+              - monthly
+              description: Whether maintenance occurs on a weekly or monthly basis.
+              example:
+            duration:
+              type: integer
+              minimum: 1
+              maximum: 3
+              description: The maximum maintenance window time in hours.
+              example: 3
+            hour_of_day:
+              type: integer
+              minimum: 0
+              maximum: 23
+              description: The hour to begin maintenance based in UTC time.
+              example: 0
+            day_of_week:
+              type: integer
+              minimum: 1
+              maximum: 7
+              description: The day to perform maintenance. 1=Monday, 2=Tuesday, etc.
+              example: 1
+            week_of_month:
+              type: integer
+              minimum: 1
+              maximum: 4
+              description: |
+                The week of the month to perform `monthly` frequency updates.
+
+                * Required for `monthly` frequency updates.
+
+                * Must be `null` for `weekly` frequency updates.
+              example: 1
     DatabaseMySQLRequest:
       type: object
       description: Managed MySQL Database request object.
@@ -18011,6 +18148,8 @@ components:
           $ref: '#/components/schemas/DatabaseMySQL/properties/ssl_connection'
         replication_type:
           $ref: '#/components/schemas/DatabaseMySQL/properties/replication_type'
+        updates:
+          $ref: '#/components/schemas/DatabaseMySQL/properties/updates'
     DatabaseSSL:
       type: object
       description: Managed Database SSL object.