feat: preview-create becomes preview-deploy to allow updating of prev…

[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.