feat: add --preview-deploy-or-create to support updating previous preview deployments

[gary-ix]

…iew environments rather than always creating new ones

Problem

Currently --preview-create only creates new preview deployments and does not allow for updating a preview deployment.

Solution

Replaced --preview-create with --preview-deploy:

• If preview deployment exists it pushes changes to that preview.
• If preview deployment does not exist it creates the preview deployment.

Implementation

• Added checkPreviewDeploymentExists() function
• Routes to appropriate deployment function based on existence
• Adds deprecation for --preview-create

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[thomasballinger]

Thanks for contributing this, it's a feature people have asked for and we want to implement.

This should be opt-in instead of the new main supported way to do this because it makes data migrations required: by default, pushing a change to a branch should create a new deployment so that the data in the existing deployment won't cause push to be rejected due to changes to the schema. So let's not deprecate the old behavior.

I think I'd rather this be a flag like --resuse-deployment, since --preview-create is optional anyway and specifying a preview name is unrelated to this deployment reuse behavior.

Catching the error is a clever, I thought we'd need api.convex.dev support for this. This implementation seems good, we'll need make sure this error code is stable but this should work.

I'd like to have special error handling (at least an error message) for a data migration error suggesting action to take to fix your preview deploy, which makes me want to control this from the Convex dashboard instead (since changing a preview deploy pipeline is pretty involved). Either that or have an automatic retry: if we catch a "your schema doesnt' match" error we should log a warning that we're wiping state and get a new deployment.

We can do most of this from the CLI so feel free to make these changes and resubmit, I think this is promising as a prototype / most of the CLI-side changes for the feature. I'd want to make some backend changes to better support this but if we can do the above I'm interested in merging this.

[gary-ix]

Hi long time no see.

This time I just added a new CLI option for --preview-deploy-or-create. When this is set, it still uses the previous logic to look up a previous deployment, and if it exists, then it deploys to the existing preview. If the existing preview does not exist, it falls through to the behavior of --preview-create unless the lookup had a non-404 error. We could still fall through here regardless of the lookup error, but the Convex team probably has better opinions about this.

I kept the logic the same between --preview-deploy-or-create and --preview-create for determining the preview name, so existing CIs on Netlify, Vercel, etc. should be able to cleanly transition to this new option if they choose to do so.
Previously @thomasballinger, you had mentioned special error handling, and I am not clear on exactly how to implement that. You also had mentioned backend changes to better support this.

Let me know how else I can help.