--- title: "Neon Migration Specialist: review, role & definition · Undominated.ai" canonical: https://undominated.ai/agents/github-neon-migration-specialist/ description: "Tests schema changes on a temporary Neon database branch and prepares migration files for a separate production rollout." --- # Neon Migration Specialist: review, role & definition · Undominated.ai > Tests schema changes on a temporary Neon database branch and prepares migration files for a separate production rollout. [← Explore all agents](/agents/) MODERNIZATION AND SPECIFICATIONS / github # Neon Migration Specialist Tests schema changes on a temporary Neon database branch and prepares migration files for a separate production rollout. Use this definition ↓Original source ↗ SOURCE REVIEW Reviewed 2026-09-21 Evidence 7 linked sources Publisher github Licence MIT ↗ Revision ad4c196b933c Read what was—and wasn’t—checked ↓ “Safe Postgres migrations with zero-downtime using Neon's branching workflow. Test schema changes in isolated database branches, validate thoroughly, then apply to production—all automated with support for Prisma, Drizzle, or your favorite ORM.” github · upstream description ↗ Our analysis follows below. 01 / THE REASONING ## Why this made the selection. - Explicitly forbids running migrations on the main Neon database branch and separates database branches from Git branches. - Uses the existing migration system before considering a fallback and includes temporary-branch cleanup. ### A good fit for - Rehearsing an ORM migration against an existing Neon project. - Preparing a reviewed migration pull request before the user or CI applies it. ### Weigh up before choosing - Workflow adjustment is required: the description promises automated production application and zero downtime, while the body prohibits main-branch migrations. Use only the test-branch workflow, with no downtime guarantee. - Validation is not specified as concrete data, schema or rollback checks; define those acceptance criteria for the migration. - The original contains an old example expiry timestamp and a documentation URL that returned 404. Use a newly computed expiry and the current Neon documentation linked here. - The prompt asks for an API key. Configure credentials through the host’s protected mechanisms rather than embedding them in the definition or committed files. 02 / THE REVIEW RECORD ## What we actually inspected. Source review has boundaries. A clear record is more useful than a “safe” badge. ### Material inspected - agents/neon-migration-specialist.agent.md (complete original frontmatter and body; strict YAML duplicate-key check) - LICENSE (full applicable licence bytes and redistribution terms) - Current official host configuration documentation; exact source and licence SHA-256 recorded ### Our findings - The source separates Neon database branches from Git branches and prioritises the project’s existing migration system. - Current Neon documentation confirms explicit future expiry and separately configured compute; the original example date and documentation link must not be used as current settings. ### Not established by this review - This agent has not been executed or benchmarked. - Host discovery, configured tool availability, model behaviour and task outcomes were not runtime-tested. The review applies to the material and revision named here. A newer upstream release can change its behavior. 03 / PUT IT TO WORK ## Use the role in your project. Upstream setup instructions ↗ - Download the original neon-migration-specialist.agent.md with its full licence and attribution; inspect the complete instructions and tool scope before use. - Explicitly limit the task to a temporary test database branch. The user or CI applies any production migration separately; the original description’s automation and downtime claims are not guarantees. - Place the reviewed working copy at .github/agents/neon-migration-specialist.agent.md. Select the custom agent in VS Code’s agent picker. - Use the host’s tool configuration to check every declared tool name and any MCP dependency. Confirm a pinned model is available or select a supported one in the working copy; never treat unknown tools as extra permission. - Use the current Neon branch and expiration documentation linked below in place of the original dead documentation URL. Identify the existing project and intended parent branch by ID, then calculate a future RFC 3339 expiry instead of copying the old example. - Configure the API credential through the host’s protected mechanism. Create or attach a compute endpoint for the test branch, and verify the connection points to that branch before running the project’s migration tool. - Agree on schema, data and rollback checks; record their actual results before deleting the temporary branch and preparing the migration pull request. Deleting a database branch permanently removes its branch data. ### Before you start - An existing Neon project and an authorised API credential with the needed test-branch operations. - The project’s migration files and a defined validation/rollback plan; a connected test-branch compute. ### Compatibility GitHub Copilot custom agents in VS Code (workflow adjustment required) ### Temporary database branch and repository writes - No host tool allowlist is declared; the configured host controls available file, shell and network tools. - The intended API operations create and delete a temporary database branch. The body prohibits migration writes to the main database branch. ### Cost model The definition is reusable under its stated licence. The host, model and connected services have their own access and billing terms. THE COMPLETE REVIEWED DEFINITION ## Read it before you reuse it. Original source bytes, with attribution. Review the host-specific setup notes above. Copy definition ↗ [Download definition + licence ↗](/resources/agents/github-neon-migration-specialist/bundle.zip)[Raw Markdown ↗](/resources/agents/github-neon-migration-specialist/definition.md) --- name: Neon Migration Specialist description: Safe Postgres migrations with zero-downtime using Neon's branching workflow. Test schema changes in isolated database branches, validate thoroughly, then apply to production—all automated with support for Prisma, Drizzle, or your favorite ORM. --- # Neon Database Migration Specialist You are a database migration specialist for Neon Serverless Postgres. You perform safe, reversible schema changes using Neon's branching workflow. ## Prerequisites The user must provide: - **Neon API Key**: If not provided, direct them to create one at https://console.neon.tech/app/settings#api-keys - **Project ID or connection string**: If not provided, ask the user for one. Do not create a new project. Reference Neon branching documentation: https://neon.com/llms/manage-branches.txt **Use the Neon API directly. Do not use neonctl.** ## Core Workflow 1. **Create a test Neon database branch** from main with a 4-hour TTL using `expires_at` in RFC 3339 format (e.g., `2025-07-15T18:02:16Z`) 2. **Run migrations on the test Neon database branch** using the branch-specific connection string to validate they work 3. **Validate** the changes thoroughly 4. **Delete the test Neon database branch** after validation 5. **Create migration files** and open a PR—let the user or CI/CD apply the migration to the main Neon database branch **CRITICAL: DO NOT RUN MIGRATIONS ON THE MAIN NEON DATABASE BRANCH.** Only test on Neon database branches. The migration should be committed to the git repository for the user or CI/CD to execute on main. Always distinguish between **Neon database branches** and **git branches**. Never refer to either as just "branch" without the qualifier. ## Migration Tools Priority 1. **Prefer existing ORMs**: Use the project's migration system if present (Prisma, Drizzle, SQLAlchemy, Django ORM, Active Record, Hibernate, etc.) 2. **Use migra as fallback**: Only if no migration system exists - Capture existing schema from main Neon database branch (skip if project has no schema yet) - Generate migration SQL by comparing against main Neon database branch - **DO NOT install migra if a migration system already exists** ## File Management **Do not create new markdown files.** Only modify existing files when necessary and relevant to the migration. It is perfectly acceptable to complete a migration without adding or modifying any markdown files. ## Key Principles - Neon is Postgres—assume Postgres compatibility throughout - Test all migrations on Neon database branches before applying to main - Clean up test Neon database branches after completion - Prioritize zero-downtime strategies The download contains neon-migration-specialist.agent.md . Keep its filename when placing it in the agent directory described above. By **github**. Exact upstream source ↗ · [Licence](/resources/agents/github-neon-migration-specialist/LICENSE.txt) · [Attribution](/resources/agents/github-neon-migration-specialist/ATTRIBUTION.txt) SHA-256 8c6545c7eceaed3a233e8f4034a03b2148efe370dc7f5e95b6fac3832578086e Read the applicable licence MIT License Copyright GitHub, Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 04 / FOLLOW THE EVIDENCE ## The source trail. Our notes are separate from the original resource. Check upstream before adopting a new version. - Complete upstream definition at the reviewed revision ↗ Checked 2026-09-21 https://github.com/github/awesome-copilot/blob/ad4c196b933c5ca7f82a5ba78969ddcd2603ba80/agents/neon-migration-specialist.agent.md Supports: summary, upstreamDescription, whySelected, bestFor, limitations, review, access - Applicable full upstream licence ↗ Checked 2026-09-21 https://github.com/github/awesome-copilot/blob/ad4c196b933c5ca7f82a5ba78969ddcd2603ba80/LICENSE Supports: license, artifact - Current official custom-agent configuration ↗ Checked 2026-09-21 https://code.visualstudio.com/docs/agent-customization/custom-agents Supports: compatibility, install, access, limitations, review - VS Code tool availability and permissions ↗ Checked 2026-09-21 https://code.visualstudio.com/docs/agents/run/tools Supports: install, access, limitations, review - Neon branch lifecycle and compute connections ↗ Checked 2026-09-21 https://neon.com/docs/manage/branches Supports: install, limitations, access, review - Neon branch expiration requirements ↗ Checked 2026-09-21 https://neon.com/docs/guides/branch-expiration Supports: install, limitations, review - Neon create-branch API and optional compute endpoint ↗ Checked 2026-09-21 https://api-docs.neon.tech/reference/createprojectbranch Supports: install, review KEEP COMPARING ## Other approaches to consider. Related by category or shared topics. These are alternatives to inspect, not a measured quality order. [### Business Rules Extractor ↗ Extracts domain calculations, validation and policy rules from legacy code into concrete test scenarios with source references and uncertainty questions.](/agents/anthropic-business-rules-extractor/)[### Pilot-Driven Uplift Migrator ↗ Applies a proven version-upgrade playbook to one module, keeping edits within that unit and reporting its actual build result and playbook gaps.](/agents/anthropic-uplift-migrator/)[### Scaffolder ↗ Creates one modernization service from an approved architecture and specification, including its domain model, API stubs and rule-linked acceptance tests.](/agents/anthropic-scaffolder/) [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)