import * as pulumi from "@pulumi/pulumi"; import * as inputs from "../types/input"; import * as outputs from "../types/output"; /** * Creates a new Google SQL Database Instance. For more information, see the [official documentation](https://cloud.google.com/sql/docs/mysql/create-instance), * or the [JSON API](https://cloud.google.com/sql/docs/admin-api/v1beta4/instances). * * > **NOTE on `gcp.sql.DatabaseInstance`:** - Second-generation instances include a * default 'root'@'%' user with no password. This user will be deleted by the provider on * instance creation. You should use `gcp.sql.User` to define a custom user with * a restricted host and strong password. * * > **Note**: On newer versions of the provider, you must explicitly set `deletion_protection=false` * (and run `pulumi update` to write the field to state) in order to destroy an instance. * It is recommended to not set this field (or set it to true) until you're ready to destroy the instance and its databases. * * ## Example Usage * * ### SQL Second Generation Instance * * ```typescript * import * as pulumi from "@pulumi/pulumi"; * import * as gcp from "@pulumi/gcp"; * * const main = new gcp.sql.DatabaseInstance("main", { * name: "main-instance", * databaseVersion: "POSTGRES_15", * region: "us-central1", * settings: { * tier: "db-f1-micro", * }, * }); * ``` * * ### Private IP Instance * > **NOTE:** For private IP instance setup, note that the `gcp.sql.DatabaseInstance` does not actually interpolate values from `gcp.servicenetworking.Connection`. You must explicitly add a `dependsOn`reference as shown below. * * ```typescript * import * as pulumi from "@pulumi/pulumi"; * import * as gcp from "@pulumi/gcp"; * import * as random from "@pulumi/random"; * * const privateNetwork = new gcp.compute.Network("private_network", {name: "private-network"}); * const privateIpAddress = new gcp.compute.GlobalAddress("private_ip_address", { * name: "private-ip-address", * purpose: "VPC_PEERING", * addressType: "INTERNAL", * prefixLength: 16, * network: privateNetwork.id, * }); * const privateVpcConnection = new gcp.servicenetworking.Connection("private_vpc_connection", { * network: privateNetwork.id, * service: "servicenetworking.googleapis.com", * reservedPeeringRanges: [privateIpAddress.name], * }); * const dbNameSuffix = new random.RandomId("db_name_suffix", {byteLength: 4}); * const instance = new gcp.sql.DatabaseInstance("instance", { * name: pulumi.interpolate`private-instance-${dbNameSuffix.hex}`, * region: "us-central1", * databaseVersion: "MYSQL_5_7", * settings: { * tier: "db-f1-micro", * ipConfiguration: { * ipv4Enabled: false, * privateNetwork: privateNetwork.selfLink, * enablePrivatePathForGoogleCloudServices: true, * }, * }, * }, { * dependsOn: [privateVpcConnection], * }); * ``` * * ### ENTERPRISE_PLUS Instance with dataCacheConfig * * ```typescript * import * as pulumi from "@pulumi/pulumi"; * import * as gcp from "@pulumi/gcp"; * * const main = new gcp.sql.DatabaseInstance("main", { * name: "enterprise-plus-main-instance", * databaseVersion: "MYSQL_8_0_31", * settings: { * tier: "db-perf-optimized-N-2", * edition: "ENTERPRISE_PLUS", * dataCacheConfig: { * dataCacheEnabled: true, * }, * }, * }); * ``` * * ### Cloud SQL Instance with PSC connectivity * * ```typescript * import * as pulumi from "@pulumi/pulumi"; * import * as gcp from "@pulumi/gcp"; * * const main = new gcp.sql.DatabaseInstance("main", { * name: "psc-enabled-main-instance", * databaseVersion: "MYSQL_8_0", * settings: { * tier: "db-f1-micro", * ipConfiguration: { * pscConfigs: [{ * pscEnabled: true, * allowedConsumerProjects: ["allowed-consumer-project-name"], * }], * ipv4Enabled: false, * }, * backupConfiguration: { * enabled: true, * binaryLogEnabled: true, * }, * availabilityType: "REGIONAL", * }, * }); * ``` * * ### Cloud SQL Instance with PSC auto connections * * ```typescript * import * as pulumi from "@pulumi/pulumi"; * import * as gcp from "@pulumi/gcp"; * * const main = new gcp.sql.DatabaseInstance("main", { * name: "psc-enabled-main-instance", * databaseVersion: "MYSQL_8_0", * settings: { * tier: "db-f1-micro", * ipConfiguration: { * pscConfigs: [{ * pscEnabled: true, * allowedConsumerProjects: ["allowed-consumer-project-name"], * pscAutoConnections: [{ * consumerNetwork: "network-name", * consumerServiceProjectId: "project-id", * }], * }], * ipv4Enabled: false, * }, * backupConfiguration: { * enabled: true, * binaryLogEnabled: true, * }, * availabilityType: "REGIONAL", * }, * }); * ``` * * ## Switchover * * Users can perform a switchover on a replica by following the steps below. * * ~>**WARNING:** Failure to follow these steps can lead to data loss (You will be warned during plan stage). To prevent data loss during a switchover, please verify your plan with the checklist below. * * For a more in-depth walkthrough with example code, see the Switchover Guide * * ### Steps to Invoke Switchover * * MySQL/PostgreSQL: Create a cross-region, Enterprise Plus edition primary and replica pair, then set the value of primary's `replication_cluster.failover_dr_replica_name` as the replica. * * SQL Server: Create a `cascadable` replica in a different region from the primary (`cascadableReplica` is set to true in `replicaConfiguration`) * * #### Invoking switchover in the replica resource: * 1. Change instanceType from `READ_REPLICA_INSTANCE` to `CLOUD_SQL_INSTANCE` * 2. Remove `masterInstanceName` * 3. (SQL Server) Remove `replicaConfiguration` * 4. Add current primary's name to the replica's `replicaNames` list * 5. (MySQL/PostgreSQL) Add current primary's name to the replica's `replication_cluster.failover_dr_replica_name`. * 6. (MySQL/PostgreSQL) Adjust `backupConfiguration`. See Switchover Guide for details. * * #### Updating the primary resource: * 1. Change `instanceType` from `CLOUD_SQL_INSTANCE` to `READ_REPLICA_INSTANCE` * 2. Set `masterInstanceName` to the original replica (which will be primary after switchover) * 3. (SQL Server) Set `replicaConfiguration` and set `cascadableReplica` to `true` * 4. Remove original replica from `replicaNames` * * **NOTE**: Do **not** delete the replicaNames field, even if it has no replicas remaining. Set replicaNames = [ ] to indicate it having no replicas. * 5. (MySQL/PostgreSQL) Set `replication_cluster.failover_dr_replica_name` as the empty string. * 6. (MySQL/PostgreSQL) Adjust `backupConfiguration`. See Switchover Guide for details. * #### Plan and verify that: * - `pulumi preview` outputs **"0 to add, 0 to destroy"** * - `pulumi preview` does not say **"must be replaced"** for any resource * - Every resource **"will be updated in-place"** * - Only the 2 instances involved in switchover have planned changes * - (Recommended) Use `deletionProtection` on instances as a safety measure * * ## Import * * Database instances can be imported using one of any of these accepted formats: * * * `projects/{{project}}/instances/{{name}}` * * * `{{project}}/{{name}}` * * * `{{name}}` * * When using the `pulumi import` command, Database instances can be imported using one of the formats above. For example: * * ```sh * $ pulumi import gcp:sql/databaseInstance:DatabaseInstance default projects/{{project}}/instances/{{name}} * ``` * * ```sh * $ pulumi import gcp:sql/databaseInstance:DatabaseInstance default {{project}}/{{name}} * ``` * * ```sh * $ pulumi import gcp:sql/databaseInstance:DatabaseInstance default {{name}} * ``` * * config and set on the server. * * When importing, double-check that your config has all the fields set that you expect- just seeing * * no diff isn't sufficient to know that your config could reproduce the imported resource. */ export declare class DatabaseInstance extends pulumi.CustomResource { /** * Get an existing DatabaseInstance resource's state with the given name, ID, and optional extra * properties used to qualify the lookup. * * @param name The _unique_ name of the resulting resource. * @param id The _unique_ provider ID of the resource to lookup. * @param state Any extra arguments used during the lookup. * @param opts Optional settings to control the behavior of the CustomResource. */ static get(name: string, id: pulumi.Input, state?: DatabaseInstanceState, opts?: pulumi.CustomResourceOptions): DatabaseInstance; /** * Returns true if the given object is an instance of DatabaseInstance. This is designed to work even * when multiple copies of the Pulumi SDK have been loaded into the same process. */ static isInstance(obj: any): obj is DatabaseInstance; /** * The list of all maintenance versions applicable on the instance. */ readonly availableMaintenanceVersions: pulumi.Output; /** * The context needed to create this instance as a clone of another instance. When this field is set during * resource creation, this provider will attempt to clone another instance as indicated in the context. The * configuration is detailed below. */ readonly clone: pulumi.Output; /** * The connection name of the instance to be used in * connection strings. For example, when connecting with [Cloud SQL Proxy](https://cloud.google.com/sql/docs/mysql/connect-admin-proxy). */ readonly connectionName: pulumi.Output; /** * The MySQL, PostgreSQL or * SQL Server version to use. Supported values include `MYSQL_5_6`, * `MYSQL_5_7`, `MYSQL_8_0`, `MYSQL_8_4`, `POSTGRES_9_6`,`POSTGRES_10`, `POSTGRES_11`, * `POSTGRES_12`, `POSTGRES_13`, `POSTGRES_14`, `POSTGRES_15`, `POSTGRES_16`, `POSTGRES_17`, * `SQLSERVER_2017_STANDARD`, `SQLSERVER_2017_ENTERPRISE`, `SQLSERVER_2017_EXPRESS`, `SQLSERVER_2017_WEB`. * `SQLSERVER_2019_STANDARD`, `SQLSERVER_2019_ENTERPRISE`, `SQLSERVER_2019_EXPRESS`, * `SQLSERVER_2019_WEB`. * [Database Version Policies](https://cloud.google.com/sql/docs/db-versions) * includes an up-to-date reference of supported versions. */ readonly databaseVersion: pulumi.Output; /** * Whether or not to allow the provider to destroy the instance. Unless this field is set to false * in state, a `destroy` or `update` command that deletes the instance will fail. Defaults to `true`. */ readonly deletionProtection: pulumi.Output; /** * The DNS name of the instance. See [Connect to an instance using Private Service Connect](https://cloud.google.com/sql/docs/mysql/configure-private-service-connect#view-summary-information-cloud-sql-instances-psc-enabled) for more details. */ readonly dnsName: pulumi.Output; /** * The full path to the encryption key used for the CMEK disk encryption. Setting * up disk encryption currently requires manual steps outside of this provider. * The provided key must be in the same region as the SQL instance. In order * to use this feature, a special kind of service account must be created and * granted permission on this key. This step can currently only be done * manually, please see [this step](https://cloud.google.com/sql/docs/mysql/configure-cmek#service-account). * That service account needs the `Cloud KMS > Cloud KMS CryptoKey Encrypter/Decrypter` role on your * key - please see [this step](https://cloud.google.com/sql/docs/mysql/configure-cmek#grantkey). */ readonly encryptionKeyName: pulumi.Output; /** * The first IPv4 address of any type assigned. */ readonly firstIpAddress: pulumi.Output; /** * The type of the instance. The supported values are `SQL_INSTANCE_TYPE_UNSPECIFIED`, `CLOUD_SQL_INSTANCE`, `ON_PREMISES_INSTANCE` and `READ_REPLICA_INSTANCE`. */ readonly instanceType: pulumi.Output; readonly ipAddresses: pulumi.Output; /** * The current software version on the instance. This attribute can not be set during creation. Refer to `availableMaintenanceVersions` attribute to see what `maintenanceVersion` are available for upgrade. When this attribute gets updated, it will cause an instance restart. Setting a `maintenanceVersion` value that is older than the current one on the instance will be ignored. */ readonly maintenanceVersion: pulumi.Output; /** * The name of the existing instance that will * act as the master in the replication setup. Note, this requires the master to * have `binaryLogEnabled` set, as well as existing backups. */ readonly masterInstanceName: pulumi.Output; /** * The name of the instance. If the name is left * blank, the provider will randomly generate one when the instance is first * created. This is done because after a name is used, it cannot be reused for * up to [one week](https://cloud.google.com/sql/docs/delete-instance). */ readonly name: pulumi.Output; /** * The first private (`PRIVATE`) IPv4 address assigned. */ readonly privateIpAddress: pulumi.Output; /** * The ID of the project in which the resource belongs. If it * is not provided, the provider project is used. */ readonly project: pulumi.Output; /** * the URI that points to the service attachment of the instance. */ readonly pscServiceAttachmentLink: pulumi.Output; /** * The first public (`PRIMARY`) IPv4 address assigned. */ readonly publicIpAddress: pulumi.Output; /** * The region the instance will sit in. If a region is not provided in the resource definition, * the provider region will be used instead. * * - - - */ readonly region: pulumi.Output; /** * The configuration for replication. The * configuration is detailed below. */ readonly replicaConfiguration: pulumi.Output; /** * List of replica names. Can be updated. */ readonly replicaNames: pulumi.Output; /** * A primary instance and disaster recovery replica pair. Applicable to MySQL and PostgreSQL. This field can be set only * after both the primary and replica are created. */ readonly replicationCluster: pulumi.Output; /** * The context needed to restore the database to a backup run. This field will * cause the provider to trigger the database to restore from the backup run indicated. The configuration is detailed below. * **NOTE:** Restoring from a backup is an imperative action and not recommended via this provider. Adding or modifying this * block during resource creation/update will trigger the restore action after the resource is created/updated. */ readonly restoreBackupContext: pulumi.Output; /** * Initial root password. Can be updated. Required for MS SQL Server. */ readonly rootPassword: pulumi.Output; /** * The URI of the created resource. */ readonly selfLink: pulumi.Output; readonly serverCaCerts: pulumi.Output; /** * The service account email address assigned to the * instance. */ readonly serviceAccountEmailAddress: pulumi.Output; /** * The settings to use for the database. The * configuration is detailed below. Required if `clone` is not set. */ readonly settings: pulumi.Output; /** * Create a DatabaseInstance resource with the given unique name, arguments, and options. * * @param name The _unique_ name of the resource. * @param args The arguments to use to populate this resource's properties. * @param opts A bag of options that control this resource's behavior. */ constructor(name: string, args: DatabaseInstanceArgs, opts?: pulumi.CustomResourceOptions); } /** * Input properties used for looking up and filtering DatabaseInstance resources. */ export interface DatabaseInstanceState { /** * The list of all maintenance versions applicable on the instance. */ availableMaintenanceVersions?: pulumi.Input[]>; /** * The context needed to create this instance as a clone of another instance. When this field is set during * resource creation, this provider will attempt to clone another instance as indicated in the context. The * configuration is detailed below. */ clone?: pulumi.Input; /** * The connection name of the instance to be used in * connection strings. For example, when connecting with [Cloud SQL Proxy](https://cloud.google.com/sql/docs/mysql/connect-admin-proxy). */ connectionName?: pulumi.Input; /** * The MySQL, PostgreSQL or * SQL Server version to use. Supported values include `MYSQL_5_6`, * `MYSQL_5_7`, `MYSQL_8_0`, `MYSQL_8_4`, `POSTGRES_9_6`,`POSTGRES_10`, `POSTGRES_11`, * `POSTGRES_12`, `POSTGRES_13`, `POSTGRES_14`, `POSTGRES_15`, `POSTGRES_16`, `POSTGRES_17`, * `SQLSERVER_2017_STANDARD`, `SQLSERVER_2017_ENTERPRISE`, `SQLSERVER_2017_EXPRESS`, `SQLSERVER_2017_WEB`. * `SQLSERVER_2019_STANDARD`, `SQLSERVER_2019_ENTERPRISE`, `SQLSERVER_2019_EXPRESS`, * `SQLSERVER_2019_WEB`. * [Database Version Policies](https://cloud.google.com/sql/docs/db-versions) * includes an up-to-date reference of supported versions. */ databaseVersion?: pulumi.Input; /** * Whether or not to allow the provider to destroy the instance. Unless this field is set to false * in state, a `destroy` or `update` command that deletes the instance will fail. Defaults to `true`. */ deletionProtection?: pulumi.Input; /** * The DNS name of the instance. See [Connect to an instance using Private Service Connect](https://cloud.google.com/sql/docs/mysql/configure-private-service-connect#view-summary-information-cloud-sql-instances-psc-enabled) for more details. */ dnsName?: pulumi.Input; /** * The full path to the encryption key used for the CMEK disk encryption. Setting * up disk encryption currently requires manual steps outside of this provider. * The provided key must be in the same region as the SQL instance. In order * to use this feature, a special kind of service account must be created and * granted permission on this key. This step can currently only be done * manually, please see [this step](https://cloud.google.com/sql/docs/mysql/configure-cmek#service-account). * That service account needs the `Cloud KMS > Cloud KMS CryptoKey Encrypter/Decrypter` role on your * key - please see [this step](https://cloud.google.com/sql/docs/mysql/configure-cmek#grantkey). */ encryptionKeyName?: pulumi.Input; /** * The first IPv4 address of any type assigned. */ firstIpAddress?: pulumi.Input; /** * The type of the instance. The supported values are `SQL_INSTANCE_TYPE_UNSPECIFIED`, `CLOUD_SQL_INSTANCE`, `ON_PREMISES_INSTANCE` and `READ_REPLICA_INSTANCE`. */ instanceType?: pulumi.Input; ipAddresses?: pulumi.Input[]>; /** * The current software version on the instance. This attribute can not be set during creation. Refer to `availableMaintenanceVersions` attribute to see what `maintenanceVersion` are available for upgrade. When this attribute gets updated, it will cause an instance restart. Setting a `maintenanceVersion` value that is older than the current one on the instance will be ignored. */ maintenanceVersion?: pulumi.Input; /** * The name of the existing instance that will * act as the master in the replication setup. Note, this requires the master to * have `binaryLogEnabled` set, as well as existing backups. */ masterInstanceName?: pulumi.Input; /** * The name of the instance. If the name is left * blank, the provider will randomly generate one when the instance is first * created. This is done because after a name is used, it cannot be reused for * up to [one week](https://cloud.google.com/sql/docs/delete-instance). */ name?: pulumi.Input; /** * The first private (`PRIVATE`) IPv4 address assigned. */ privateIpAddress?: pulumi.Input; /** * The ID of the project in which the resource belongs. If it * is not provided, the provider project is used. */ project?: pulumi.Input; /** * the URI that points to the service attachment of the instance. */ pscServiceAttachmentLink?: pulumi.Input; /** * The first public (`PRIMARY`) IPv4 address assigned. */ publicIpAddress?: pulumi.Input; /** * The region the instance will sit in. If a region is not provided in the resource definition, * the provider region will be used instead. * * - - - */ region?: pulumi.Input; /** * The configuration for replication. The * configuration is detailed below. */ replicaConfiguration?: pulumi.Input; /** * List of replica names. Can be updated. */ replicaNames?: pulumi.Input[]>; /** * A primary instance and disaster recovery replica pair. Applicable to MySQL and PostgreSQL. This field can be set only * after both the primary and replica are created. */ replicationCluster?: pulumi.Input; /** * The context needed to restore the database to a backup run. This field will * cause the provider to trigger the database to restore from the backup run indicated. The configuration is detailed below. * **NOTE:** Restoring from a backup is an imperative action and not recommended via this provider. Adding or modifying this * block during resource creation/update will trigger the restore action after the resource is created/updated. */ restoreBackupContext?: pulumi.Input; /** * Initial root password. Can be updated. Required for MS SQL Server. */ rootPassword?: pulumi.Input; /** * The URI of the created resource. */ selfLink?: pulumi.Input; serverCaCerts?: pulumi.Input[]>; /** * The service account email address assigned to the * instance. */ serviceAccountEmailAddress?: pulumi.Input; /** * The settings to use for the database. The * configuration is detailed below. Required if `clone` is not set. */ settings?: pulumi.Input; } /** * The set of arguments for constructing a DatabaseInstance resource. */ export interface DatabaseInstanceArgs { /** * The context needed to create this instance as a clone of another instance. When this field is set during * resource creation, this provider will attempt to clone another instance as indicated in the context. The * configuration is detailed below. */ clone?: pulumi.Input; /** * The MySQL, PostgreSQL or * SQL Server version to use. Supported values include `MYSQL_5_6`, * `MYSQL_5_7`, `MYSQL_8_0`, `MYSQL_8_4`, `POSTGRES_9_6`,`POSTGRES_10`, `POSTGRES_11`, * `POSTGRES_12`, `POSTGRES_13`, `POSTGRES_14`, `POSTGRES_15`, `POSTGRES_16`, `POSTGRES_17`, * `SQLSERVER_2017_STANDARD`, `SQLSERVER_2017_ENTERPRISE`, `SQLSERVER_2017_EXPRESS`, `SQLSERVER_2017_WEB`. * `SQLSERVER_2019_STANDARD`, `SQLSERVER_2019_ENTERPRISE`, `SQLSERVER_2019_EXPRESS`, * `SQLSERVER_2019_WEB`. * [Database Version Policies](https://cloud.google.com/sql/docs/db-versions) * includes an up-to-date reference of supported versions. */ databaseVersion: pulumi.Input; /** * Whether or not to allow the provider to destroy the instance. Unless this field is set to false * in state, a `destroy` or `update` command that deletes the instance will fail. Defaults to `true`. */ deletionProtection?: pulumi.Input; /** * The full path to the encryption key used for the CMEK disk encryption. Setting * up disk encryption currently requires manual steps outside of this provider. * The provided key must be in the same region as the SQL instance. In order * to use this feature, a special kind of service account must be created and * granted permission on this key. This step can currently only be done * manually, please see [this step](https://cloud.google.com/sql/docs/mysql/configure-cmek#service-account). * That service account needs the `Cloud KMS > Cloud KMS CryptoKey Encrypter/Decrypter` role on your * key - please see [this step](https://cloud.google.com/sql/docs/mysql/configure-cmek#grantkey). */ encryptionKeyName?: pulumi.Input; /** * The type of the instance. The supported values are `SQL_INSTANCE_TYPE_UNSPECIFIED`, `CLOUD_SQL_INSTANCE`, `ON_PREMISES_INSTANCE` and `READ_REPLICA_INSTANCE`. */ instanceType?: pulumi.Input; /** * The current software version on the instance. This attribute can not be set during creation. Refer to `availableMaintenanceVersions` attribute to see what `maintenanceVersion` are available for upgrade. When this attribute gets updated, it will cause an instance restart. Setting a `maintenanceVersion` value that is older than the current one on the instance will be ignored. */ maintenanceVersion?: pulumi.Input; /** * The name of the existing instance that will * act as the master in the replication setup. Note, this requires the master to * have `binaryLogEnabled` set, as well as existing backups. */ masterInstanceName?: pulumi.Input; /** * The name of the instance. If the name is left * blank, the provider will randomly generate one when the instance is first * created. This is done because after a name is used, it cannot be reused for * up to [one week](https://cloud.google.com/sql/docs/delete-instance). */ name?: pulumi.Input; /** * The ID of the project in which the resource belongs. If it * is not provided, the provider project is used. */ project?: pulumi.Input; /** * The region the instance will sit in. If a region is not provided in the resource definition, * the provider region will be used instead. * * - - - */ region?: pulumi.Input; /** * The configuration for replication. The * configuration is detailed below. */ replicaConfiguration?: pulumi.Input; /** * List of replica names. Can be updated. */ replicaNames?: pulumi.Input[]>; /** * A primary instance and disaster recovery replica pair. Applicable to MySQL and PostgreSQL. This field can be set only * after both the primary and replica are created. */ replicationCluster?: pulumi.Input; /** * The context needed to restore the database to a backup run. This field will * cause the provider to trigger the database to restore from the backup run indicated. The configuration is detailed below. * **NOTE:** Restoring from a backup is an imperative action and not recommended via this provider. Adding or modifying this * block during resource creation/update will trigger the restore action after the resource is created/updated. */ restoreBackupContext?: pulumi.Input; /** * Initial root password. Can be updated. Required for MS SQL Server. */ rootPassword?: pulumi.Input; /** * The settings to use for the database. The * configuration is detailed below. Required if `clone` is not set. */ settings?: pulumi.Input; }