Managing YDB databases
In Managed Service for YDB, you can create a database in two modes: serverless and dedicated, i.e., with dedicated servers.
You can use the management console or Yandex Cloud CLI to:
- Create and update parameters of a serverless database.
- Create and update parameters of a dedicated database.
- View a list of databases.
- Delete a database.
Creating and updating parameters of a serverless database
Creating a serverless database
-
In the management console
, select the folder to create your DB in. -
In the list of services, select Managed Service for YDB.
-
Click Create a database.
-
Enter the Name of the DB. The naming requirements are as follows:
- The name must be from 3 to 63 characters long.
- It may contain lowercase Latin letters, numbers, and hyphens.
- The first character must be a letter and the last character cannot be a hyphen.
-
Under Database type, select
Serverless
. -
You will be suggested default values for DB parameters. They are selected for you to get started in the most efficient way. You can change them right away or later, if required. For more information about the DB settings, see Serverless and dedicated modes.
-
Click Create a database.
Wait for the DB status to change to Running
.
If you do not have the Yandex Cloud command line interface yet, install and initialize it.
The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name
or --folder-id
parameter.
-
View a description of the Yandex Cloud CLI command to create a database:
yc ydb database create --help
-
Run this command:
yc ydb database create <DB_name> --serverless
Result:
id: etne027gi9aa******** folder_id: b1gmit33ngp3******** created_at: "2022-12-13T09:17:06Z" name: svlbd status: PROVISIONING endpoint: grpcs://ydb.serverless.yandexcloud.net:2135/?database=/ru-central1/b1gia87mbaom********/etne027gi9aa******** serverless_database: storage_size_limit: "53687091200" location_id: ru-central1 backup_config: backup_settings: - name: daily backup_schedule: daily_backup_schedule: execute_time: hours: 17 backup_time_to_live: 604800s type: SYSTEM document_api_endpoint: https://docapi.serverless.yandexcloud.net/ru-central1/b1gia87mbaom********/etne027gi9aa******** monitoring_config: {}
You can update any parameter later by running the update
Yandex Cloud CLI command or using the management console. For more information, see Serverless database parameters.
Every serverless database is created with geographic redundancy in three availability zones.
Terraform
For more information about the provider resources, see the documentation on the Terraform
If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.
If you don't have Terraform, install it and configure the Yandex Cloud provider.
-
In the Terraform configuration file, describe the parameters of the serverless DB to create:
resource "yandex_ydb_database_serverless" "database1" { name = "<DB_name>" deletion_protection = "<deletion_protection>" serverless_database { enable_throttling_rcu_limit = <throughput_limit> provisioned_rcu_limit = <throughput> storage_size_limit = <data_size> throttling_rcu_limit = <allocated_throughput> } }
Where:
name
: DB name. This is a required parameter.deletion_protection
: DB deletion protection,true
orfalse
. You cannot delete a DB with this option enabled. If deletion protection is activated, this does not protect the DB contents. The default value isfalse
.enable_throttling_rcu_limit
: Enable throughput limit,true
orfalse
. This is an optional parameter. The default value isfalse
.provisioned_rcu_limit
: Limit on request units consumed per second. This is an optional parameter. The default value is0
.storage_size_limit
: Data size limit in bytes. This is an optional parameter. The default value is50
GB.throttling_rcu_limit
: Shows the request unit usage per second charged on an hourly basis according to the service plan. If set to 0, hourly billing is disabled. This is an optional parameter. The default value is0
.
-
Apply the changes:
-
In the terminal, change to the folder where you edited the configuration file.
-
Make sure the configuration file is correct using the command:
terraform validate
If the configuration is correct, the following message is returned:
Success! The configuration is valid.
-
Run the command:
terraform plan
The terminal will display a list of resources with parameters. No changes are made at this step. If the configuration contains errors, Terraform will point them out.
-
Apply the configuration changes:
terraform apply
-
Confirm the changes: type
yes
in the terminal and press Enter.
-
Terraform will create all the required resources. You can check the update using the management console
yc ydb database get <DB_name>
Example
Creating a serverless DB protected against deletion, with the 10 RU/s throughput limit and 50 GB of data:
resource "yandex_ydb_database_serverless" "database1" { name = "test-ydb-serverless" deletion_protection = "true" serverless_database { enable_throttling_rcu_limit = false provisioned_rcu_limit = 10 storage_size_limit = 50 throttling_rcu_limit = 0 } }
To create a serverless database, use the create REST API method for the Database resource or the DatabaseService/Create gRPC API call and provide the following in the request:
- ID of the folder to host the database in the
folderId
parameter. - DB name in the
name
parameter. - DB throughput in the
serverlessDatabase.throttlingRcuLimit
parameter. - DB size (in bytes) in the
serverlessDatabase.storageSizeLimit
parameter.
Updating serverless database parameters
- In the management console
, select the folder you want to update DB settings in. - In the list of services, select Managed Service for YDB.
- Click
in the row with the DB you need and select Edit. - Configure the DB settings:
- Change the DB name, if required.
- Under Limits, specify throughput and data size.
- Under Pricing, set the provisioned throughput capacity.
- Click Update database.
If you do not have the Yandex Cloud command line interface yet, install and initialize it.
The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name
or --folder-id
parameter.
View a description of the Yandex Cloud CLI command to update a database:
yc ydb database update --help
Serverless DB parameter names start with sls-
. Other parameters are only applicable to dedicated DBs.
Examples
-
Renaming the
dbtest
database tomydb
:yc ydb database update dbtest \ --new-name mydb
-
Setting a consumption limit of 100 request units per second for a serverless DB named
db5
:yc ydb database update db5 \ --sls-throttling-rcu 100
If you don't have Terraform, install it and configure the Yandex Cloud provider.
-
Open the Terraform configuration file and edit the fragment with the serverless DB description:
resource "yandex_ydb_database_serverless" "database1" { name = "<DB_name>" deletion_protection = "<deletion_protection>" serverless_database { enable_throttling_rcu_limit = <throughput_limit> provisioned_rcu_limit = <throughput> storage_size_limit = <data_size> throttling_rcu_limit = <allocated_throughput> } }
Where:
name
: DB name. This is a required parameter.deletion_protection
: DB deletion protection,true
orfalse
. You cannot delete a DB with this option enabled. If deletion protection is activated, this does not protect the DB contents. The default value isfalse
.enable_throttling_rcu_limit
: Enable throughput limit,true
orfalse
. This is an optional parameter. The default value isfalse
.provisioned_rcu_limit
: Limit on request units consumed per second. This is an optional parameter. The default value is0
.storage_size_limit
: Amount of data, in GB. This is an optional parameter. The default value is50
.throttling_rcu_limit
: Shows the request unit usage per second charged on an hourly basis according to the service plan. If set to 0, hourly billing is disabled. This is an optional parameter. The default value is0
.
-
Apply the changes:
-
In the terminal, change to the folder where you edited the configuration file.
-
Make sure the configuration file is correct using the command:
terraform validate
If the configuration is correct, the following message is returned:
Success! The configuration is valid.
-
Run the command:
terraform plan
The terminal will display a list of resources with parameters. No changes are made at this step. If the configuration contains errors, Terraform will point them out.
-
Apply the configuration changes:
terraform apply
-
Confirm the changes: type
yes
in the terminal and press Enter.
-
Terraform will apply the required changes to the resources. You can check the update using the management console
yc ydb database get <DB_name>
Example
Changing the provisioned throughput capacity and amount of data for the test-ydb-serverless
DB:
resource "yandex_ydb_database_serverless" "database1" { name = "test-ydb-serverless" deletion_protection = "true" serverless_database { enable_throttling_rcu_limit = false provisioned_rcu_limit = 10 storage_size_limit = 80 throttling_rcu_limit = 100 } }
To change the serverless database parameters, use the update REST API method for the Database resource or the DatabaseService/Update gRPC API call and specify the database ID in the databaseId
request parameter.
You can get the database ID with a list of databases.
Provide the following in the request:
- ID of the folder to host the database in the
folderId
parameter. - DB name in the
name
parameter. - DB throughput in the
serverlessDatabase.throttlingRcuLimit
parameter. - DB size (in bytes) in the
serverlessDatabase.storageSizeLimit
parameter. - Computing resource ID in the
resourcePresetId
parameter. - Network ID in the
networkId
parameter. - Media type in the
storageConfig.storageOptions.storageTypeId
parameter. - Number of storage groups in the
storageConfig.storageOptions.groupCount
parameter. - Number of database instances in the
scalePolicy.fixedScale.size
parameter.
Creating and updating parameters of a dedicated database
Creating a dedicated database
-
In the management console
, select the folder to create your DB in. -
In the list of services, select Managed Service for YDB.
-
Click Create a database.
-
Enter the database Name. The naming requirements are as follows:
- The name must be from 3 to 63 characters long.
- It may contain lowercase Latin letters, numbers, and hyphens.
- The first character must be a letter and the last character cannot be a hyphen.
-
Under Database type, select
Dedicated
. -
Under Computing resources, select the type and amount of computing resources.
Warning
For reliable and stable performance, a database needs multiple slots. A database run in the production environment must have at least three slots.
-
Under Storage groups, select the disk type and number of storage groups that determines the total amount of storage.
-
Under Network, configure network settings:
-
(Optional) In the Public IP addresses field, select Assign if you plan to query the database from the Yandex Cloud network and the internet.
Warning
For Managed Service for YDB databases with external IPs, the usage of outgoing internet traffic is counted by the current pricing policy.
The charges for outgoing internet traffic generated by Managed Service for YDB usage will be offset by grants.
-
Select an existing network from the Cloud network list or create a new one:
- Click Create new.
- In the window that opens, enter a Name for the new network.
- (Optional) Select the Create subnets option. Subnets in each availability zone will be created automatically.
- Click Create network.
-
Under Subnets, select a subnet or create a new one for each availability zone:
- Click Create new.
- In the window that opens, enter a Name for the new subnet.
- (Optional) Enter a Description of the subnet.
- Select the availability zone you need from the Zone list.
- Set the subnet address in CIDR
format. - Click Create subnet.
-
-
Click Create a database.
Wait for the DB status to change to Running
.
If you do not have the Yandex Cloud command line interface yet, install and initialize it.
The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name
or --folder-id
parameter.
-
View a description of the Yandex Cloud CLI command to create a database:
yc ydb database create --help
-
Run this command:
yc ydb database create <DB_name> \ --dedicated \ --network-name <network_name> \ --storage <media_type>,<number_of_storage_groups> \ --resource-preset <computing_resource_configuration> \
Where:
--dedicated
: Configuration of the DB with dedicated servers.--network-name
: Name of the cloud network to create the DB in. You can specify the network asdefault
.--storage
: Media type and number of storage groups, intype=<media_type>,groups=<number_of_storage_groups>
format. For thessd
type, a single storage group can store up to 100 GB of data.--resource-preset
: Configuration of the node computing resources. You can find the possible values in the Configuration name column of the table in Database on dedicated resources.
Important additional parameters:
--public-ip
: Public IP address assignment flag. Without it, you cannot connect to the DB you created, from the internet.--fixed-size INT
: Number of cluster nodes, default is1
. Nodes are allocated in different availability zones, so a configuration of three nodes will be geographically distributed across three availability zones.--async
: Asynchronous DB creation flag. Creating a dedicated DB may take a long time, up to a few minutes. You can set this flag to recover control as soon as the command to create DB is accepted by the cloud.
Examples
-
Creating a single-node dedicated YDB database with the minimum configuration, named
dedb
and accessible from the internet:yc ydb database create dedb \ --dedicated \ --network-name default \ --storage type=ssd,groups=1 \ --resource-preset medium \ --public-ip
-
Asynchronously creating a three-node dedicated YDB database with geographic redundancy, 300 GB of storage, and computing nodes with 64 GB RAM each, named
dedb3
and accessible from the internet:yc ydb database create dedb3 \ --dedicated --network-name default \ --storage type=ssd,groups=3 \ --resource-preset medium-m64 \ --public-ip \ --fixed-size 3 \ --async
If you don't have Terraform, install it and configure the Yandex Cloud provider.
-
In the Terraform configuration file, describe the parameters of the Dedicated DB to create:
resource "yandex_ydb_database_dedicated" "database1" { name = "<DB_name>" network_id = "<network_ID>" subnet_ids = ["<subnet_1_ID>", "<subnet_2_ID>", "<subnet_3_ID>"] resource_preset_id = "<computing_resource_configuration>" deletion_protection = "<deletion_protection>" scale_policy { fixed_scale { size = <number_of_DB_instances> } } storage_config { group_count = <number_of_storage_groups> storage_type_id = "<media_type>" } }
Where:
name
: DB name.network_id
: ID of the network the DB is connected to.subnet_ids
: List of subnet IDs, separated by commas.resource_preset_id
: Configuration of the node computing resources. You can find the possible values in the Configuration name column of the table in Database on dedicated resources.deletion_protection
: DB deletion protection,true
orfalse
. You cannot delete a DB with this option enabled. If deletion protection is activated, this does not protect the DB contents. The default value isfalse
.scale_policy
: Scaling policy, wheresize
indicates the number of DB instances.storage_config
: Storage configuration, where:group_count
: Number of storage groups.storage_type_id
: Media type. For thessd
type, a single storage group can store up to 100 GB of data.
-
Create a database:
-
In the terminal, change to the folder where you edited the configuration file.
-
Make sure the configuration file is correct using the command:
terraform validate
If the configuration is correct, the following message is returned:
Success! The configuration is valid.
-
Run the command:
terraform plan
The terminal will display a list of resources with parameters. No changes are made at this step. If the configuration contains errors, Terraform will point them out.
-
Apply the configuration changes:
terraform apply
-
Confirm the changes: type
yes
in the terminal and press Enter.
-
Terraform will create all the required resources. You can check the update using the management console
yc ydb database list
Example
Creating a single-node dedicated Managed Service for YDB database with the minimum configuration, named test-bd
and accessible from the internet:
resource "yandex_ydb_database_dedicated" "database2" { name = "test-ydb-dedicated" network_id = yandex_vpc_network.my-net.id subnet_ids = [yandex_vpc_subnet.my-subnet-a.id, yandex_vpc_subnet.my-subnet-b.id, yandex_vpc_subnet.my-subnet-d.id] resource_preset_id = "medium" deletion_protection = "true" scale_policy { fixed_scale { size = 1 } } storage_config { group_count = 1 storage_type_id = "ssd" } }
To create a dedicated database, use the create REST API method for the Database resource or the DatabaseService/Create gRPC API call and provide the following in the request:
- ID of the folder to host the database in the
folderId
parameter. - DB name in the
name
parameter. - Permission to assign public IP addresses to DB nodes in the
dedicatedDatabase.assignPublicIps
parameter. - Computing resource ID in the
resourcePresetId
parameter. - Network ID in the
networkId
parameter. - Media type in the
storageConfig.storageOptions.storageTypeId
parameter. - Number of storage groups in the
storageConfig.storageOptions.groupCount
parameter. - Number of database instances in the
scalePolicy.fixedScale.size
parameter.
Updating dedicated database parameters
- In the management console
, select the folder you want to update DB settings in. - In the list of services, select Managed Service for YDB.
- Click
in the row with the DB you need and select Edit. - Configure the DB settings:
- Change the DB name, if required.
- Under Computing resources, select the type and amount of computing resources.
- Under Storage groups, select the disk type and number of storage groups that determines the total amount of storage.
- Click Update database.
If you do not have the Yandex Cloud command line interface yet, install and initialize it.
The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name
or --folder-id
parameter.
View a description of the Yandex Cloud CLI command to update a database:
yc ydb database update --help
Dedicated DB parameters have no sls-
prefix.
Example
Changing the number of storage groups for a DB with the SSD storage type and a single storage group:
yc ydb database update test-db \ --storage type=ssd,group=2
You cannot decrease the number of storage groups.
If you don't have Terraform, install it and configure the Yandex Cloud provider.
-
Open the Terraform configuration file and edit the fragment with the DB description:
resource "yandex_ydb_database_dedicated" "database2" { name = "my-first-ydb-dedicated" network_id = yandex_vpc_network.my-net.id subnet_ids = [yandex_vpc_subnet.my-subnet-a.id, yandex_vpc_subnet.my-subnet-b.id, yandex_vpc_subnet.my-subnet-d.id] resource_preset_id = "medium" deletion_protection = "true" scale_policy { fixed_scale { size = 2 } } storage_config { group_count = 1 storage_type_id = "ssd" } }
-
Apply the changes:
-
In the terminal, change to the folder where you edited the configuration file.
-
Make sure the configuration file is correct using the command:
terraform validate
If the configuration is correct, the following message is returned:
Success! The configuration is valid.
-
Run the command:
terraform plan
The terminal will display a list of resources with parameters. No changes are made at this step. If the configuration contains errors, Terraform will point them out.
-
Apply the configuration changes:
terraform apply
-
Confirm the changes: type
yes
in the terminal and press Enter.
-
You can check the update using the management console
yc ydb database get <DB_name>
To change the dedicated database parameters, use the update REST API method for the Database resource or the DatabaseService/Update gRPC API call and specify the database ID in the databaseId
request parameter.
You can get the database ID with a list of databases.
In the request, provide a set of parameters used to create the dedicated database with your updated values.
To move a database to a different availability zone, follow this guide.
Viewing the list of databases
- In the management console
, select the folder to get a list of databases for. - In the list of services, select Managed Service for YDB.
If you do not have the Yandex Cloud command line interface yet, install and initialize it.
The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name
or --folder-id
parameter.
Run this command:
yc ydb database list
To get a list of databases in the folder, use the list REST API method for the Database resource or the DatabaseService/List gRPC API call and provide the folder ID in the folderId
request parameter.
Assigning a role for a database
You can grant access to a Managed Service for YDB database to a user, service account, or user group. To do this, assign a role for the database. To choose the one you need, learn about the service's roles.
- In the management console
, select the folder the DB resides in. - In the list of services, select Managed Service for YDB.
- Click the name of the database.
- Go to
Access bindings and click Assign bindings. - Select the group, user, or service account you want to grant access to the database.
- Click
Add role and select the required roles. - Click Save.
If you do not have the Yandex Cloud command line interface yet, install and initialize it.
The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name
or --folder-id
parameter.
To assign a role for a database:
-
See the description of the CLI role assignment command:
yc ydb database add-access-binding --help
-
Get a list of databases with their IDs:
yc ydb database list
-
Get the ID of the user, service account, or user group you are assigning a role to.
-
Use one of these commands to assign a role:
-
To a user:
yc ydb database add-access-binding \ --id <DB_ID> \ --role <role> \ --user-account-id <user_ID>
-
To a federated user:
yc ydb database add-access-binding \ --id <DB_ID> \ --role <role> \ --user-account-id <user_ID>
-
To a service account:
yc ydb database add-access-binding \ --id <DB_ID> \ --role <role> \ --service-account-id <service_account_ID>
-
To a user group:
yc ydb database add-access-binding \ --id <DB_ID> \ --role <role> \ --subject group:<group_ID>
-
Use the DatabaseService/UpdateAccessBindings gRPC API call and provide the following in the request:
ADD
value in theaccess_binding_deltas[].action
parameter to add a role.- Role in the
access_binding_deltas[].access_binding.role_id
parameter. - ID of the subject you are assigning the role to in the
access_binding_deltas[].access_binding.subject.id
parameter. - Type of the subject you are assigning the role to in the
access_binding_deltas[].access_binding.subject.type
parameter.
Assigning multiple roles for a database
- In the management console
, select the folder the DB resides in. - In the list of services, select Managed Service for YDB.
- Click the name of the database.
- Go to
Access bindings and click Assign bindings. - Select the group, user, or service account you want to grant access to the database.
- Click
Add role and select the required roles. - Click Save.
Alert
The set-access-bindings
command for assigning multiple roles completely rewrites access permissions for the resource. All current resource roles will be deleted.
If you do not have the Yandex Cloud command line interface yet, install and initialize it.
The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name
or --folder-id
parameter.
To assign multiple roles for a database:
-
Make sure the database has no roles assigned that you would not want to lose:
yc ydb database list-access-bindings \ --id <DB_ID>
-
See the description of the CLI role assignment command:
yc ydb database set-access-bindings --help
-
Get a list of databases with their IDs:
yc ydb database list
-
Get the ID of the user, service account, or user group you are assigning roles to.
-
Use one of the commands below to assign roles:
-
To a Yandex account user:
yc ydb database set-access-bindings \ --id <DB_ID> \ --access-binding role=<role>,user-account-id=<user_ID>
-
To a federated user:
yc ydb database set-access-bindings \ --id <DB_ID> \ --access-binding role=<role>,subject=federatedUser:<user_ID>
-
To a service account:
yc ydb database set-access-bindings \ --id <DB_ID> \ --access-binding role=<role>,service-account-id=<service_account_ID>
-
To a user group:
yc ydb database set-access-bindings \ --id <DB_ID> \ --access-binding role=<role>,subject=group:<group_ID>
Provide a separate
--access-binding
flag for each role. Example:yc ydb database set-access-bindings \ --id <DB_ID> \ --access-binding role=<role_1>,service-account-id=<service_account_ID> \ --access-binding role=<role_2>,service-account-id=<service_account_ID> \ --access-binding role=<role_3>,service-account-id=<service_account_ID>
-
Alert
The setAccessBindings
method for assigning multiple roles completely rewrites access permissions for the resource. All current resource roles will be deleted.
Use the DatabaseService/SetAccessBindings gRPC API call. In your request, provide an array of objects, each one corresponding to a particular role and containing the following data:
- Role in the
access_bindings[].role_id
parameter. - ID of the subject getting the roles in the
access_bindings[].subject.id
parameter. - Type of the subject getting the roles in the
access_bindings[].subject.type
parameter.
Deleting a database
- In the management console
, select the folder to delete the DB from. - In the list of services, select Managed Service for YDB.
- Click
in the row with the DB you need and select Delete. - Confirm the deletion.
If you do not have the Yandex Cloud command line interface yet, install and initialize it.
The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name
or --folder-id
parameter.
Run this command:
yc ydb database delete <DB_name>
If you don't have Terraform, install it and configure the Yandex Cloud provider.
-
Open the Terraform configuration file and delete the fragment with the DB description.
Sample DB description in the Terraform configuration:
resource "yandex_ydb_database_dedicated" "database2" { name = "test-ydb-dedicated" network_id = yandex_vpc_network.my-net.id subnet_ids = [yandex_vpc_subnet.my-subnet-a.id, yandex_vpc_subnet.my-subnet-b.id, yandex_vpc_subnet.my-subnet-d.id] resource_preset_id = "medium" scale_policy { fixed_scale { size = 1 } } storage_config { group_count = 1 storage_type_id = "ssd" } }
-
Apply the changes:
-
In the terminal, change to the folder where you edited the configuration file.
-
Make sure the configuration file is correct using the command:
terraform validate
If the configuration is correct, the following message is returned:
Success! The configuration is valid.
-
Run the command:
terraform plan
The terminal will display a list of resources with parameters. No changes are made at this step. If the configuration contains errors, Terraform will point them out.
-
Apply the configuration changes:
terraform apply
-
Confirm the changes: type
yes
in the terminal and press Enter.
-
Terraform will delete all the resources as appropriate. You can check the update using the management console
yc ydb database list
To delete the database, use the delete REST API method for the Database resource or the DatabaseService/Delete gRPC API call and specify the deleted database ID in the databaseId
request parameter.
You can get the database ID with a list of databases.