Project: YDB (App Definition and Development / Database)
File: terraform.md

can create, delete, and modify the following objects inside a {{ ydb-short-name }} cluster: of tables for tables {% note warning %} Currently, the {{ ydb-short-name }} provider for Terraform is under development, and its functionality will be expanded. {% endnote %} To get started, you need to: Deploy the cluster Create a database (described in paragraph 1 for the appropriate type of cluster deployment) Install Install and configure You need to download Build the provider by executing `$make local-build` in the root directory of the provider's code. To do this, you need to additionally install the utility and The provider will be installed in the Terraform plugins folder - `~/.terraform.d/plugins/terraform.storage.ydb.tech/...` Add the provider to `~/.terraformrc` by adding the following content to the `provider_installation` section (if there was no such section yet, then create): ```tf provider_installation { direct { exclude = ["terraform.storage.ydb.tech//"] } filesystem_mirror { path = "/PATHTOHOME/.terraform.d/plugins" include = ["terraform.storage.ydb.tech//"] } } ``` Next, we configure the {{ ydb-short-name }} provider itself to work (for example, in the file `provider.tf` in the working directory): ```tf terraform { required_providers { ydb = { source = "terraform.storage.ydb.tech/provider/ydb" } } required_version = ">= 0.13" } provider "ydb" { token = "<TOKEN>" //OR for static credentials user = "<USER>" password = "<PASSWORD>" } ``` Where: `token` - specifies the access token to the database if authentication is used, for example, using a third-party provider. `user` - the username for accessing the database in case of using authentication by `password` - the password for accessing the database in case of using authentication by The following commands are used to apply changes to terraform resources: `terraform init` - initialization of the terraform module (performed in the terraform resource directory). `terraform validate` - checking the syntax of terraform resource configuration files. `terraform apply` - direct application of the terraform resource configuration. For ease of use, it is recommended to name terraform files as follows: `provider.tf` - contains the settings of the terraform provider itself. `main.tf` - contains a set of resources to create. For all resources describing data schema objects, you must specify the database details in which they are located. To do this, provide one of the two arguments: The connection string `connection_string` is an expression of the form `grpc(s)://HOST:PORT/?database=/database/path`, where `grpc(s)://HOST:PORT/` endpoint, and `/database/path` is the path of the database. For example, `grpcs://example.com:2135?database=/Root/testdb0`. `databaseendpoint` - used when working with the [topics] resource (#topicresource) (analogous to `connection_string` when working with table resources). {% note info %} The user can transfer the connection string to the database using standard Terraform tools - via . {% endnote %} If you are using the creation of `ydbtablechangefeed` or `ydb_topic` resources and authorization is not enabled on the {{ ydb-short-name }} server, then in the DB config you need to specify: ```yaml ... pqconfig: requirecredentialsinnewprotocol: false check_acl: false ``` This example combines all types of resources that are available in the {{ ydb-short-name }} Terraform provider: ```tf variable "db-connect" { type = string default = "grpc(s)://HOST:PORT/?database=/database/path" # you need to specify the path to the database } resource "ydb_table" "table" { path = "1/2/3/tftest" connection_string =

column { name = "a" type = "Utf8" } column { name = "b" type = "String" } column { name = "ttlBase" type = "Uint32" } ttl { column_name = "ttlBase" expire_interval = "P7D" unit = "milliseconds" } primary_key = ["b", "a"] partitioning_settings { autopartitioningminpartitionscount = 5 autopartitioningmaxpartitionscount = 8 autopartitioningpartitionsizemb = 256 autopartitioningby_load = true } } resource "ydbtableindex" "table_index" { tablepath = ydbtable.table.path connectionstring = ydbtable.table.connection_string name = "my_index" type = "globalsync" # "globalasync" columns = ["a", "b"] dependson = [ydbtable.table] # link to the table creation resource } resource "ydbtablechangefeed" "table_changefeed" { tableid = ydbtable.table.id name = "changefeed" mode = "NEW_IMAGE" format = "JSON" consumer { name = "test" supported_codecs = ["raw", "gzip"] } dependson = [ydbtable.table] # link to the table creation resource } resource "ydb_topic" "test" { databaseendpoint = ydbtable.table.connection_string name = "1/2/test" supported_codecs = ["zstd"] consumer { name = "test-consumer3" startingmessagetimestamp_ms = 0 supported_codecs = ["zstd","raw"] } consumer { name = "test-consumer1" startingmessagetimestamp_ms = 2000 supported_codecs = ["zstd"] } consumer { name = "test-consumer2" startingmessagetimestamp_ms = 0 supported_codecs = ["zstd"] } } ``` All resources of the {{ ydb-short-name }} Terraform provider will be described in detail below. {% note info %} Working with column-oriented tables via Terraform is not yet available. {% endnote %} The `ydb_table` resource is used to work with tables. Example: ```tf resource "ydbtable" "ydbtable" { path = "path/to/table" # path relative to the base root connection_string = "grpc(s)://HOST:PORT/?database=/database/path" #DB connection example column { name = "a" type = "Utf8" not_null = true } column { name = "b" type = "Uint32" not_null = true } column { name = "c" type = String not_null = false } column { name = "f" type = "Utf8" } column { name = "e" type = "String" } column { name = "d" type = "Timestamp" } primary_key = ["b", "a"] } ``` The following arguments are supported: `path` - (required) is the path of the table relative to the root of the database (example - `/path/to/table`). `connection_string` (required) . `column` (required) column properties (see the argument). `family` - (optional) is a column group (see the argument). `primary_key` (required) of the table that contains an ordered list of column names of the primary key. `ttl` (optional) TTL (see the argument). `partitioning_settings` (optional) partitioning settings (see the argument ). `keybloomfilter` (optional) (bool) use , the default value is false. `readreplicassettings` (optional) settings for . The `column` argument describes the of the table. {% note warning %} Using Terraform, you cannot only add columns but not delete them. To delete a column, use the {{ ydb-short-name }} tools, then delete the column from the resource description. When trying to apply changes to the table's columns (changing the data type or name), Terraform will not try to delete them but will try to do an update-in-place, though the changes will not be applied. {% endnote %} Example: ```tf column { name = "column_name" type = "Utf8" family = "some_family" not_null = true } ``` `name` - (required) is the column's name. `type` (required) columns. Simple column types are

However, container types cannot be used as data types of table columns. `family` - (optional) is the name of the column group (see the argument). `not_null` (optional) column cannot contain `NULL`. The default value: `false`. The `family` argument describes . `name` - (required) is the name of the column group. `data` (required) for column data of this group. `compression` (required) . Example: ```tf family { name = "my_family" data = "ssd" compression = "lz4" } ``` The `partitioning_settings` argument describes . Example: ```tf partitioning_settings { autopartitioningminpartitionscount = 5 autopartitioningmaxpartitionscount = 8 autopartitioningpartitionsizemb = 256 autopartitioningby_load = true } ``` `uniform_partitions` (optional) the number of . `partitionatkeys` (optional) . `autopartitioningminpartitionscount` (optional) when auto-partitioning. `autopartitioningmaxpartitionscount` (optional) when auto-partitioning. `autopartitioningpartitionsizemb` (optional) setting the value of in megabytes. `autopartitioningbysizeenabled` (optional) enabling auto-partitioning by size (bool), enabled by default (true). `autopartitioningby_load` (optional) enabling (bool), disabled by default (false). See the links above for more information about the parameters and their default values. The `ttl` argument describes the settings. Example: ```tf ttl { columnname = "columnname" expire_interval = "PT1H" # 1 hour unit = "seconds" # for numeric column types (non-ISO8601) } ``` `column_name` - (required) is the column name for TTL. `expire_interval` (required) interval in format (for example, `P1D` is an interval of 1 day, that is, 24 hours). `unit` (optional) is set if the column with ttl has a . Supported values: `seconds` `milliseconds` `microseconds` `nanoseconds` The resource is used to work with a table index. Example: ```tf resource "ydbtableindex" "ydbtableindex" { table_path = "path/to/table" # path relative to the base root connection_string = "grpc(s)://HOST:PORT/?database=/database/path" #DB connection example name = "my_index" type = "globalsync" # "globalasync" columns = ["a", "b"] cover = ["c"] } ``` The following arguments are supported: `tablepath` - is the path of the table. Specified if `tableid` is not specified. `connectionstring` . Specified if `tableid` is not specified. `tableid` - terraform-table identifier. Specify if `tablepath` or `connection_string` is not specified. `name` - (required) is the name of the index. `type` - (required) is the index type . `columns` - (required) is an ordered list of column names participating in the index. `cover` - (required) is a list of additional columns for the covering index. The `ydbtablechangefeed` resource is used to work with the of the table. Example: ```tf resource "ydbtablechangefeed" "ydbtablechangefeed" { tableid = ydbtable.ydb_table.id name = "changefeed" mode = "NEW_IMAGE" format = "JSON" } ``` The following arguments are supported: `tablepath` - is the path of the table. Specified if `tableid` is not specified. `connectionstring` . Specified if `tableid` is not specified. `tableid` terraform-table identifier. Specify if `tablepath` or `connection_string` is not specified. `name` - (required) is the name of the change stream. `mode` - (required) is the mode of operation of the . `format` - (required) is the format of the . `virtual_timestamps` (optional) using . `retention_period` (optional) data storage time in format. `consumer` - (optional) is a reader of the change data capture (see the argument ). The `consumer` argument describes the of the change data capture. `name` - (required) is the reader's name. `supported_codecs` (optional) supported data codec. `startingmessagetimestamp_ms` (optional) timestamp in format in milliseconds, from which the reader will start reading the

```tf resource "ydbtable" "ydbtable" { path = "path/to/table" # path relative to the base root connection_string = "grpc(s)://HOST:PORT/?database=/database/path" #DB connection example column { name = "a" type = "Uint64" not_null = true } column { name = "b" type = "Uint32" not_null = true } column { name = "c" type = String not_null = false } column { name = "f" type = "Utf8" } column { name = "e" type = "String" } column { name = "d" type = "Timestamp" } primary_key = [ "a", "b" ] } ``` ```tf resource "ydbtable" "ydbtable" { path = "path/to/table" # path relative to the base root connection_string = "grpc(s)://HOST:PORT/?database=/database/path" #DB connection example column { name = "a" type = "Uint64" not_null = true } column { name = "b" type = "Uint32" not_null = true } column { name = "c" type = "Utf8" } column { name = "f" type = "Utf8" } column { name = "e" type = "String" } column { name = "d" type = "Timestamp" } primary_key = [ "a", "b" ] ttl { column_name = "d" expire_interval = "PT5S" } partitioning_settings { autopartitioningby_load = false autopartitioningpartitionsizemb = 256 autopartitioningminpartitionscount = 6 autopartitioningmaxpartitionscount = 8 } readreplicassettings = "PER_AZ:1" keybloomfilter = true # Default = false } resource "ydbtablechangefeed" "ydbtablechangefeed" { tableid = ydbtable.ydb_table.id name = "changefeed" mode = "NEW_IMAGE" format = "JSON" consumer { name = "test_consumer" } dependson = [ydbtable.ydb_table] # link to the table creation resource } resource "ydbtableindex" "ydbtableindex" { tableid = ydbtable.ydb_table.id name = "some_index" columns = ["c", "d"] cover = ["e"] type = "global_sync" dependson = [ydbtable.ydb_table] # link to the table creation resource } ``` The `ydb_topic` resource is used to work with {% note info %} The topic cannot be created in the root of the database; you need to specify at least one directory in the name of the topic. When trying to create a topic in the root of the database, the provider will return an error. {% endnote %} Example: ```tf resource "ydbtopic" "ydbtopic" { database_endpoint = "grpcs://example.com:2135/?database=/Root/testdb0" #database connection example name = "test/test1" supported_codecs = ["zstd"] consumer { name = "test-consumer1" startingmessagetimestamp_ms = 0 supported_codecs = ["zstd","raw"] } consumer { name = "test-consumer2" startingmessagetimestamp_ms = 2000 supported_codecs = ["zstd"] } consumer { name = "test-consumer3" startingmessagetimestamp_ms = 0 supported_codecs = ["zstd"] } } ``` The following arguments are supported: `name` - (required) is the name of the topic. `databaseendpoint` - (required) is the full path to the database, for example: `"grpcs://example.com:2135/?database=/Root/testdb0"`; analogous to `connectionstring` for tables. `retentionperiodms` - the duration of data storage in milliseconds; the default value is `86400000` (day). `partitions_count` - the number of partitions; the default value is `2`. `supported_codecs` - supported data compression codecs, the default value is `"gzip", "raw", "zstd"`. `consumer` - readers for the topic. Description of the data consumer `consumer`: `name` - (required) is the reader's name. `supported_codecs` - supported data compression encodings, by default - `"gzip", "raw", "zstd"`. `startingmessagetimestamp_ms` - timestamp in format in milliseconds, from which the reader will start reading the data; the default value is 0, which means "from the beginning".