Skip to content

docs(pubsub): update migration docs with seek #12642

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 4, 2025
Merged

docs(pubsub): update migration docs with seek #12642

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 30 additions & 2 deletions pubsub/MIGRATING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,13 +36,13 @@ The following is an overview of the migration process. You can find more details

## Admin operations

The Pub/Sub admin plane is used to manage Pub/Sub resources like topics, subscriptions, and schemas. These admin operations include `Create`, `Get`, `Update`, `List`, and `Delete`.
The Pub/Sub admin plane is used to manage Pub/Sub resources like topics, subscriptions, and schemas. These admin operations include `Create`, `Get`, `Update`, `List`, and `Delete`. For subscriptions, seek and snapshots are also part of this layer.

One of the key differences between the v1 and v2 versions is the change to the admin API. Two new clients called `TopicAdminClient` and `SubscriptionAdminClient` are added that handle the admin operations for topics and subscriptions respectively.

For topics and subscriptions, you can access these admin clients as fields of the main client: `pubsub.Client.TopicAdminClient` and `pubsub.Client.SubscriptionAdminClient`. These clients are pre-initialized when calling `pubsub.NewClient`, and takes in the same `ClientOptions` when `NewClient` is called.

There is a mostly one-to-one mapping of existing admin methods to the new admin methods.
There is a mostly one-to-one mapping of existing admin methods to the new admin methods. There are some exceptions that are noted below.

### General RPCs

Expand Down Expand Up @@ -344,6 +344,34 @@ topic, err := client.TopicAdminClient.CreateTopic(ctx, topicpb)

In this case, `MessageTransform_JavascriptUdf` satisfies the interface, while `JavascriptUdf` holds the actual strings relevant for the message transform.

### Seek / snapshots

Seek and snapshot RPCs are also part of the admin layer. Use the [SubscriptionAdminClient](https://pkg.go.dev/cloud.google.com/go/pubsub/v2/apiv1#SubscriptionAdminClient) to Seek to specific time or snapshot.

```go
// v2 way to call seek on a subscription

import (
"cloud.google.com/go/pubsub/v2"
"google.golang.org/protobuf/types/known/timestamppb"
pb "cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)
...
projectID := "my-project-id"
subscriptionID := "my-subscription-id"

now := time.Now()

client, err := pubsub.NewClient(ctx, projectID)
...
client.SubscriptionAdminClient.Seek(ctx, &pb.SeekRequest{
Subscription: fmt.Sprintf("projects/%s/subscriptions/%s", projectID, subID),
Target: &pb.SeekRequest_Time{
Time: timestamppb.New(now),
},
})
```

### Call Options (retries and timeouts)

In the v2, [pubsub.NewClientWithConfig](https://pkg.go.dev/cloud.google.com/go/pubsub#NewClientWithConfig) is still the correct method to invoke to add RPC specific retries and timeouts. However, the helper struct is renamed from `ClientConfig.PublisherCallOptions` to `TopicAdminCallOptions`. The same is true for Subscription calls, which is now named `SubscriptionAdminCallOptions.`
Expand Down
Loading