openapi: 3.1.0
info:
  title: Google Cloud SQL Admin API
  description: >-
    The Cloud SQL Admin API provides programmatic access to manage Cloud SQL
    instances, databases, users, and related resources. It supports MySQL,
    PostgreSQL, and SQL Server database engines, enabling automated provisioning,
    configuration, backup management, and monitoring of managed relational
    database instances.
  version: v1
  contact:
    name: Google Cloud
    url: https://cloud.google.com/sql/docs/mysql/admin-api/rest
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: https://sqladmin.googleapis.com/v1
    description: Cloud SQL Admin API v1
tags:
  - name: BackupRuns
    description: Operations on backup runs
  - name: Databases
    description: Operations on databases within instances
  - name: Instances
    description: Operations on Cloud SQL instances
  - name: Users
    description: Operations on database users
paths:
  /projects/{project}/instances:
    get:
      tags:
        - Instances
      summary: Google Cloud SQL List instances
      description: Lists instances under a given project.
      operationId: listInstances
      parameters:
        - name: project
          in: path
          required: true
          schema:
            type: string
        - name: maxResults
          in: query
          schema:
            type: integer
        - name: pageToken
          in: query
          schema:
            type: string
        - name: filter
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstancesListResponse'
      security:
        - oauth2:
            - https://www.googleapis.com/auth/cloud-platform
            - https://www.googleapis.com/auth/sqlservice.admin
    post:
      tags:
        - Instances
      summary: Google Cloud SQL Create an instance
      description: Creates a new Cloud SQL instance.
      operationId: insertInstance
      parameters:
        - name: project
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatabaseInstance'
      responses:
        '200':
          description: Instance creation initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
      security:
        - oauth2:
            - https://www.googleapis.com/auth/cloud-platform
            - https://www.googleapis.com/auth/sqlservice.admin
  /projects/{project}/instances/{instance}:
    get:
      tags:
        - Instances
      summary: Google Cloud SQL Get an instance
      description: Retrieves a resource containing information about a Cloud SQL instance.
      operationId: getInstance
      parameters:
        - name: project
          in: path
          required: true
          schema:
            type: string
        - name: instance
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatabaseInstance'
      security:
        - oauth2:
            - https://www.googleapis.com/auth/cloud-platform
            - https://www.googleapis.com/auth/sqlservice.admin
    patch:
      tags:
        - Instances
      summary: Google Cloud SQL Update an instance
      description: Updates settings of a Cloud SQL instance using patch semantics.
      operationId: patchInstance
      parameters:
        - name: project
          in: path
          required: true
          schema:
            type: string
        - name: instance
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatabaseInstance'
      responses:
        '200':
          description: Instance update initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
      security:
        - oauth2:
            - https://www.googleapis.com/auth/cloud-platform
            - https://www.googleapis.com/auth/sqlservice.admin
    delete:
      tags:
        - Instances
      summary: Google Cloud SQL Delete an instance
      description: Deletes a Cloud SQL instance.
      operationId: deleteInstance
      parameters:
        - name: project
          in: path
          required: true
          schema:
            type: string
        - name: instance
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Instance deletion initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
      security:
        - oauth2:
            - https://www.googleapis.com/auth/cloud-platform
            - https://www.googleapis.com/auth/sqlservice.admin
  /projects/{project}/instances/{instance}/databases:
    get:
      tags:
        - Databases
      summary: Google Cloud SQL List databases
      description: Lists databases in the specified Cloud SQL instance.
      operationId: listDatabases
      parameters:
        - name: project
          in: path
          required: true
          schema:
            type: string
        - name: instance
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatabasesListResponse'
      security:
        - oauth2:
            - https://www.googleapis.com/auth/cloud-platform
            - https://www.googleapis.com/auth/sqlservice.admin
    post:
      tags:
        - Databases
      summary: Google Cloud SQL Create a database
      description: Inserts a resource containing information about a database inside a Cloud SQL instance.
      operationId: insertDatabase
      parameters:
        - name: project
          in: path
          required: true
          schema:
            type: string
        - name: instance
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Database'
      responses:
        '200':
          description: Database creation initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
      security:
        - oauth2:
            - https://www.googleapis.com/auth/cloud-platform
            - https://www.googleapis.com/auth/sqlservice.admin
  /projects/{project}/instances/{instance}/databases/{database}:
    get:
      tags:
        - Databases
      summary: Google Cloud SQL Get a database
      description: Retrieves a resource containing information about a database inside a Cloud SQL instance.
      operationId: getDatabase
      parameters:
        - name: project
          in: path
          required: true
          schema:
            type: string
        - name: instance
          in: path
          required: true
          schema:
            type: string
        - name: database
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
      security:
        - oauth2:
            - https://www.googleapis.com/auth/cloud-platform
            - https://www.googleapis.com/auth/sqlservice.admin
    delete:
      tags:
        - Databases
      summary: Google Cloud SQL Delete a database
      description: Deletes a database from a Cloud SQL instance.
      operationId: deleteDatabase
      parameters:
        - name: project
          in: path
          required: true
          schema:
            type: string
        - name: instance
          in: path
          required: true
          schema:
            type: string
        - name: database
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Database deletion initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
      security:
        - oauth2:
            - https://www.googleapis.com/auth/cloud-platform
            - https://www.googleapis.com/auth/sqlservice.admin
  /projects/{project}/instances/{instance}/users:
    get:
      tags:
        - Users
      summary: Google Cloud SQL List users
      description: Lists users in the specified Cloud SQL instance.
      operationId: listUsers
      parameters:
        - name: project
          in: path
          required: true
          schema:
            type: string
        - name: instance
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersListResponse'
      security:
        - oauth2:
            - https://www.googleapis.com/auth/cloud-platform
            - https://www.googleapis.com/auth/sqlservice.admin
    post:
      tags:
        - Users
      summary: Google Cloud SQL Create a user
      description: Creates a new user in a Cloud SQL instance.
      operationId: insertUser
      parameters:
        - name: project
          in: path
          required: true
          schema:
            type: string
        - name: instance
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: User creation initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
      security:
        - oauth2:
            - https://www.googleapis.com/auth/cloud-platform
            - https://www.googleapis.com/auth/sqlservice.admin
  /projects/{project}/instances/{instance}/backupRuns:
    get:
      tags:
        - BackupRuns
      summary: Google Cloud SQL List backup runs
      description: Lists all backup runs associated with a given instance in reverse chronological order.
      operationId: listBackupRuns
      parameters:
        - name: project
          in: path
          required: true
          schema:
            type: string
        - name: instance
          in: path
          required: true
          schema:
            type: string
        - name: maxResults
          in: query
          schema:
            type: integer
        - name: pageToken
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupRunsListResponse'
      security:
        - oauth2:
            - https://www.googleapis.com/auth/cloud-platform
            - https://www.googleapis.com/auth/sqlservice.admin
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/cloud-platform: Full access to Cloud Platform
            https://www.googleapis.com/auth/sqlservice.admin: Manage Cloud SQL instances
  schemas:
    DatabaseInstance:
      type: object
      properties:
        kind:
          type: string
          default: sql#instance
        name:
          type: string
          description: Name of the Cloud SQL instance.
        project:
          type: string
        state:
          type: string
          enum:
            - SQL_INSTANCE_STATE_UNSPECIFIED
            - RUNNABLE
            - SUSPENDED
            - PENDING_DELETE
            - PENDING_CREATE
            - MAINTENANCE
            - FAILED
        region:
          type: string
        databaseVersion:
          type: string
          description: The database engine type and version (e.g., MYSQL_8_0, POSTGRES_15, SQLSERVER_2019_STANDARD).
        settings:
          $ref: '#/components/schemas/Settings'
        connectionName:
          type: string
        ipAddresses:
          type: array
          items:
            $ref: '#/components/schemas/IpMapping'
        gceZone:
          type: string
        createTime:
          type: string
          format: date-time
        backendType:
          type: string
          enum:
            - SQL_BACKEND_TYPE_UNSPECIFIED
            - FIRST_GEN
            - SECOND_GEN
            - EXTERNAL
        selfLink:
          type: string
        serviceAccountEmailAddress:
          type: string
    Settings:
      type: object
      properties:
        tier:
          type: string
          description: The machine type (e.g., db-n1-standard-1).
        edition:
          type: string
          enum:
            - EDITION_UNSPECIFIED
            - ENTERPRISE
            - ENTERPRISE_PLUS
        availabilityType:
          type: string
          enum:
            - SQL_AVAILABILITY_TYPE_UNSPECIFIED
            - ZONAL
            - REGIONAL
        dataDiskSizeGb:
          type: string
        dataDiskType:
          type: string
          enum:
            - SQL_DATA_DISK_TYPE_UNSPECIFIED
            - PD_SSD
            - PD_HDD
            - OBSOLETE_LOCAL_SSD
        backupConfiguration:
          type: object
          properties:
            enabled:
              type: boolean
            startTime:
              type: string
            binaryLogEnabled:
              type: boolean
        ipConfiguration:
          type: object
          properties:
            ipv4Enabled:
              type: boolean
            requireSsl:
              type: boolean
            privateNetwork:
              type: string
            authorizedNetworks:
              type: array
              items:
                type: object
                properties:
                  value:
                    type: string
                  name:
                    type: string
                  expirationTime:
                    type: string
        databaseFlags:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: string
        activationPolicy:
          type: string
          enum:
            - SQL_ACTIVATION_POLICY_UNSPECIFIED
            - ALWAYS
            - NEVER
    Database:
      type: object
      properties:
        kind:
          type: string
          default: sql#database
        name:
          type: string
        instance:
          type: string
        project:
          type: string
        charset:
          type: string
        collation:
          type: string
        selfLink:
          type: string
    User:
      type: object
      properties:
        kind:
          type: string
          default: sql#user
        name:
          type: string
        host:
          type: string
        instance:
          type: string
        project:
          type: string
        password:
          type: string
        type:
          type: string
          enum:
            - BUILT_IN
            - CLOUD_IAM_USER
            - CLOUD_IAM_SERVICE_ACCOUNT
    IpMapping:
      type: object
      properties:
        type:
          type: string
          enum:
            - SQL_IP_ADDRESS_TYPE_UNSPECIFIED
            - PRIMARY
            - OUTGOING
            - PRIVATE
        ipAddress:
          type: string
        timeToRetire:
          type: string
          format: date-time
    BackupRun:
      type: object
      properties:
        kind:
          type: string
          default: sql#backupRun
        id:
          type: string
        status:
          type: string
          enum:
            - SQL_BACKUP_RUN_STATUS_UNSPECIFIED
            - ENQUEUED
            - OVERDUE
            - RUNNING
            - FAILED
            - SUCCESSFUL
            - SKIPPED
            - DELETION_PENDING
            - DELETION_FAILED
            - DELETED
        type:
          type: string
          enum:
            - SQL_BACKUP_RUN_TYPE_UNSPECIFIED
            - AUTOMATED
            - ON_DEMAND
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        instance:
          type: string
        selfLink:
          type: string
    InstancesListResponse:
      type: object
      properties:
        kind:
          type: string
          default: sql#instancesList
        items:
          type: array
          items:
            $ref: '#/components/schemas/DatabaseInstance'
        nextPageToken:
          type: string
    DatabasesListResponse:
      type: object
      properties:
        kind:
          type: string
          default: sql#databasesList
        items:
          type: array
          items:
            $ref: '#/components/schemas/Database'
    UsersListResponse:
      type: object
      properties:
        kind:
          type: string
          default: sql#usersList
        items:
          type: array
          items:
            $ref: '#/components/schemas/User'
    BackupRunsListResponse:
      type: object
      properties:
        kind:
          type: string
          default: sql#backupRunsList
        items:
          type: array
          items:
            $ref: '#/components/schemas/BackupRun'
        nextPageToken:
          type: string
    Operation:
      type: object
      properties:
        kind:
          type: string
          default: sql#operation
        name:
          type: string
        status:
          type: string
          enum:
            - SQL_OPERATION_STATUS_UNSPECIFIED
            - PENDING
            - RUNNING
            - DONE
        operationType:
          type: string
        targetId:
          type: string
        targetProject:
          type: string
        insertTime:
          type: string
          format: date-time
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time