DOCSEARCHbyAlgolia
Submit Docs

Google Cloud Client Libraries for Go

repository·main·Indexed 26 days ago

https://github.com/googleapis/google-cloud-go

Idiomatic Go packages for interacting with various Google Cloud Platform services, including Vertex AI, AlloyDB, API Gateway, Generative Language API, and Gemini Enterprise Agent Platform. The libraries provide support for both stable (e.g., apiv1) and experimental/beta service backends.

Tokens
61.6K
Snippets
257
Records
516
Agent score
89%

What's inside google-cloud-go

  1. Understand SessionClient topology and ownership

    main

    The SessionClient manages the lifecycle and pooling of Bigtable sessions. Understanding its hierarchy is critical for resource management:

    • Client to SessionClient (1:1): A bigtable.Client owns exactly one SessionClient. All session-eligible operations on that client use the same SessionClient instance.
    • SessionClient to SessionPools (1:N): A single SessionClient manages multiple session pools, which are lazily created and keyed by {resource, direction} (e.g., a specific table and whether it is for read or write).
    • Pool Deduplication: Multiple calls to OpenTable, OpenAuthorizedView, or OpenMaterializedView for the same resource and direction will return handles backed by the same underlying pool pair within a single SessionClient.
    • Lazy Creation: Pools and individual sessions are not created at initialization. A pool is only opened when the first operation (like ReadRow or Apply) is issued. Failed opens are not cached, allowing for automatic retries on transient errors.

  3. Use spansql for Spanner SQL parsing and syntactic operations

    main

    The spansql package provides types and a parser specifically for the Spanner SQL dialect. It is intended for tools that need to interact with Spanner on a syntactic basis, such as schema management tools (DDL) or SQL statement parsers.

    Note: This package is designed for syntactic operations and is not a complete implementation of Spanner's full functionality. For functional end-to-end testing, use a Spanner instance or the Spanner Emulator.

  4. Understand Cloud Workstations API stability and breaking changes

    main

    The stability of the Cloud Workstations module follows Semantic Versioning (SemVer). However, breaking changes may occur in v1+ modules if:

    1. The import path contains alpha or beta.
    2. The GoDoc contains an explicit stability disclaimer (e.g., for experimental features).

  5. Manage SessionClient Channel Pools

    main

    A SessionClient uses a single shared ChannelPool for all its session pools, regardless of the resource type or direction.

    • Shared Infrastructure: Every SessionPoolImpl (Table, Authorized View, or Materialized View) dials through this single channel pool.
    • Traffic Distribution: Session traffic is fanned out across sub-channels within this pool based on MinServerCount, MaxServerCount, and PerServerSessionCount.
    • Separation from Classic Pool: In a mixed-mode bigtable.Client, the session channel pool is distinct from the classic (data-plane) channel pool. The Diverter component is responsible for routing calls to the appropriate pool.
    • Teardown: Calling SessionClient.Close() will close all managed SessionPoolImpl instances, the shared channel pool, and the metrics factory.

  6. Understand Bigtable Session Pool Topology

    main

    Bigtable resources use session pools to manage connections. Most resources have two distinct pools—one for read operations and one for write operations. This separation prevents cross-direction traffic from starving different types of requests.

    Key behaviors:

    • MaterializedViews: These are read-only. Attempting a MutateRow on a MaterializedView will return ErrWriteNotSupported.
    • Lazy Initialization: Pools are lazyPool types. They are not opened when you call OpenTable, but rather on the first ReadRow or Apply call.
    • Error Handling: Because pools are lazy, serialization failures (like proto.Marshal) will surface during the first actual data operation (ReadRow/Apply) rather than at the table opening stage.
    • Pool Independence: Read and write pools do not share sessions; each runs its own OpenSession bidi stream.

  7. Understand the spannertest architecture

    main

    The spannertest package is designed to support testing code that uses Cloud Spanner as a client. It is optimized for correctness and simplicity rather than performance. The architecture is divided into five functional sections:

    • RPC interface (inmem.go): Implements the gRPC interface used by Cloud Spanner, handling conversions between gRPC protobuf types and internal package types.
    • Top-level DB interface (db.go): Manages primitive types (database, table, row), schema management, all write operations (insert, update, delete, DML), and basic reads (key-based and key-range-based).
    • Query evaluator (db_query.go): Evaluates spansql.Query objects by transforming them into a pipeline of rowIter transformers.
    • Expression evaluator (db_eval.go): Evaluates spansql.Expr within specific contexts (e.g., on a table row).
    • Expression functions (funcs.go): Contains the logic for expression functions.

  8. Understand Cloud Commerce Consumer Procurement API stability

    main

    Stability is indicated by Semantic Versioning (SemVer). However, be aware that breaking changes may occur in v1+ modules if:

    1. The import path contains alpha or beta.
    2. The GoDoc contains an explicit stability disclaimer (e.g., for experimental features).

  10. Understand Cloud Location Finder API stability

    main

    The stability of the Cloud Location Finder module follows Semantic Versioning (SemVer). However, be aware that v1+ modules may introduce breaking changes if:

    1. The import path contains alpha or beta.
    2. The GoDoc contains an explicit stability disclaimer (e.g., for experimental features).

  11. Understand the Bigtable Session subsystem topology

    main

    The Bigtable Session subsystem is organized into a layered architecture to maintain strict boundaries and prevent circular dependencies. The layers, from bottom to top, are:

    1. Transport primitives: Handles bidi streams, retry classification, and message types (bigtable/internal/transport/).
    2. Session: A state machine wrapping a bidi stream with lifecycle and heartbeat management (bigtable/internal/transport/).
    3. Pool: Groups multiple Sessions by AFE (App Frontend Endpoint), managing check-in/out and sizing (bigtable/internal/transport/).
    4. Session client + tables: Provides per-resource read/write pool pairs and the proto-native table API (bigtable/internal/session/).
    5. Routing shim + diverter: Manages mixed-mode routing between session-based and classic Bigtable modes (bigtable/table_shim.go, bigtable/internal/transport/diverter.go).
    6. Public bigtable API: The user-facing Client, Table, Mutation, and Row interfaces (bigtable/).
    7. Observability tier: Provides debug views (z-pages) and snapshot DTOs (bigtable/debugview/, bigtable/internal/transport/*_snapshot.go).