Roll back a schema revision

This document shows you how to roll back a schema for a Pub/Sub topic.

The rollback operation lets you create another schema revision with the exact schema definition as the specified previous revision.

Before you begin

Required roles and permissions

To get the permissions that you need to roll back schemas and manage them, ask your administrator to grant you the Pub/Sub Editor (roles/pubsub.editor) IAM role on your project. For more information about granting roles, see Manage access.

This predefined role contains the permissions required to roll back schemas and manage them. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to roll back schemas and manage them:

  • Create schema: pubsub.schemas.create
  • Attach schema to topic: pubsub.schemas.attach
  • Commit a schema revision: pubsub.schemas.commit
  • Delete a schema or a schema revision: pubsub.schemas.delete
  • Get a schema or schema revisions: pubsub.schemas.get
  • List schemas: pubsub.schemas.list
  • List schema revisions: pubsub.schemas.listRevisions
  • Rollback a schema: pubsub.schemas.rollback
  • Validate a message: pubsub.schemas.validate
  • Get the IAM policy for a schema: pubsub.schemas.getIamPolicy
  • Configure the IAM policy for a schema: pubsub.schemas.setIamPolicy

You might also be able to get these permissions with custom roles or other predefined roles.

You can grant roles and permissions to principals such as users, groups, domains, or service accounts. You can create a schema in one project and attach it to a topic located in a different project. Ensure that you have the required permissions for each project.

Roll back a schema revision

You can roll back a schema using the Google Cloud console, the gcloud CLI, the Pub/Sub API, or the Cloud Client Libraries. Follow these steps:

Console

  1. In the Google Cloud console, go to the Pub/Sub schemas page.

    Go to Schemas

  2. Click the name of an existing schema.

    The Schema details page for the schema opens.

  3. Click Roll back.

    The Roll back schema dialog opens.

  4. Select the revision to which you want to roll back your schema.

  5. Click Confirm to save the rollback operation.

    A new revision is created with the schema specified in the rollback operation.

  6. In the Schema details page, select the latest version of the schema and the version you selected as source for the rollback operation.

  7. Click View diff.

    You can verify that the two schemas are identical.

    You can use the schema revision that you just created as the last revision for validating a topic by updating the Last revision allowed field.

gcloud

gcloud pubsub schemas rollback SCHEMA_ID \
        --revision-id=REVISION_ID

Where:

  • REVISION_ID is the revision to which you want to roll back.

REST

To roll back a schema, send a POST request like the following:

POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/schemas/SCHEMA_ID:rollback
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json --data @response-body.json

Specify the following fields in the request body:

{
  "revisionId": REVISION_KD
}

Where:

  • REVISION_KD is the ID of the revision to which to roll back.

The response body should contain a JSON representation of a schema resource.

C++

Before trying this sample, follow the C++ setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C++ API reference documentation. 

namespace pubsub = ::google::cloud::pubsub;
[](pubsub::SchemaServiceClient client, std::string const& project_id,
   std::string const& schema_id, std::string const& revision_id) {
  google::pubsub::v1::RollbackSchemaRequest request;
  request.set_name(pubsub::Schema(project_id, schema_id).FullName());
  request.set_revision_id(revision_id);
  auto schema = client.RollbackSchema(request);
  if (!schema) throw std::move(schema).status();

  std::cout << "Rolledback schema. Created a new schema and its metadata is:"
            << "\n"
            << schema->DebugString() << "\n";
}

Go

Before trying this sample, follow the Go setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Go API reference documentation. 

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub"
)

// rollbackSchema creates a new schema revision that is a copy of the provided revisionID.
func rollbackSchema(w io.Writer, projectID, schemaID, revisionID string) error {
	// projectID := "my-project-id"
	// schemaID := "my-schema"
	// revisionID := "a1b2c3d4"
	ctx := context.Background()
	client, err := pubsub.NewSchemaClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewSchemaClient: %w", err)
	}
	defer client.Close()

	s, err := client.RollbackSchema(ctx, schemaID, revisionID)
	if err != nil {
		return fmt.Errorf("RollbackSchema: %w", err)
	}
	fmt.Fprintf(w, "Rolled back a schema: %#v\n", s)
	return nil
}

Java

Before trying this sample, follow the Java setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Java API reference documentation. 


import com.google.api.gax.rpc.NotFoundException;
import com.google.cloud.pubsub.v1.SchemaServiceClient;
import com.google.pubsub.v1.Schema;
import com.google.pubsub.v1.SchemaName;
import java.io.IOException;

public class RollbackSchemaExample {

  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project";
    String schemaId = "your-schema";
    String revisionId = "your-revision";

    rollbackSchemaExample(projectId, schemaId, revisionId);
  }

  public static void rollbackSchemaExample(String projectId, String schemaId, String revisionId)
      throws IOException {
    SchemaName schemaName = SchemaName.of(projectId, schemaId);

    try (SchemaServiceClient schemaServiceClient = SchemaServiceClient.create()) {

      Schema schema = schemaServiceClient.rollbackSchema(schemaName, revisionId);

      System.out.println("Rolled back a schema:" + schema);

    } catch (NotFoundException e) {
      System.out.println(schemaName + "not found.");
    }
  }
}

Python

Before trying this sample, follow the Python setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Python API reference documentation. 

from google.api_core.exceptions import NotFound
from google.cloud.pubsub import SchemaServiceClient

# TODO(developer): Replace these variables before running the sample.
# project_id = "your-project-id"
# schema_id = "your-schema-id"
# schema_revision_id = "your-schema-revision-id"

schema_client = SchemaServiceClient()
schema_path = schema_client.schema_path(project_id, schema_id)

try:
    result = schema_client.rollback_schema(
        request={"name": schema_path, "revision_id": schema_revision_id}
    )
    print(f"Rolled back a schema revision:\n{result}")
except NotFound:
    print(f"{schema_id} not found.")

Node.js

Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation. 

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const schemaNameOrId = 'YOUR_SCHEMA_NAME_OR_ID';
// const revisionId = 'YOUR_REVISION_ID';

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function rollbackSchema(schemaNameOrId, revisionId) {
  // Get the fully qualified schema name.
  const schema = pubSubClient.schema(schemaNameOrId);
  const name = await schema.getName();

  // Use the gapic client to roll back the schema revision.
  const schemaClient = await pubSubClient.getSchemaClient();
  await schemaClient.rollbackSchema({
    name,
    revisionId,
  });

  console.log(`Schema ${name} revision ${revisionId} rolled back.`);
}

Node.js

Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation. 

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const schemaNameOrId = 'YOUR_SCHEMA_NAME_OR_ID';
// const revisionId = 'YOUR_REVISION_ID';

// Imports the Google Cloud client library
import {PubSub} from '@google-cloud/pubsub';

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function rollbackSchema(schemaNameOrId: string, revisionId: string) {
  // Get the fully qualified schema name.
  const schema = pubSubClient.schema(schemaNameOrId);
  const name = await schema.getName();

  // Use the gapic client to roll back the schema revision.
  const schemaClient = await pubSubClient.getSchemaClient();
  await schemaClient.rollbackSchema({
    name,
    revisionId,
  });

  console.log(`Schema ${name} revision ${revisionId} rolled back.`);
}

What's next