Vercel -> Render Migration Playbook (Reuse Existing Postgres URL)

What You Will Learn

• Drive migration with prompts and explicit expected agent actions.
• Inventory Vercel + Render state before running writes.
• Create or reuse a Render web service and set `DATABASE_URL` safely.
• Validate outcomes with optional restart and post-run checks.

Purpose

This guide uses the `vercel_to_render_neon` workflow name in prompts and examples.

The workflow migrates app runtime from Vercel to Render while reusing an existing Postgres connection string (`DATABASE_URL`), rather than provisioning or migrating databases.

expected You get a concrete, repeatable path: discover project state, create/find Render service, upsert `DATABASE_URL`, and optionally restart.

Workflow Scope

Current in-scope actions for `vercel_to_render_neon`:

1) Read Vercel project details and locate `DATABASE_URL` (or use an explicit override).

2) Find an existing Render web service by name, or create one if missing.

3) Upsert `DATABASE_URL` on the target Render service.

4) Optionally restart the Render service after env var update.

tip Out of scope for this workflow: DNS/domain cutover, cross-database data migration, and blue/green traffic switching.

How to Use This Guide (Goal-Oriented, NL-First)

This guide is outcome-oriented: use natural-language prompts to communicate migration goals, constraints, and gates, then evaluate whether agent actions satisfy those goals.

For this workflow, step execution is deterministic once inputs are fixed, but input collection and environment mapping are non-deterministic and should be handled through explicit prompt-and-review loops.

Keep safety invariants stable: do read-only discovery first, review conditional execution paths before write steps, redact secrets in reports, and finish with pass/fail evidence.

expected You can use the same goal prompts across environments even when resource IDs, names, or surrounding deployment details differ.

Prompt Patterns: Prompt -> Expected Agent Actions

Use these prompts as realistic operator commands for a connected agent. Each prompt maps to expected actions aligned to the workflow behavior.

tip If IDs differ in your environment, ask the agent to discover available commands/workflows first and substitute exact IDs before execution.

Pattern 1: Inventory and Input Collection (Read-Only)

Start with discovery to gather workflow inputs and verify prerequisites.

Prompt:
Inventory Vercel project and Render workspace state for this migration. Do not write anything. Return required workflow inputs and identify any missing values.

expected Expected agent actions: discover project/service state, resolve owner/project identifiers, and report missing required inputs before execution.

fallback Representative discovery commands: `vercel projects:list`, `vercel projects:info`, `vercel projects:env:list`, `render owners:list`, `render services:list`.

Pattern 2: Prepare a Safe Run Plan

Use the agent to preview what will happen for your inputs before running writes.

Prompt:
Prepare a run plan for vercel_to_render_neon using my inputs. Show which steps will execute, which are conditional, and any risks before I approve.

expected Expected agent actions: resolve conditions (existing service vs new service, Vercel value vs override), surface risks, and request approval before writes.

Pattern 3: Run Migration Workflow

Execute the migration workflow after review and approval.

Prompt:
Run vercel_to_render_neon now with the approved inputs. Reuse existing Render service if present; create it only if missing. Then set DATABASE_URL and restart if enabled.

expected Expected agent actions: execute workflow steps in order, report which branch was taken (existing/new service, override/derived URL), and return resulting service identifiers.

fallback Representative mutating commands: `render services:create`, `render services:env-vars:add-or-update-environment-variable`, `render services:restart:create`.

Pattern 4: Post-Run Validation

Validate that app runtime and environment configuration are correct after the workflow completes.

Prompt:
Validate migration outcomes without further writes. Confirm the Render service exists, DATABASE_URL is set, and restart status is healthy.

expected Expected agent actions: run read-oriented checks, summarize deployment health, and report pass/fail for each acceptance item.

tip Keep `DATABASE_URL` values redacted in summaries and logs.

Pattern 5: Read-Only Executive Summary

Use a read-only summary when reporting status to stakeholders.

Prompt:
Produce an executive summary of this Vercel-to-Render migration run with completed steps, unresolved risks, and next actions. Do not perform any writes.

expected Expected agent actions: summarize outcomes from completed workflow steps, list open items, and avoid mutating operations.

Workflow Blueprint (Recommended Run Order)

Use this run order for predictable, reviewable execution:

1) Inventory and inputs -> 2) Review conditional run plan -> 3) Execute `vercel_to_render_neon` -> 4) Post-run validation -> 5) Executive summary.

tip Use the Workflows view to review/approve generated workflows and inspect step-level outcomes: `/docs/learn/workflows-basics`.

Rollback and Safety Notes

For this workflow scope, rollback is configuration-focused:

Re-point runtime traffic to the prior Vercel deployment if Render validation fails.

Restore prior `DATABASE_URL` value on Render (or remove it) if incorrect.

Disable optional restart behavior during retries if you need staged verification first.

expected You can revert app runtime behavior quickly without performing cross-database rollback operations.

Migration Acceptance Checklist

Render service is healthy and serving expected responses.

`DATABASE_URL` is present on Render service and points to the intended database target.

Workflow branch outcome is documented (existing vs new service, override vs Vercel-derived URL).

If restart was enabled, restart completed successfully.

No secret values were exposed in logs or reports.

expected Migration is complete for this workflow when runtime and environment checks pass and residual risk is accepted.

Next Steps

If you need full domain cutover or cross-database migration, add separate workflows for those phases and keep them behind explicit approvals.

Export reviewed workflow runs and operator notes into repository docs for auditability.

tip Use a periodic read-only validation prompt to detect config drift after migration.

Extension Goals (For Full Migration Coverage)

Use these extension workflows for phases intentionally out of scope for `vercel_to_render_neon`.

Each extension should be implemented as its own workflow with explicit inputs, gate criteria, and acceptance checks.

tip Before running extension prompts, ask the agent to list available workflows and use the exact workflow IDs it finds in your environment.

tip Manual operator control points are easiest to run from `/docs/learn/workflows-basics` with guardrails from `/docs/learn/how-oatty-executes-safely`.

Extension Goal 1: Domain Cutover

Use a dedicated domain-cutover workflow for this goal. If one does not exist yet, ask the agent to draft it before proceeding.

Use this extension after Render runtime validation is green and before final traffic switch.

Prompt:
Run the domain cutover extension workflow for this migration. Pause before final DNS changes, show me the exact records to change, and continue only after explicit approval.

expected Expected agent actions: verify Render domain readiness, propose DNS changes, pause for approval, execute switch, and run post-switch domain/TLS checks.

tip Gate criteria: Render service health is green, rollback target is confirmed, and DNS change window is approved.

Extension Goal 2: Database Migration

Use a dedicated database-migration workflow for this goal. If one does not exist yet, ask the agent to draft it before proceeding.

Use this extension only when moving data to a new database target; skip if you continue reusing the existing `DATABASE_URL`.

Prompt:
Run the database migration extension workflow with pre-migration backup confirmation, parity checks, and rollback notes. Stop immediately if any integrity check fails.

expected Expected agent actions: verify source/target connectivity, enforce backup gate, execute migration sequence, run schema/row-count parity checks, and report pass/fail with rollback readiness.

advanced Gate criteria: backup/snapshot exists, migration window is active, validation queries are defined, and operator approval is recorded.

Extension Goal 3: Post-Cutover Audit

Use a dedicated post-cutover audit workflow for this goal. If one does not exist yet, ask the agent to draft it before proceeding.

Use this extension after runtime/domain cutover to produce an operator and leadership-ready status report.

Prompt:
Run the post-cutover audit extension workflow in read-only mode and return an executive pass/fail summary with unresolved risks and immediate next actions.

expected Expected agent actions: execute read-only checks for health, config integrity, and recent deploy state; then emit concise status, risks, and recommended follow-up actions.

tip Gate criteria: cutover is complete, monitoring data is available, and no in-progress rollback is active.