You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# How to set up Azure CLI for migration service in Azure Database for PostgreSQL - Flexible Server
15
15
16
-
To begin migrating using Azure CLI, you need to install the Azure CLI on your local machine.
16
+
The Azure CLI is a set of commands used across Azure services to create and manage resources. It provides the same capabilities as the Azure portal but is optimized for users who prefer to work within a command-line environment. To begin migrating using Azure CLI, you need to install the Azure CLI on your local machine.
17
17
18
18
## Prerequisites
19
19
20
-
-[Choose the right command line tool](/CLI/azure/choose-the-right-azure-command-line-tool)
-[Review the az postgresql commands](/cli/azure/postgres)
20
+
-**Install Azure CLI**: Depending on your operating system, download and install the Azure CLI. It’s available for Windows, macOS, and Linux.
21
+
-**Azure CLI Installation Guide**: Follow the instructions provided in the official Azure documentation to install the Azure CLI - [How to install the Azure CLI](/cli/azure/install-azure-cli).
22
+
-**Check Azure CLI Version**: Ensure that your Azure CLI version is at least 2.56.0 or higher, as this is required for the migration service. Use the command `az --version` to check your current version.
23
+
-**Sign in to Azure**: After installation, execute `az login` to authenticate. This will open your default browser to complete the sign-in process with your Azure credentials.
23
24
24
-
## Migrate commands
25
+
These steps will prepare your environment for using the Azure CLI to manage the migration service in Azure Database for PostgreSQL effectively. Always refer to the latest Azure documentation for any updates or changes to the installation process.
25
26
26
-
Migrating with the Azure CLI uses the following commands:
All the CLI commands start with `az postgres flexible-server migration`. There are also help statements provided to assist you in understanding the various options and framing the correct syntax for the CLI commands.
31
30
32
-
The following table defines the parameters and the commands that use them:
31
+
Once the CLI is installed, open the command prompt and log into the Azure account using the below command.
33
32
34
-
| Parameter | Relevant commands | Description |
35
-
| --- | --- | --- |
36
-
|`subscription`| Create, List, Show | Subscription ID of PostgreSQL Flexible server |
37
-
|`resource-group`| Create, List, Show | Resource group of PostgreSQL Flexible server |
38
-
|`name`| Create, List, Show | Name of the PostgreSQL Flexible server |
39
-
|`migration-name`| Create, Show | Unique identifier to migrations attempted to Flexible Server. This field accepts only alphanumeric characters and doesn't accept any special characters except a hyphen (-). The name can't start with -, and no two migrations to a Flexible Server target can have the same name. |
40
-
| `filter` | List | To filter migrations, two values are supported – Active and All
41
-
|`help`| Create, List, Show | Provides information about each command. |
42
-
|`migration-mode`| Create | This is an optional parameter. Default value: Offline. Offline migration involves copying your source databases to your target server at a point in time. |
43
-
| `migration-option` | Create | Allows you to perform validations before triggering a migration. Default is ValidateAndMigrate. Allowed values are - Migrate, Validate, ValidateAndMigrate.
44
-
|`properties`| Create | Absolute path to a JSON file that has the information about the source server |
45
-
46
-
The **create** command requires a JSON file, which contains the following information:
33
+
```azurecli-interactive
34
+
`az login`
35
+
```
47
36
48
-
| Property Name | Description |
49
-
| --- | --- |
50
-
|`sourceDbServerResourceId`| Source server details in the format for on-premises, Azure virtual machines (VMs), AWS - `<<hostname or IP address>>:<<port>>@<<username>>`|
51
-
|`AdminCredentials`| This parameter lists passwords for admin users for both the source server and the target PostgreSQL flexible server. These passwords help to authenticate against the source and target servers |
52
-
|`targetServerUserName`| The default value is the admin user created during the creation of the flexible server, and the password provided is used for authentication against this user. If you aren't using the default user, this parameter is the user or role on the target server for migration. This user should be a member of azure_pg_admin, pg_read_all_settings, pg_read_all_stats, and pg_stat_scan_tables roles and should have the Create role, Create DB attributes |
53
-
|`dbsToMigrate`| Specify the list of databases that you want to migrate to Flexible Server. You can include a maximum of eight database names at a time. Providing the list of DBs in array format. |
54
-
|`OverwriteDBsInTarget`| When set to true (default), if the target server happens to have an existing database with the same name as the one you're trying to migrate, the migration tool automatically overwrites the database |
55
-
|`MigrationMode`| Mode of the migration. The supported value is "Offline" |
56
-
|`sourceType`| Required parameter. Values can be - on-premises, AWS, AzureVM, PostgreSQLSingleServer |
57
-
|`sslMode`| SSL modes for migration. SSL mode for PostgreSQLSingleServer is VerifyFull and Prefer/Require for other source types |
37
+
## Migrate commands
58
38
59
-
## Cutover the migration
39
+
The migration service provides the following commands to help you migrate your PostgreSQL instances to Azure Database for PostgreSQL - Flexible Server.
60
40
61
-
After the base data migration is complete, the migration task moves to the `WaitingForCutoverTrigger` substate. In this state, users can trigger the cutover from the portal by selecting the migration name in the migration grid or through the CLI using the command below.
41
+
### Help command
62
42
63
-
For example:
43
+
The `--help` command in Azure CLI is a valuable option that provides detailed documentation about the commands and their subcommands, including the required verbs for operations. The `–-help`command displays the necessary commands and their associated actions fpr migration service in Azure Database for PostgreSQL.
Before initiating cutover, it's important to ensure that:
49
+
The output will guide you through the necessary steps and parameters required to manage your database migrations effectively using the Azure CLI.
70
50
71
-
- Writes to the source are stopped
72
-
-`latency` value decreases to 0 or close to 0
73
-
-`latency` value indicates when the target last synced with the source. At this point, writes to the source can be stopped and cutover initiated. In case there's heavy traffic at the source, it's recommended to stop writes first so that `Latency` can come close to 0, and then a cutover is initiated.
74
-
- The Cutover operation applies all pending changes from the Source to the Target and completes the migration. If you trigger a "Cutover" even with nonzero `Latency`, the replication stops until that point in time. All the data on source until the cutover point is then applied on the target. Say a latency was 15 minutes at the cutover point, so all the changed data in the last 15 minutes applies to the target.
51
+
### Create command
75
52
76
-
Time depends on the backlog of changes occurring in the last 15 minutes. Hence, it's recommended that the latency go to zero or near zero before triggering the cutover.
53
+
The `az postgres flexible-server migration create` command in Azure CLI is used to initiate a new migration workflow. It facilitates the migration of databases from a source PostgreSQL instance to a target Azure Database for PostgreSQL - Flexible Server instance. This command sets up the necessary parameters and configurations to ensure a smooth and efficient migration process.
77
54
78
-
The `latency` information can be obtained using the migration show command.
79
-
Here's a snapshot of the migration before initiating the cutover:
55
+
For more information, refer to [az postgres flexible-server migration create](/cli/azure/postgres/flexible-server/migration#az-postgres-flexible-server-migration-create)
80
56
81
-
After the cutover is initiated, pending data captured during CDC is written to the target, and migration is now complete.
57
+
### List command
82
58
83
-
If the cutover isn't successful, the migration moves to the `Failed` state.
59
+
The `az postgres flexible-server migration list` command is used to list all the migration attempts made to an Azure Database for PostgreSQL target. This command provides an overview of the migrations that have been initiated, allowing you to track the status and details of each migration attempt.
84
60
85
-
For more information about this command, use the `help` parameter.
61
+
For more information, refer to [az postgres flexible-server migration list](/cli/azure/postgres/flexible-server/migration#az-postgres-flexible-server-migration-list)
86
62
87
-
##Cancel the migration
63
+
### Show command
88
64
89
-
To cancel the migration task, use the following command:
65
+
The `az postgres flexible-server migration show` command helps you monitor ongoing migrations and gives the current state and substate of the migration. These details include information on the current state and substate of the migration.
90
66
91
-
```azurecli
92
-
az postgres flexible-server migration update cancel [--subscription]
93
-
[--resource-group]
94
-
[--name]
95
-
[--migration-name]
96
-
```
67
+
For more information, refer to [az postgres flexible-server migration show](/cli/azure/postgres/flexible-server/migration#az-postgres-flexible-server-migration-show)
97
68
98
-
## The --help command
69
+
Some possible migration states:
99
70
100
-
For more information about this command, use the `help` parameter:
71
+
#### Migration states
101
72
102
-
```azurecli-interactive
103
-
az postgres flexible-server migration update cancel -- help
104
-
```
73
+
| State | Description |
74
+
| --- | --- |
75
+
|**InProgress**| The migration infrastructure setup is underway, or the actual data migration is in progress. |
76
+
|**Cancelled**| The migration is canceled or deleted. |
77
+
|**Failed**| The migration has failed. |
78
+
|**Validation Failed**| The validation has failed. |
79
+
|**Succeeded**| The migration has succeeded and is complete. |
80
+
|**WaitingForUserAction**| Applicable only for online migration. Waiting for user action to perform cutover. |
81
+
82
+
#### Migration substates
83
+
84
+
| Substate | Description |
85
+
| --- | --- |
86
+
|**PerformingPreRequisiteSteps**| Infrastructure setup is underway for data migration. |
87
+
|**Validation in Progress**| Validation is in progress. |
88
+
|**MigratingData**| Data migration is in progress. |
89
+
|**CompletingMigration**| Migration is in the final stages of completion. |
90
+
|**Completed**| Migration has been completed. |
91
+
|**Failed**| Migration has failed. |
92
+
93
+
#### Validation substates
94
+
95
+
| Substate | Description |
96
+
| --- | --- |
97
+
|**Failed**| Validation has failed. |
98
+
|**Succeeded**| Validation is successful. |
99
+
|**Warning**| Validation is in warning. |
100
+
101
+
### Update command
102
+
103
+
The `az postgres flexible-server migration update` command is used to manage the migration process to an Azure Database for PostgreSQL Flexible Server. Specifically, it can be used to:
104
+
105
+
-**Perform a cutover**: This finalizes the migration process by switching the database traffic from the source server to the target Flexible Server.
106
+
- After the base data migration is complete, the migration task moves to the `WaitingForCutoverTrigger` substate. In this state, users can trigger the cutover from the portal by selecting the migration name in the migration grid or through the CLI.
107
+
- Before initiating cutover, it's important to ensure that:
108
+
- Writes to the source are stopped
109
+
-`latency` value decreases to 0 or close to 0
110
+
-`latency` value indicates when the target last synced with the source. At this point, writes to the source can be stopped and cutover initiated. In case there's heavy traffic at the source, it's recommended to stop writes first so that `Latency` can come close to 0, and then a cutover is initiated.
111
+
- The Cutover operation applies all pending changes from the Source to the Target and completes the migration. If you trigger a "Cutover" even with nonzero `Latency`, the replication stops until that point in time. All the data on source until the cutover point is then applied on the target. Say a latency was 15 minutes at the cutover point, so all the changed data in the last 15 minutes applies to the target.
112
+
-**Cancel the migration**: If needed, this option allows you to stop the migration process.
113
+
-**Setup logical replication at the source**: This is particularly useful when the source server is an Azure Database for PostgreSQL - Single Server, as it prepares the server for data replication to the Flexible Server.
114
+
115
+
For more information, refer to [az postgres flexible-server migration update](/cli/azure/postgres/flexible-server/migration#az-postgres-flexible-server-migration-update)
116
+
117
+
## Summary
118
+
119
+
The following table summarizes the parameters used by the migration commands:
120
+
121
+
| Parameter | Relevant commands | Description |
122
+
| --- | --- | --- |
123
+
|`subscription`| create, list, show, update | Subscription ID of PostgreSQL Flexible server |
124
+
|`resource-group`| create, list, show, update | Resource group of PostgreSQL Flexible server |
125
+
|`name`| create, list, show | Name of the PostgreSQL Flexible server |
126
+
|`migration-name`| create, show, update | Unique identifier to migrations attempted to Flexible Server. This field accepts only alphanumeric characters and doesn't accept any special characters except a hyphen (-). The name can't start with -, and no two migrations to a Flexible Server target can have the same name. |
127
+
|`filter`| list | To filter migrations, two values are supported – Active and All |
128
+
|`help`| create, list, show, update | Provides information about each command. |
129
+
|`migration-mode`| create | This is an optional parameter. Allowed Values are - offline, online. Default value: Offline.|
130
+
| `migration-option` | create | Allows you to perform validations before triggering a migration. Default is ValidateAndMigrate. Allowed values are - Migrate, Validate, ValidateAndMigrate.
131
+
|`properties`| create | Absolute path to a JSON file that has the information about the source, target server, databases to migrate, SSL modes, defining source types |
132
+
133
+
### Details of the JSON file
134
+
135
+
The `az postgres flexible-server migration create` command requires a JSON file path as part of `--properties` parameter, which contains configuration details for the migration, such as the source database server resource ID, admin credentials, databases to migrate, and other important settings. Below are the different properties:
136
+
137
+
| Property Name | Description |
138
+
| --- | --- |
139
+
|`sourceDbServerResourceId`| Source server details in the format for on-premises, Azure virtual machines (VMs), AWS_RDS - `<<hostname or IP address>>:<<port>>@<<username>>`. If the source server is Azure Database for PostgreSQL - Single server then the resource ID is in the format - `/subscriptions/<<Subscription ID>>/resourceGroups/<<Resource Group Name>>/providers/Microsoft.DBforPostgreSQL/servers/<<PostgreSQL Single Server name>>`|
140
+
|`adminCredentials`| This parameter lists passwords for admin users for both the source server and the target PostgreSQL flexible server. These passwords help to authenticate against the source and target servers. It includes two sub-properties, `sourceServerPassword` and `targetServerPassword`|
141
+
|`targetServerUserName`| The default value is the admin user created during the creation of the PostgreSQL target flexible server, and the password provided is used for authentication against this user. |
142
+
|`dbsToMigrate`| Specify the list of databases that you want to migrate to Flexible Server. You can include a maximum of eight database names at a time. Providing the list of DBs in array format. |
143
+
|`overwriteDBsInTarget`| When set to true (default), if the target server happens to have an existing database with the same name as the one you're trying to migrate, the migration service automatically overwrites the database |
144
+
|`sourceType`| Required parameter. Values can be - OnPremises, AWS_RDS, AzureVM, PostgreSQLSingleServer |
145
+
|`sslMode`| SSL modes for migration. SSL mode for PostgreSQLSingleServer is VerifyFull and Prefer/Require for other source types. |
0 commit comments