Example: Add frontend migration example

examples/datasource-http-backend/pkg/kinds/query.go

@@ -6,7 +6,10 @@ import (
 )
 
 type DataQuery struct {
-	Multiplier int `json:"multiplier"`
+	// Deprecated: Moved to Multiply, made optional
+	Multiplier int `json:"multiplier,omitempty"`
+	// Multiply is the number to multiply the input by
+	Multiply int `json:"multiply,omitempty"`
 }
 
 //go:embed query.types.json

examples/datasource-http-backend/pkg/kinds/query.panel.example.json

@@ -7,7 +7,7 @@
         "type": "grafana-testdata-datasource",
         "uid": "TheUID"
       },
-      "multiplier": 1
+      "multiply": 1
     }
   ]
 }

examples/datasource-http-backend/pkg/kinds/query.panel.schema.json

@@ -9,9 +9,6 @@
       "type": "array",
       "items": {
         "type": "object",
-        "required": [
-          "multiplier"
-        ],
         "properties": {
           "datasource": {
             "description": "The datasource",
@@ -49,6 +46,11 @@
             "type": "integer"
           },
           "multiplier": {
+            "description": "Deprecated: Moved to Multiply, made optional",
+            "type": "integer"
+          },
+          "multiply": {
+            "description": "Multiply is the number to multiply the input by",
             "type": "integer"
           },
           "queryType": {

examples/datasource-http-backend/pkg/kinds/query.request.example.json

@@ -6,7 +6,7 @@
       "refId": "A",
       "maxDataPoints": 1000,
       "intervalMs": 5,
-      "multiplier": 1
+      "multiply": 1
     }
   ]
 }

examples/datasource-http-backend/pkg/kinds/query.request.schema.json

@@ -19,9 +19,6 @@
       "type": "array",
       "items": {
         "type": "object",
-        "required": [
-          "multiplier"
-        ],
         "properties": {
           "datasource": {
             "description": "The datasource",
@@ -59,6 +56,11 @@
             "type": "integer"
           },
           "multiplier": {
+            "description": "Deprecated: Moved to Multiply, made optional",
+            "type": "integer"
+          },
+          "multiply": {
+            "description": "Multiply is the number to multiply the input by",
             "type": "integer"
           },
           "queryType": {

examples/datasource-http-backend/pkg/kinds/query.types.json

@@ -8,7 +8,7 @@
     {
       "metadata": {
         "name": "default",
-        "resourceVersion": "1720173156947",
+        "resourceVersion": "1720430974503",
         "creationTimestamp": "2024-07-05T09:52:36Z"
       },
       "spec": {
@@ -17,19 +17,21 @@
           "additionalProperties": false,
           "properties": {
             "multiplier": {
+              "description": "Deprecated: Moved to Multiply, made optional",
+              "type": "integer"
+            },
+            "multiply": {
+              "description": "Multiply is the number to multiply the input by",
               "type": "integer"
             }
           },
-          "required": [
-            "multiplier"
-          ],
           "type": "object"
         },
         "examples": [
           {
             "name": "simple multiplier",
             "saveModel": {
-              "multiplier": 1
+              "multiply": 1
             }
           }
         ]

examples/datasource-http-backend/pkg/kinds/query_test.go

@@ -29,7 +29,7 @@ func TestQueryTypeDefinitions(t *testing.T) {
 					Name: "simple multiplier",
 					SaveModel: data.AsUnstructured(
 						DataQuery{
-							Multiplier: 1,
+							Multiply: 1,
 						},
 					),
 				},

examples/datasource-http-backend/pkg/plugin/datasource.go

@@ -9,6 +9,7 @@ import (
 	"strconv"
 	"time"
 
+	"github.com/grafana/datasource-http-backend/pkg/kinds"
 	"github.com/grafana/grafana-plugin-sdk-go/backend"
 	"github.com/grafana/grafana-plugin-sdk-go/backend/datasource"
 	"github.com/grafana/grafana-plugin-sdk-go/backend/httpclient"
@@ -174,13 +175,13 @@ func (d *Datasource) query(ctx context.Context, pCtx backend.PluginContext, quer
 		return backend.DataResponse{}, fmt.Errorf("new request with context: %w", err)
 	}
 	if len(query.JSON) > 0 {
-		input := &apiQuery{}
+		input := &kinds.DataQuery{}
 		err = json.Unmarshal(query.JSON, input)
 		if err != nil {
 			return backend.DataResponse{}, fmt.Errorf("unmarshal: %w", err)
 		}
 		q := req.URL.Query()
-		q.Add("multiplier", strconv.Itoa(input.Multiplier))
+		q.Add("multiplier", strconv.Itoa(input.Multiply))
 		req.URL.RawQuery = q.Encode()
 	}
 	httpResp, err := d.httpClient.Do(req)

examples/datasource-http-backend/src/components/QueryEditor.tsx

@@ -1,24 +1,23 @@
-import React, { PureComponent } from 'react';
+import React from 'react';
 import { QueryEditorProps } from '@grafana/data';
 import { DataSource } from '../datasource';
 import { MyDataSourceOptions, MyQuery } from '../types';
 import { HorizontalGroup, Input, Label } from '@grafana/ui';
 
 type Props = QueryEditorProps<DataSource, MyQuery, MyDataSourceOptions>;
 
-export class QueryEditor extends PureComponent<Props> {
-  render() {
-    return (
-      <HorizontalGroup>
-        <Label htmlFor="multiplier">Multiplier</Label>
-        <Input
-          type="number"
-          id="multiplier"
-          name="multiplier"
-          value={this.props.query.multiplier}
-          onChange={(e) => this.props.onChange({ ...this.props.query, multiplier: e.currentTarget.valueAsNumber })}
-        />
-      </HorizontalGroup>
-    );
-  }
+export function QueryEditor(props: Props) {
+  const query = props.datasource.migrateQuery(props.query);
+  return (
+    <HorizontalGroup>
+      <Label htmlFor="multiplier">Multiplier</Label>
+      <Input
+        type="number"
+        id="multiplier"
+        name="multiplier"
+        value={query.multiply}
+        onChange={(e) => props.onChange({ ...query, multiply: e.currentTarget.valueAsNumber })}
+      />
+    </HorizontalGroup>
+  );
 }

examples/datasource-http-backend/src/datasource.ts

@@ -1,14 +1,33 @@
 import { CoreApp, DataSourceInstanceSettings } from '@grafana/data';
 
-import { MyQuery, MyDataSourceOptions } from './types';
+import { MyQuery, MyDataSourceOptions, MyQueryDeprecated } from './types';
 import { DataSourceWithBackend } from '@grafana/runtime';
+import { omit } from 'lodash';
 
 export class DataSource extends DataSourceWithBackend<MyQuery, MyDataSourceOptions> {
   constructor(instanceSettings: DataSourceInstanceSettings<MyDataSourceOptions>) {
     super(instanceSettings);
   }
 
   getDefaultQuery(_: CoreApp): Partial<MyQuery> {
-    return { multiplier: 1 };
+    return { multiply: 1 };
+  }
+
+  migrateQuery(query: MyQuery | MyQueryDeprecated): MyQuery {
+    if (query.datasource?.apiVersion !== 'v0alpha1') {
+      // Unkown version
+      return query as MyQuery;
+    }
+    if ('multiply' in query) {
+      return query;
+    }
+    if ('multiplier' in query) {
+      const migrated: MyQuery = {
+        ...query,
+        multiply: query.multiplier,
+      };
+      return omit(migrated, 'multiplier');
+    }
+    throw new Error('Unknown query format');
   }
 }

examples/datasource-http-backend/src/types.ts

@@ -1,9 +1,15 @@
-import { DataQuery, DataSourceJsonData } from '@grafana/data';
+import { DataQuery, DataSourceJsonData } from '@grafana/schema';
 
-export interface MyQuery extends DataQuery {
+export interface MyQueryDeprecated extends DataQuery {
+  // Old implementation
   multiplier: number;
 }
 
+export interface MyQuery extends DataQuery {
+  // New
+  multiply: number;
+}
+
 /**
  * Value that is used in the backend, but never sent over HTTP to the frontend
  */