Upgrading Cynic v1 to v2

Cynic made a number of breaking changes in v2. I've tried to make the upgrade process as smooth as possible despite these, but here's a guide for how to do an upgrade.

Update your Cargo.toml

First update the version reference for cynic in your Cargo.toml to 2.

Some of the names of features changed in v2, so you may also need to update those:

old featurenew feature

Cynic v1 had some features that existed only to enable surf features:

  • surf-h1-client
  • surf-curl-client
  • surf-wasm-client
  • surf-middleware-logger
  • surf-encoding.

These no longer exist in cynic v2 - you should remove these features and instead add the equivalents to the surf entry in your Cargo.toml

Update queries with variables

Any of your existing QueryFragments that take variables will need to be updated to the new argument syntax. This new syntax is very similar to the underlying GraphQL argument syntax. For example if you currently have

    first = args.page_size,
    states = Some(vec![PullRequestState::Merged]),
    after = &args.pr_cursor

You should change this to

#[arguments(first: $page_size, states = [MERGED], after: $pr_cursor)]

Note that cynic will no longer re-case arguments: you should use the names of arguments/input fields as they appear in the graphql schema.

Add Fallbacks to InlineFragments

If your queries have any InlineFragments without fallbacks you'll need to add one to them. Cynic v2 no longer does exhaustiveness checking on InlineFragments, so requires a fallback every time.

Update JSON decoding

If you are manually decoding cynic responses you should update the code responsible to use serde_json directly rather than Operation::decode_response.

Update ::build calls

The QueryBuilder::build, MutationBuilder::build and SubscriptionBuilder::build calls now take their parameter by value, so you should update any uses of them accordingly.

Update deprecations

Rust itself should let you know about the deprecations, but you will likely need to:

  • Use the QueryVariables derive instead of FragmentArguments.
  • Find any structs that derive QueryFragment and are using the argument_struct parameter. You need to rename this to variables.