canonical: https://jentic.com/apis/googleapis.com/datamigration

# Google Database Migration API

The Google Cloud Database Migration API drives the lifecycle of homogeneous and heterogeneous database migrations into Cloud SQL, AlloyDB, and Spanner. It exposes 41 endpoints covering connection profiles for source and destination databases, migration jobs, conversion workspaces for schema translation, and private connectivity. The API supports continuous replication migrations, so cutover happens with minimal downtime once the source and target are in sync.

## For AI agents

Drive database migrations into Cloud SQL, AlloyDB, and Spanner programmatically. Lets agents create connection profiles, run migration jobs, and manage conversion workspaces without the Cloud Console.

## Scope

Does not run application data backfills, perform query-level transformations, or replicate non-database event streams - use for managed homogeneous and heterogeneous database migrations into Cloud SQL, AlloyDB, and Spanner only.

## Capabilities

- Create connection profiles for MySQL, PostgreSQL, Oracle, and SQL Server source databases
- Run continuous-replication migration jobs from on-prem or cloud sources to Cloud SQL or AlloyDB
- Convert Oracle and SQL Server schemas to PostgreSQL using conversion workspaces
- Generate SSH and TCP proxy scripts for self-managed source connectivity
- Promote a migration job to cut over to the destination database
- Verify, restart, and stop migration jobs at any point in their lifecycle

## Use cases

### Continuous-Replication Migration to Cloud SQL

Move a production MySQL or PostgreSQL database from on-prem or another cloud into Cloud SQL with continuous replication and a near-zero-downtime cutover. The API creates source and destination connection profiles, starts the migration job in DUMP_AND_CONTINUOUS mode, and exposes a promote operation when the team is ready to switch traffic. Most one-database migrations complete in hours plus the replication lag.

Example prompt: Create source and destination connection profiles, start a migration job named 'mysql-prod-to-cloudsql' in CONTINUOUS mode, verify it, and promote when source and destination report consistent state

### Heterogeneous Oracle-to-PostgreSQL Conversion

Convert an Oracle schema to PostgreSQL by creating a conversion workspace, importing the source DDL, applying conversion rules, and exporting the converted schema. The API exposes describeDatabaseEntities and describeConversionWorkspaceRevisions to inspect the conversion result before applying it to a destination AlloyDB or Cloud SQL for PostgreSQL instance.

Example prompt: Create a conversion workspace 'oracle-finance-cw', describe its database entities, apply conversion to a PostgreSQL destination, and report any UNSUPPORTED entities back to the user

### Migration CI/CD with Verification Gates

Wire migration jobs into a release pipeline: createConnectionProfile and createMigrationJob from the build environment, verifyMigrationJob as a quality gate, and promote only when the gate passes. The API's restart and stop operations let pipelines retry transient failures or abort cleanly. This supports repeatable database refreshes for staging environments.

Example prompt: Run verifyMigrationJob on 'staging-refresh-2026-06', wait for the operation to complete, and only call promoteMigrationJob if verification reports OK

### AI Agent Migration Operator

An AI agent can drive database migrations end-to-end through Jentic without touching the Console. Jentic search returns the matching connection-profile, migration-job, or conversion-workspace operation, the agent loads its schema, and Jentic executes against datamigration.googleapis.com using vault-stored credentials. This removes the multi-day OAuth and long-running-operation plumbing work.

Example prompt: Use Jentic to search 'create a database migration job', load the createMigrationJob schema, and execute it from the configured source profile to a Cloud SQL destination

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v1/{+parent}/connectionProfiles | Create a source or destination connection profile |
| POST | /v1/{+parent}/migrationJobs | Create a migration job |
| POST | /v1/{+name}:verify | Verify a migration job before promotion |
| POST | /v1/{+name}:promote | Promote the migration job to cut over |
| POST | /v1/{+migrationJob}:generateSshScript | Generate SSH script for self-managed source |
| POST | /v1/{+conversionWorkspace}:describeDatabaseEntities | Inspect entities in a conversion workspace |

## Key resources

- **ConnectionProfiles** — Source and destination database connection settings
- **MigrationJobs** — Continuous-replication migration jobs from source to destination
- **ConversionWorkspaces** — Schema conversion workspaces for heterogeneous migrations
- **PrivateConnections** — VPC peering and reverse-SSH private connectivity for sources
- **Operations** — Long-running operations for create, promote, verify, and stop calls

## Why Jentic

- **Setup:** Wiring the Database Migration API by hand means setting up Google OAuth, refreshing short-lived scoped tokens instead of embedding client secrets, and addressing connection profile and migration job resources on datamigration.googleapis.com. Through Jentic you install once, import the Database Migration API from the API Directory, store the Google credential once, and your agent calls it.
- **Permission scoping:** The API carries the parent and resource name in the URL path (/v1/{parent}/migrationJobs and /v1/{name}:verify), so a rule can pin your agent to one migration job or conversion workspace. You choose the operations it may call, so it can create and verify a migration job while promote is not included unless you add it.
- **Credential handling:** Your Google OAuth credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a database migration job', and Jentic returns the matching Database Migration operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Cloud SQL Admin API** — Cloud SQL Admin manages the destination instances that Database Migration writes into.
- **AlloyDB Admin API** — AlloyDB Admin manages PostgreSQL-compatible destinations for Oracle and PostgreSQL migrations.
- **Datastream API** — Datastream provides change-data-capture streams; Database Migration provides a managed end-to-end migration with cutover.

## FAQ

### What authentication does the Database Migration API use?

The Database Migration API uses OAuth 2.0 with the cloud-platform scope. Through Jentic the OAuth client and refresh tokens live in your Jentic One instance and the agent receives short-lived scoped tokens, so raw Google credentials never enter the agent context.

### Can I migrate Oracle to PostgreSQL with this API?

Yes. Create a ConversionWorkspace, import the Oracle DDL, call describeDatabaseEntities to inspect the converted entities, and apply the conversion to a PostgreSQL destination (Cloud SQL for PostgreSQL or AlloyDB). Heterogeneous MySQL-to-PostgreSQL is also supported through the same workflow.

### What are the rate limits for the Database Migration API?

Google enforces standard Cloud quotas on datamigration.googleapis.com: per-project rate limits on read/write calls and limits on concurrent migration jobs per region. Quotas are visible in the Cloud Console under IAM and admin, quotas, filtered to datamigration.googleapis.com.

### How do I cut over a migration through Jentic?

Search Jentic for 'promote a database migration job', load the schema for POST /v1/{+name}:promote, and execute with the migration-job resource name. Jentic returns the long-running operation; poll until done before pointing application traffic at the destination.

### Is the Database Migration API free?

Migrations into Cloud SQL are free for the migration phase; you pay only the standard Cloud SQL or AlloyDB charges of the destination instance plus any egress from the source. Migrations into other targets and ongoing replication beyond cutover may attract additional fees per the official pricing page.

### How do I connect to a self-managed source database?

Call POST /v1/{+migrationJob}:generateSshScript or generateTcpProxyScript to retrieve a script that opens a reverse-SSH tunnel or TCP proxy from your bastion host to Google's migration service. Run the script on the bastion before starting the migration job.

### Can I limit what my agent is allowed to do with the Database Migration API?

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use. Since this API carries the parent and resource name in the URL path (for example /v1/{parent}/migrationJobs and /v1/{name}:verify), you can pin the agent to a single migration job or conversion workspace. You can also choose exactly which operations it calls, so it may create and verify a migration job while promote stays off unless you grant it.