> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Phased Bulk Load Migration from PostgreSQL
export const InternalLink = ({version, path = "", children, ...props}) => {
let detectedVersion = version || "stable";
if (typeof window !== 'undefined' && !version) {
const match = window.location.pathname.match(/\/docs\/([^/]+)/);
if (match) {
detectedVersion = match[1];
}
}
const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
return
{children}
;
};
A *Phased Bulk Load Migration* involves migrating data to CockroachDB in several phases. Data can be sliced per tenant, per service, per region, or per table to suit the needs of the migration. In this approach, you stop application traffic to the source database *only* for the tables in a particular slice of data. You then migrate that phase of data to the target cluster using MOLT Fetch during a **downtime window**. Application traffic is then cut over to those target tables after schema finalization and data verification. This process is repeated for each phase of data.
* Data is migrated to the target in phases.
* This approach does not utilize continuous replication.
* Rollback is manual. If you wish to roll back before the target has received any writes that are not present on the source database, nothing needs to be done. If you wish to roll back after the target has received writes that are not present on the source database, you must manually replicate these new rows on the source.
This approach is comparable to the Classic Bulk Load Migration, but dividing the data into multiple phases allows each downtime window to be shorter, and it allows each phase of the migration to be less complex. Depending on how you divide the data, it also may allow your downtime windows to affect only a subset of users. For example, dividing the data per region could mean that, when migrating the data from Region A, application usage in Region B may remain unaffected. This approach may increase overall migration complexity: its duration is longer, you will need to do the work of partitioning the data, and you will have a longer period when you run both the source and the target database concurrently.
This approach is best for databases that are too large to migrate all at once, internal tools, dev/staging environments, and production environments that can handle business disruption. It can only be performed if your system can handle downtime for each migration phase, and if your source database can easily be divided into the phases you need.
This page describes an example scenario. While the commands provided can be copy-and-pasted, they may need to be altered or reconsidered to suit the needs of your specific environment.
## Example scenario
You have a moderately-sized (500GB) database that provides the data store for a web application. You want to migrate the entirety of this database to a new CockroachDB cluster. You will divide this migration into four geographic regions (A, B, C, and D). You schedule a maintenance window for each region over four subsequent evenings, and you announce them to your users (per region) several weeks in advance.
The application runs on a Kubernetes cluster with an NGINX Ingress Controller.
**Estimated system downtime:** 4 hours per region.
## Before the migration
* Install the MOLT (Migrate Off Legacy Technology) tools.
* Review the MOLT Fetch documentation.
* Develop a migration plan and prepare for the migration.
* **Recommended:** Perform a dry run of this full set of instructions in a development environment that closely resembles your production environment. This can help you get a realistic sense of the time and complexity it requires.
* Announce the maintenance window to your users on a per-region basis.
* Understand the prerequisites and limitations of the MOLT tools:
### Limitations
#### MOLT Fetch limitations
* Only tables with primary key types of `INT`, `FLOAT`, or `UUID` can be sharded with `--export-concurrency`.
* `GEOMETRY` and `GEOGRAPHY` types are not supported.
* `OID LOB` types in PostgreSQL are not supported, although similar types like `BYTEA` are supported.
#### MOLT Verify limitations
* MOLT Verify compares 20,000 rows at a time by default, and row values can change between batches, potentially resulting in temporary inconsistencies in data. To configure the row batch size, use the `--row_batch_size` flag.
* MOLT Verify checks for collation mismatches on primary key columns. This may cause validation to fail when a `STRING` is used as a primary key and the source and target databases are using different collations.
* MOLT Verify might give an error in case of schema changes on either the source or target database.
* Geospatial types cannot yet be compared.
## Step 1: Prepare the source database
In this step, you will:
* [Create a dedicated migration user on your source database](#create-migration-user-on-source-database).
### Create migration user on source database
Create a dedicated migration user (for example, `MIGRATION_USER`) on the source database. This user is responsible for reading data from source tables during the migration. You will pass this username in the [source connection string](#source-connection-string).
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
CREATE USER migration_user WITH PASSWORD 'password';
```
Grant the user privileges to connect, view schema objects, and select the tables you migrate.
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
GRANT CONNECT ON DATABASE migration_db TO migration_user;
GRANT USAGE ON SCHEMA migration_schema TO migration_user;
GRANT SELECT ON ALL TABLES IN SCHEMA migration_schema TO migration_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA migration_schema GRANT SELECT ON TABLES TO migration_user;
```
## Step 2: Prepare the target database
In this step, you will:
* [Provision and run a new CockroachDB cluster](#provision-a-cockroachdb-cluster).
* [Define the tables on the target cluster](#define-the-target-tables) to match those on the source.
* [Create a SQL user on the target cluster](#create-the-sql-user) with the necessary write permissions.
### Provision a CockroachDB cluster
Use one of the following options to create and run a new CockroachDB cluster. This is your migration **target**.
#### Option 1: Create a secure cluster locally
If you have the CockroachDB binary installed locally, you can manually deploy a multi-node, self-hosted CockroachDB cluster on your local machine.
Learn how to deploy a CockroachDB cluster locally.
#### Option 2: Create a CockroachDB Self-Hosted cluster on AWS
You can manually deploy a multi-node, self-hosted CockroachDB cluster on Amazon's AWS EC2 platform, using AWS's managed load-balancing service to distribute client traffic.
Learn how to deploy a CockroachDB cluster on AWS.
#### Option 3: Create a CockroachDB Cloud cluster
CockroachDB Cloud is a fully-managed service run by Cockroach Labs, which simplifies the deployment and management of CockroachDB.
[Sign up for a CockroachDB Cloud account](https://cockroachlabs.cloud) and create a cluster using trial credits.
### Define the target tables
Convert the source table definitions into CockroachDB-compatible equivalents. CockroachDB supports the PostgreSQL wire protocol and is largely compatible with PostgreSQL syntax.
* The source and target table definitions must **match**. Review Type mapping to understand which source types can be mapped to CockroachDB types.
For example, a PostgreSQL source table defined as `CREATE TABLE migration_schema.tbl (pk INT PRIMARY KEY);` must have a corresponding schema and table in CockroachDB:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
CREATE SCHEMA migration_schema;
CREATE TABLE migration_schema.tbl (pk INT PRIMARY KEY);
```
* MOLT Fetch can automatically define matching CockroachDB tables using the `drop-on-target-and-recreate` option.
* If you define the target tables manually, review how MOLT Fetch handles type mismatches. You can use the [MOLT Schema Conversion Tool](#schema-conversion-tool) to create matching table definitions.
* Every table **must** have an explicit primary key.
Avoid using sequential keys. To learn more about the performance issues that can result from their use, refer to the guidance on indexing with sequential keys. If a sequential key is necessary in your CockroachDB table, you must create it manually, after using MOLT Fetch to load and replicate the data.
* Review Transformations to understand how computed columns and partitioned tables can be mapped to the target, and how target tables can be renamed.
* By default on CockroachDB, `INT` is an alias for `INT8`, which creates 64-bit signed integers. PostgreSQL and MySQL default to 32-bit integers. Depending on your source database or application requirements, you may need to change the integer size to `4`. For more information, refer to Considerations for 64-bit signed integers.
#### Schema Conversion Tool
The MOLT Schema Conversion Tool (SCT) converts source table definitions to CockroachDB-compatible syntax. It requires a free CockroachDB Cloud account.
1. Upload a source `.sql` file to convert the syntax and identify unimplemented features and syntax incompatibilities in the table definitions.
2. Import the converted table definitions to a CockroachDB cluster:
* When migrating to CockroachDB Cloud, the Schema Conversion Tool automatically applies the converted table definitions to a new Cloud database.
* When migrating to a self-hosted CockroachDB cluster, export a converted DDL file and pipe the data definition language (DDL) directly into `cockroach sql`.
#### Drop constraints and indexes
To optimize data load performance, drop all non-`PRIMARY KEY` constraints and indexes on the target CockroachDB database before migrating:
* `FOREIGN KEY`
* `UNIQUE`
* Secondary indexes
* `CHECK`
* `DEFAULT`
* `NOT NULL` (you do not need to drop this constraint when using `drop-on-target-and-recreate` for [table handling](#table-handling-mode))
Do **not** drop `PRIMARY KEY` constraints.
You can [recreate the constraints and indexes after loading the data](#add-constraints-and-indexes).
### Create the SQL user
Create a SQL user in the CockroachDB cluster that has the necessary privileges.
To create a user `crdb_user` in the default database (you will pass this username in the [target connection string](#target-connection-string)):
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
CREATE USER crdb_user WITH PASSWORD 'password';
```
Grant database-level privileges for schema creation within the target database:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
GRANT ALL ON DATABASE defaultdb TO crdb_user;
```
Grant permission to modify cluster settings:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
GRANT SYSTEM MODIFYCLUSTERSETTING TO crdb_user;
```
Grant usage on schemas being migrated:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
GRANT USAGE ON SCHEMA migration_schema TO crdb_user;
GRANT USAGE ON SCHEMA public TO crdb_user;
```
Grant user privileges to create tables in the `migration_schema` schema and internal MOLT tables like `_molt_fetch_exceptions` in the `public` CockroachDB schema:
Ensure that you are connected to the target database.
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
GRANT CREATE ON SCHEMA migration_schema TO crdb_user;
GRANT CREATE ON SCHEMA public TO crdb_user;
```
If you manually defined the target tables (which means that [`drop-on-target-and-recreate`](#table-handling-mode) will not be used), grant the following privileges on the schema:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA migration_schema TO crdb_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA migration_schema
GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO crdb_user;
```
Grant the same privileges for internal MOLT tables in the `public` CockroachDB schema:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO crdb_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO crdb_user;
```
If you will be running Fetch with [`drop-on-target-and-recreate`](#table-handling-mode), and the target schema has pre-existing tables that were created by a different user, you may need to change table ownership to allow the migration user to drop those tables. Make the following alteration for each table:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ALTER TABLE migration_schema.table1 OWNER TO crdb_user;
```
Depending on the MOLT Fetch data load mode you will use, grant the necessary privileges to run either [`IMPORT INTO`](#import-into-privileges) or [`COPY FROM`](#copy-from-privileges) on the target tables:
#### `IMPORT INTO` privileges
Grant `SELECT`, `INSERT`, and `DROP` (required because the table is taken offline during the `IMPORT INTO`) privileges on all tables being migrated:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
GRANT SELECT, INSERT, DROP ON ALL TABLES IN SCHEMA migration_schema TO crdb_user;
```
If you plan to use [cloud storage with implicit authentication](#cloud-storage-authentication) for data load, grant the `EXTERNALIOIMPLICITACCESS` system-level privilege:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
GRANT SYSTEM EXTERNALIOIMPLICITACCESS TO crdb_user;
```
#### `COPY FROM` privileges
Grant `admin` privileges to the user:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
GRANT admin TO crdb_user;
```
#### Set session variable
Ensure that the `statement_timeout` session variable is set to `0s` for the user:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ALTER ROLE crdb_user SET statement_timeout = '0s';
```
## Migrate each phase
Steps 3-7 are run for each phase of the data migration. Within the first migration downtime window, you will run through these steps for Region A. You will repeat these steps for the other regions during each subsequent downtime window.
## Step 3: Stop application traffic
With both the source and target databases prepared for the data load, it's time to stop application traffic to the source for a particular region.
If the Kubernetes cluster that deploys the application has pre-region deployments (for example, `app-us`, `app-eu`, `app-apac`), you can scale down only the deployment for that region.
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
kubectl scale deploy/app-eu --replicas=0
```
Or this can be handled by the NGINX Ingress Controller, by including the following to your NGINX configuration, ensuring that the conditional statement is suitable for your deployment:
```yml theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: app
annotations:
nginx.ingress.kubernetes.io/server-snippet: |
if ($http_x_region = "eu") {
return 503;
}
spec:
ingressClassName: nginx
rules:
- host: api.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: app
port:
number: 80
```
Application downtime begins now, for users in the given region.
It is strongly recommended that you perform a dry run of this migration in a test environment. This will allow you to practice using the MOLT tools in real time, and it will give you an accurate sense of how long application downtime might last.
## Step 4: Load data into CockroachDB
In this step, you will:
* [Configure MOLT Fetch with the flags needed for your migration](#configure-molt-fetch).
* [Run MOLT Fetch](#run-molt-fetch).
* [Understand how to continue a load after an interruption](#continue-molt-fetch-after-an-interruption).
### Configure MOLT Fetch
The MOLT Fetch documentation includes detailed information about how to configure MOLT Fetch, and how to monitor MOLT Fetch metrics.
When you run `molt fetch`, you can configure the following options for data load:
* Specify source and target databases: Specify URL‑encoded source and target connections.
* Select data to migrate: Specify schema and table names to migrate. **Important for a phased migration.**
* Define intermediate file storage: Export data to cloud storage or a local file server.
* Define fetch mode: Specifies whether data will only be loaded into/from intermediate storage.
* Shard tables: Divide larger tables into multiple shards during data export.
* Data load mode: Choose between `IMPORT INTO` and `COPY FROM`.
* Table handling mode: Determine how existing target tables are initialized before load.
* Define data transformations: Define any row-level transformations to apply to the data before it reaches the target.
* Monitor fetch metrics: Configure metrics collection during initial data load.
Read through the documentation to understand how to configure your `molt fetch` command and its flags. Follow best practices, especially those related to security.
At minimum, the `molt fetch` command should include the source, target, data path, and `--ignore-replication-check` flags. For a phased migration, you may also choose to include `--schema-filter` or `--table-filter` flags:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
molt fetch \
--source $SOURCE \
--target $TARGET \
--table-filter '.*user.*' \
--bucket-path 's3://bucket/path' \
--ignore-replication-check
```
However, depending on the needs of your migration, you may have many more flags set, and you may need to prepare some accompanying .json files.
### Run MOLT Fetch
Perform the bulk load of the source data.
1. Run the MOLT Fetch command to move the source data into CockroachDB. This example command passes the source and target connection strings [as environment variables](#secure-connections), writes [intermediate files](#intermediate-file-storage) to S3 storage, and uses the `truncate-if-exists` [table handling mode](#table-handling-mode) to truncate the target tables before loading data. It limits the migration to a single schema and filters for three specific tables. The data load mode defaults to `IMPORT INTO`. Include the `--ignore-replication-check` flag to skip replication checkpoint queries, which eliminates the need to configure the source database for logical replication.
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
molt fetch \
--source $SOURCE \
--target $TARGET \
--schema-filter 'migration_schema' \
--table-filter 'employees|payments|orders' \
--bucket-path 's3://migration/data/cockroach' \
--table-handling truncate-if-exists \
--ignore-replication-check
```
2. Check the output to observe `fetch` progress.
A `starting fetch` message indicates that the task has started:
```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{"level":"info","type":"summary","num_tables":3,"cdc_cursor":"0/43A1960","time":"2025-02-10T14:28:11-05:00","message":"starting fetch"}
```
`data extraction` messages are written for each table that is exported to the location in `--bucket-path`:
```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{"level":"info","table":"migration_schema.employees","time":"2025-02-10T14:28:11-05:00","message":"data extraction phase starting"}
```
```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{"level":"info","table":"migration_schema.employees","type":"summary","num_rows":200000,"export_duration_ms":1000,"export_duration":"000h 00m 01s","time":"2025-02-10T14:28:12-05:00","message":"data extraction from source complete"}
```
`data import` messages are written for each table that is loaded into CockroachDB:
```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{"level":"info","table":"migration_schema.employees","time":"2025-02-10T14:28:12-05:00","message":"starting data import on target"}
```
```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{"level":"info","table":"migration_schema.employees","type":"summary","net_duration_ms":1899.748333,"net_duration":"000h 00m 01s","import_duration_ms":1160.523875,"import_duration":"000h 00m 01s","export_duration_ms":1000,"export_duration":"000h 00m 01s","num_rows":200000,"cdc_cursor":"0/43A1960","time":"2025-02-10T14:28:13-05:00","message":"data import on target for table complete"}
```
A `fetch complete` message is written when the fetch task succeeds:
```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{"level":"info","type":"summary","fetch_id":"f5cb422f-4bb4-4bbd-b2ae-08c4d00d1e7c","num_tables":3,"tables":["migration_schema.employees","migration_schema.payments","migration_schema.payments"],"skipped_unmigratable_tables":[],"cdc_cursor":"0/3F41E40","net_duration_ms":6752.847625,"net_duration":"000h 00m 06s","time":"2024-03-18T12:30:37-04:00","message":"fetch complete"}
```
### Continue MOLT Fetch after an interruption
If MOLT Fetch fails while loading data into CockroachDB from intermediate files, it exits with an error message, fetch ID, and *continuation token* for each table that failed to load on the target database.
```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{"level":"info","table":"public.employees","file_name":"shard_01_part_00000001.csv.gz","message":"creating or updating token for duplicate key value violates unique constraint \"employees_pkey\"; Key (id)=(1) already exists."}
{"level":"info","table":"public.employees","continuation_token":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","message":"created continuation token"}
{"level":"info","fetch_id":"f5cb422f-4bb4-4bbd-b2ae-08c4d00d1e7c","message":"continue from this fetch ID"}
{"level":"error","message":"Error: error from fetching table for public.employees: error importing data: duplicate key value violates unique
constraint \"employees_pkey\" (SQLSTATE 23505)"}
```
You can use this information to continue the task from the *continuation point* where it was interrupted.
Continuation is only possible under the following conditions:
* All data has been exported from the source database into intermediate files on cloud or local storage.
* The *initial load* of source data into the target CockroachDB database is incomplete.
* The load uses [`IMPORT INTO` rather than `COPY FROM`](#data-load-mode).
Only one fetch ID and set of continuation tokens, each token corresponding to a table, are active at any time. See List active continuation tokens.
The following command reattempts the data load starting from a specific continuation file, but you can also use individual continuation tokens to reattempt the data load for individual tables.
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
molt fetch \
--source $SOURCE \
--target $TARGET \
--schema-filter 'migration_schema' \
--table-filter 'employees|payments|orders' \
--bucket-path 's3://migration/data/cockroach' \
--table-handling truncate-if-exists \
--ignore-replication-check \
--fetch-id f5cb422f-4bb4-4bbd-b2ae-08c4d00d1e7c \
--continuation-file-name shard_01_part_00000001.csv.gz
```
## Step 5: Verify the data
In this step, you will use MOLT Verify to confirm that the source and target data is consistent. This ensures that the data load was successful. Use MOLT Verify's `--schema-filter` or `--table-filter` to select only the tables that are relevant for the given phase.
### Run MOLT Verify
1. Run the MOLT Verify command, specifying the source and target [connection strings](#connection-strings) and the tables to validate.
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
molt verify \
--source $SOURCE \
--target $TARGET \
--table-filter 'employees|payments|orders'
```
2. Check the output to observe `verify` progress.
A `verification in progress` indicates that the task has started:
```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{"level":"info","time":"2025-02-10T15:35:04-05:00","message":"verification in progress"}
```
`starting verify` messages are written for each specified table:
```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{"level":"info","time":"2025-02-10T15:35:04-05:00","message":"starting verify on public.employees, shard 1/1"}
```
A `finished row verification` message is written after each table is compared. If `num_success` equals `num_truth_rows` and the error counters (`num_missing`, `num_mismatch`, `num_extraneous`, and `num_column_mismatch`) are all `0`, the table verified successfully. Any non-zero values in the error counters indicate data discrepancies that need investigation. For details on each field, refer to the MOLT Verify page.
```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{"level":"info","type":"summary","table_schema":"public","table_name":"employees","num_truth_rows":200004,"num_success":200004,"num_conditional_success":0,"num_missing":0,"num_mismatch":0,"num_extraneous":0,"num_live_retry":0,"num_column_mismatch":0,"time":"2025-02-10T15:35:05-05:00","message":"finished row verification on public.employees (shard 1/1)"}
```
A `verification complete` message is written when the verify task succeeds:
```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{"level":"info","net_duration_ms":699.804875,"net_duration":"000h 00m 00s","time":"2025-02-10T15:35:05-05:00","message":"verification complete"}
```
## Step 6: Finalize the target schema
### Add constraints and indexes
Add any constraints or indexes that you previously [removed from the CockroachDB schema](#drop-constraints-and-indexes) to facilitate data load.
If you used the `--table-handling drop-on-target-and-recreate` option for data load, only `PRIMARY KEY` and `NOT NULL` constraints are preserved. You **must** manually recreate all other constraints and indexes.
For the appropriate SQL syntax, refer to `ALTER TABLE ... ADD CONSTRAINT` and `CREATE INDEX`. Review the best practices for creating secondary indexes on CockroachDB.
## Step 7: Cut over application traffic
With the target cluster verified and finalized, it's time to resume application traffic for the current migration phase.
### Modify application code
In the application back end, update the application to route traffic for this migration phase to the CockroachDB cluster. A simple example:
```yml theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
env:
- name: DATABASE_URL_US_EAST
value: postgres://root@cockroachdb.us-east:26257/defaultdb?sslmode=verify-full
- name: DATABASE_URL_US_WEST
value: postgres://legacy-db.us-west:5432/defaultdb # Still on source
```
In your application code, route database connections based on the user's region:
```python theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
def get_db_connection(user_region):
if user_region == "us-east":
return os.getenv("DATABASE_URL_US_EAST") # CockroachDB
else:
return os.getenv("DATABASE_URL_US_WEST") # Source database
```
### Resume application traffic
If you halted traffic by scaling down a regional Kubernetes deployment, scale it back up.
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
kubectl scale deploy/app-eu --replicas=3
```
Or if this was handled by the NGINX Controller, remove the 503 block that was written in step 3:
```yml theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: app
# annotations:
# nginx.ingress.kubernetes.io/server-snippet: |
# if ($http_x_region = "eu") {
# return 503;
# }
spec:
ingressClassName: nginx
rules:
- host: api.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: app
port:
number: 80
```
This ends downtime for the current migration phase.
## Repeat for each phase
During the next scheduled, regional downtime window, [return to step 3](#step-3-stop-application-traffic) to migrate the next phase of data. Repeat steps 3-7 for each phase of data, until every region's data has been migrated and all application traffic has been cut over to the target.
## See also
* Migration Overview
* Migration Considerations
* Classic Bulk Load Migration
* MOLT Fetch
* MOLT Verify
* MOLT Fetch Troubleshooting for PostgreSQL
* MOLT Replicator Troubleshooting for PostgreSQL