|
| 1 | +# Create Global Active tables using Terraform |
| 2 | + |
| 3 | +## Introduction |
| 4 | + |
| 5 | +This lab walks you through the steps to create a Global Active table (GAT) using Terraform. |
| 6 | + |
| 7 | +Estimated Lab Time: 15 Minutes |
| 8 | + |
| 9 | +### About Global Active tables |
| 10 | + |
| 11 | +Oracle NoSQL Database Cloud Service supports a global active table architecture in which you can create tables, replicate them across multiple regions, and maintain synchronized data across the regional replicas. Today's businesses need to provide faster and better services to their customers. Network latency is a crucial parameter for assessing the performance of any application. Users expect to complete their online activities smoothly and quickly from anywhere. To meet such expectations, enterprises need to host applications and data in distributed regions closest to their users. Oracle NoSQL Database Cloud Service provides a solution to these requirements through Global Active tables. This feature enables application data written in a region to be replicated transparently across multiple regions. |
| 12 | + |
| 13 | +### Prerequisites |
| 14 | + |
| 15 | +* An Oracle Free Tier, Always Free, Paid or LiveLabs Cloud Account |
| 16 | +* Successful completion of [Lab 1 : Create an API Sign-In Key ](?lab=create-api-signing-keys) |
| 17 | +* Successful completion of [Lab 2 : Create singleton tables using Terraform](?lab=create-singleton-tables) |
| 18 | + |
| 19 | +It is easy to deploy a Global Active table on OCI using Terraform. In [Lab 2 : Create singleton tables using Terraform](?lab=create-singleton-tables), you have created a singleton table called **nosql_demo**. In this lab, you will create a regional replica of this table and make it a Global Active table. |
| 20 | + |
| 21 | +## Task 1: Create NoSQL Terraform configuration file |
| 22 | +Resources are the most important element in the Terraform language. Terraform creates a NoSQL table and a table replica as a resource. The NoSQL Terraform configuration file will define the resources to be created. In this lab the resources created are a NoSQL table and a table replica. |
| 23 | + |
| 24 | +When you create a Global Active table: |
| 25 | +* The table should contain at least one JSON column. |
| 26 | +* The table DDL definition must include **with schema frozen** clause. |
| 27 | + |
| 28 | +When you add a regional table replica, you can either specify the name of the table or the OCID of the table. If you specify the name of the table, then you need to specify the OCID of your compartment and the **depends\_on** clause while defining the regional replica as shown below. If you are specifying the OCID of the table, then **depends_on** clause, and compartment OCID is optional. |
| 29 | + |
| 30 | +You create a new file named **nosql.tf** that contains the NoSQL terraform configuration resources for creating NoSQL Database Cloud Service tables. |
| 31 | +In the example below, you are creating a table **nosql_demo** with a json column and schema frozen. You then add a regional replica to the table and make it a Global Active table. |
| 32 | + |
| 33 | +``` |
| 34 | +<copy> |
| 35 | +variable "compartment_ocid" { |
| 36 | +} |
| 37 | +
|
| 38 | +variable "table_ddl_statement" { |
| 39 | + default = "CREATE TABLE IF NOT EXISTS nosql_dem0(id INTEGER, |
| 40 | + name STRING, info JSON,PRIMARY KEY(id)) |
| 41 | + using TTL 10 days with schema frozen" |
| 42 | +} |
| 43 | +
|
| 44 | +resource "oci_nosql_table" "nosql_demo" { |
| 45 | + #Required |
| 46 | + compartment_id = var.compartment_ocid |
| 47 | + ddl_statement = var.table_ddl_statement |
| 48 | + name = "nosql_demo" |
| 49 | +
|
| 50 | + table_limits { |
| 51 | + #Required |
| 52 | + max_read_units = 51 |
| 53 | + max_write_units = 51 |
| 54 | + max_storage_in_gbs = 2 |
| 55 | + } |
| 56 | +} |
| 57 | +#add a regional replica |
| 58 | +resource "oci_nosql_table_replica" "replica_montreal" { |
| 59 | + table_name_or_id = oci_nosql_table.nosql_demo.id |
| 60 | + region = "ca-montreal-1" |
| 61 | + #Optional |
| 62 | + max_read_units = "60" |
| 63 | + max_write_units = "60" |
| 64 | +} |
| 65 | +</copy> |
| 66 | +``` |
| 67 | +*Note: The definition of the singleton table (CREATE TABLE IF NOT EXISTS nosql\_demo...) must always be included in the terraform script even if the table (nosql\_demo) already exists. If the table already exists, Terraform compares the existing definition of the table to the new definition in the script. If there are no changes, the CREATE TABLE definition is ignored. If there are any changes to the definition, the terraform script overwrites the existing definition of the table with the new script (This is equivalent to an ALTER TABLE statement).If you do not include the CREATE TABLE definition in the script and terraform sees the table existing, then terraform drops the table from the existing region.* |
| 68 | + |
| 69 | +## Task 2: Use terraform to run the scripts |
| 70 | + |
| 71 | +Save the config file created above in the same folder where Terraform is installed. |
| 72 | +Invoke terraform and initialize the setup. |
| 73 | +``` |
| 74 | +<copy> |
| 75 | +terraform init |
| 76 | +</copy> |
| 77 | +``` |
| 78 | +Run the following command to invoke the terraform script. |
| 79 | +``` |
| 80 | +<copy> |
| 81 | +terraform apply |
| 82 | +</copy> |
| 83 | +``` |
| 84 | +Terraform shows the plan to be applied and prompts for confirmation as shown below. |
| 85 | +``` |
| 86 | +<copy> |
| 87 | +An execution plan has been generated and is shown below. |
| 88 | +Resource actions are indicated with the following symbols: + create |
| 89 | +
|
| 90 | +Terraform will perform the following actions: |
| 91 | +# oci_nosql_table.nosql_demo will be created |
| 92 | +
|
| 93 | + + resource "oci_nosql_table" "nosql_demo" { |
| 94 | + + compartment_id = "<COMPARTMENT_ID>" |
| 95 | + + ddl_statement = "CREATE TABLE IF NOT EXISTS nosql_demo(id INTEGER, name STRING, info JSON, PRIMARY KEY(id)) with schema frozen" |
| 96 | + + defined_tags = (known after apply) |
| 97 | + + freeform_tags = (known after apply) |
| 98 | + + id = (known after apply) |
| 99 | + + is_auto_reclaimable = (known after apply) |
| 100 | + + is_multi_region = (known after apply) |
| 101 | + + lifecycle_details = (known after apply) |
| 102 | + + local_replica_initialization_in_percent = (known after apply) |
| 103 | + + name = "nosql_demo" |
| 104 | + + replicas = (known after apply) |
| 105 | + + schema = (known after apply) |
| 106 | + + schema_state = (known after apply) |
| 107 | + + state = (known after apply) |
| 108 | + + system_tags = (known after apply) |
| 109 | + + time_created = (known after apply) |
| 110 | + + time_of_expiration = (known after apply) |
| 111 | + + time_updated = (known after apply) |
| 112 | +
|
| 113 | + + table_limits { |
| 114 | + + capacity_mode = (known after apply) |
| 115 | + + max_read_units = 60 |
| 116 | + + max_storage_in_gbs = 1 |
| 117 | + + max_write_units = 60 |
| 118 | + } |
| 119 | + } |
| 120 | +
|
| 121 | + # oci_nosql_table_replica.replica_yul will be created |
| 122 | + + resource "oci_nosql_table_replica" "replica_yul" { |
| 123 | + + compartment_id = (known after apply) |
| 124 | + + id = (known after apply) |
| 125 | + + max_read_units = (known after apply) |
| 126 | + + max_write_units = (known after apply) |
| 127 | + + region = "ca-montreal-1" |
| 128 | + + table_name_or_id = (known after apply) |
| 129 | + } |
| 130 | +
|
| 131 | +Do you want to perform these actions? |
| 132 | +Terraform will perform the actions described above. |
| 133 | +Only 'yes' will be accepted to approve. |
| 134 | +<copy> |
| 135 | +``` |
| 136 | +On confirmation, a regional replica of the *nosql_demo* table is created, converting the singleton table to a GAT. |
| 137 | + |
| 138 | +You may proceed to the next lab. |
| 139 | + |
| 140 | +## Learn More |
| 141 | + |
| 142 | +* [Global Active Tables in NDCS](https://docs.oracle.com/en/cloud/paas/nosql-cloud/gasnd/) |
| 143 | +* [Table Replica Resource in Terraform](https://registry.terraform.io/providers/oracle/oci/latest/docs/resources/nosql_table_replica) |
| 144 | + |
| 145 | +## Acknowledgements |
| 146 | +* **Author** - Vandana Rajamani, Consulting UA Developer, DB Cloud Technical Svcs & User Assistance |
| 147 | +* **Last Updated By/Date** - Vandana Rajamani, Consulting UA Developer, DB Cloud Technical Svcs & User Assistance, November 2024 |
0 commit comments