### Start Pub/Sub Emulator

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/configuration.md

Use the gcloud beta command to start the Pub/Sub emulator on a specified host and port.

```bash
# Start emulator
gcloud beta emulators pubsub start --host-port=localhost:8085
```

--------------------------------

### Run Spanner Query Example

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/googleapis-raw/README.md

Execute the Spanner query example provided with the library.

```sh
cargo run --example spanner-query
```

--------------------------------

### Publish Message Example

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/pubsub-raw.md

Example of how to publish a message using the Pub/Sub client. It demonstrates handling both successful responses and errors, including retrieving RPC status and error messages.

```rust
match client.publish(&request) {
    Ok(response) => println!("Published: {:?}", response.get_message_ids()),
    Err(e) => {
        // e.get_status() returns RPC status code
        // e.message() returns error message
        eprintln!("Publish failed: {}", e);
    }
}
```

--------------------------------

### Run Bigtable Query Example

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/googleapis-raw/README.md

Execute the Bigtable query example provided with the library.

```sh
cargo run --example bigtable-query
```

--------------------------------

### Start Spanner Emulator

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/configuration.md

Use the gcloud command to start the Spanner emulator on a specified host and port.

```bash
# Start emulator
gcloud emulators spanner start --host-port=localhost:9010
```

--------------------------------

### Install protobuf-codegen Cargo Plugin

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/googleapis-raw/README.md

Installs the protobuf-codegen cargo plugin, which is required for generating Rust bindings from .proto files. Ensure the protoc-gen-rust binary is in your PATH.

```sh
cargo install protobuf-codegen
```

--------------------------------

### Instance Configuration Example

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/bigtable-raw.md

Illustrates the structure of an Instance configuration, including its name, labels, and associated clusters. This is used when creating or modifying Bigtable instances.

```rust
Instance {
    name: "projects/{project}/instances/{instance}",
    labels: HashMap<String, String>,
    clusters: HashMap<String, Cluster>,
    type_: PRODUCTION | DEVELOPMENT,
}

Cluster {
    name: "projects/{project}/instances/{instance}/clusters/{cluster}",
    location: String,  // e.g., "us-central1-a"
    serve_nodes: i32,  // Number of nodes (ignored if autoscaling enabled)
    node_count: i32,   // Read-only current count
    autoscaling_config: AutoscalingConfig,
}

```

--------------------------------

### Begin Transaction

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/spanner-raw.md

Starts a new transaction within a session. Use ReadOnly for queries or ReadWrite for mutations.

```rust
pub fn begin_transaction(&self, req: &BeginTransactionRequest) -> ::grpcio::Result<Transaction>
```

--------------------------------

### Create Topic Example

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/pubsub-raw.md

Demonstrates how to create a new topic or retrieve an existing one. Ensure the topic name follows the `projects/{project}/topics/{topic}` format. Labels can be added for organization.

```rust
let mut topic = Topic::new();
topic.set_name("projects/my-project/topics/my-topic".to_string());
let mut labels = HashMap::new();
labels.insert("env".to_string(), "prod".to_string());
topic.set_labels(labels);
let created = client.create_topic(&topic)?;
```

--------------------------------

### Run Docker Container

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/docker/README.md

Starts the Docker container and provides a bash shell inside it. The project repository is mounted into the image.

```bash
docker-compose run rust /bin/bash
```

--------------------------------

### Build Docker Image

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/docker/README.md

Builds the Docker image for the Rust environment. Ensure Docker and docker-compose are installed.

```bash
docker-compose build rust
```

--------------------------------

### Publish Messages Example

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/pubsub-raw.md

Shows how to publish messages to a specified topic. Each message can include binary data, attributes, and an optional ordering key. The response contains server-assigned message IDs.

```rust
let mut request = PublishRequest::new();
request.set_topic("projects/my-project/topics/my-topic".to_string());

let mut msg = PubsubMessage::new();
msg.set_data("Hello, Pub/Sub!".as_bytes().to_vec());
let mut attrs = HashMap::new();
attrs.insert("source".to_string(), "example".to_string());
msg.set_attributes(attrs);

request.set_messages(vec![msg].into());
let response = client.publish(&request)?;
println!("Sent message: {}", response.get_message_ids()[0]);
```

--------------------------------

### Example Spanner Client Error Handling

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/spanner-client.md

Demonstrates how to handle potential errors when creating a new Spanner client. Errors can be printed or propagated.

```rust
use google_cloud_rust::spanner;

match spanner::Client::new(database) {
    Ok(client) => println!("Connected"),
    Err(e) => {
        // e is google_cloud_rust::Error
        eprintln!("Connection failed: {}", e);
        // Can be passed up or converted
    }
}
```

--------------------------------

### generate_initial_change_stream_partitions

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/bigtable-raw.md

Gets initial partitions for reading a change stream, which tracks mutations over time. This is the first step in consuming change stream data.

```APIDOC
## generate_initial_change_stream_partitions

### Description
Gets initial partitions for reading a change stream (tracks mutations over time).

### Method
`pub fn generate_initial_change_stream_partitions(&self, req: &GenerateInitialChangeStreamPartitionsRequest) -> ::grpcio::Result<ClientSStreamReceiver<GenerateInitialChangeStreamPartitionsResponse>>`

### Parameters
#### Request Body
- **table_name** (String) - Required - Table resource name

### Response
#### Success Response
- Stream of partition tokens for `read_change_stream`
```

--------------------------------

### Example Module Declaration in Rust

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/googleapis-raw/README.md

An example of how to declare public crate modules in Rust, which may be necessary after generating bindings. This snippet shows how to import specific modules and types, including those from nested or aliased paths.

```rust
pub(crate) use crate::{
    empty,
    iam::v1::{iam_policy, policy},
    longrunning::operations,
};
```

--------------------------------

### Example Commit Message Format

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/CONTRIBUTING.md

Follows Angular commit guidelines with type, subject, body, and footer for clear commit history. Use imperative mood and no trailing periods.

```git
feat: give the developers a delicious cookie

Properly formatted commit messages provide understandable history and
documentation. This patch will provide a delicious cookie when all tests have
passed and the commit message is properly formatted.

BREAKING CHANGE: This patch requires developer to lower expectations about
    what "delicious" and "cookie" may mean. Some sadness may result.

Closes #3.14, #9.75
```

--------------------------------

### Set Custom Metadata with CallOption

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/spanner-raw.md

Use `CallOption` to add custom headers to your gRPC requests. This example demonstrates setting a custom 'x-custom-header'. Ensure you have the necessary imports for `CallOption` and `MetadataBuilder`.

```rust
use grpcio::{CallOption, MetadataBuilder};

let mut meta = MetadataBuilder::new();
meta.add_str("x-custom-header", "value")?;
let opt = CallOption::default().headers(meta.build());
client.execute_sql_opt(&req, opt)?;
```

--------------------------------

### Exponential Backoff Usage Example

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/errors.md

Demonstrates how to use the exponential_backoff function within a retry loop. It retries an operation until successful or max retries are reached, sleeping between attempts.

```rust
// Usage
for attempt in 0..max_retries {
    match operation() {
        Ok(result) => return Ok(result),
        Err(_) => {
            let backoff = exponential_backoff(attempt, 30000);  // Max 30 sec
            std::thread::sleep(backoff);
        }
    }
}
```

--------------------------------

### Get Google Default Credentials

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/configuration.md

Obtain credentials using Google's default mechanism. This searches environment variables, GCP metadata, and gcloud defaults.

```rust
let creds = ChannelCredentials::google_default_credentials()?;

```

--------------------------------

### gRPC Initialization Pattern

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/README.md

Demonstrates the standard steps for initializing a gRPC client for Google Cloud services.

```rust
# Create an environment: EnvBuilder::new().build()
# Get credentials: ChannelCredentials::google_default_credentials()? 
# Build a channel with message size limits and credentials
# Instantiate service client from the channel
# Configure gRPC metadata with required headers (e.g., google-cloud-resource-prefix)
```

--------------------------------

### Generate and Open Documentation

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/googleapis-raw/README.md

Run this command to generate Rust documentation for the project and open it in your browser.

```sh
cargo doc --open
```

--------------------------------

### GetOperation

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/endpoints.md

Retrieves the status of a long-running operation. Use this method to poll for the status of an operation that has already been started.

```APIDOC
## GetOperation

### Description
Retrieves the status of a long-running operation. Use this method to poll for the status of an operation that has already been started.

### Method
Unary

### Request
GetOperationRequest

### Response
Operation
```

--------------------------------

### Transaction Management Methods

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/spanner-raw.md

Methods for managing transactions in Spanner, including starting, committing, and rolling back.

```APIDOC
## begin_transaction

### Description
Starts a new transaction within a session.

### Method
`begin_transaction`

### Parameters
#### Request
- `session` (String) - Required - Session resource name
- `options` (TransactionOptions) - Required - Transaction type:
  - `ReadOnly` — For queries only
  - `ReadWrite` — For queries and mutations

### Response
#### Success Response
- `Transaction` object containing `id` (Vec<u8>) - Transaction identifier (opaque)

### Types
```rust
TransactionOptions::ReadOnly {
    strong: bool,  // true = linearizable, false = staleness_bound
    staleness_bound: Duration,  // For weak reads
    read_timestamp: Timestamp,  // Or specific timestamp
}

TransactionOptions::ReadWrite {}
```
```

```APIDOC
## commit

### Description
Commits a transaction with mutations.

### Method
`commit`

### Parameters
#### Request
- `session` (String) - Required - Session resource name
- `transaction_id` (Vec<u8>) - Required - Transaction ID from `begin_transaction`
- `mutations` (Vec<Mutation>) - Required - Changes to apply:
  - `InsertRow` — Add new row
  - `UpdateRow` — Modify existing row
  - `InsertOrUpdateRow` — Insert or update
  - `DeleteRow` — Delete row
  - `DeleteRange` — Delete key range

### Response
#### Success Response
- `CommitResponse` object containing `commit_timestamp` (Timestamp) - Server timestamp when committed
```

```APIDOC
## rollback

### Description
Aborts a transaction without applying mutations.

### Method
`rollback`

### Parameters
#### Request
- `session` (String) - Required - Session resource name
- `transaction_id` (Vec<u8>) - Required - Transaction to abort

### Response
#### Success Response
- `Empty` - Success indicator
```

--------------------------------

### Spanner Client Initialization and Error Handling

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/spanner-client.md

Demonstrates how to initialize the Spanner client and handle potential connection errors.

```APIDOC
## Spanner Client Initialization and Error Handling

### Description
This section shows how to create a new Spanner client instance and handle errors that may occur during initialization.

### Method Signature
`pub fn new(database: &str) -> Result<Client>`

### Parameters
- **database** (`&str`) - Required - The name of the Spanner database to connect to.

### Response
- **Success Response** (`Result<Client>`)
  - Returns a `Client` instance on successful connection.
- **Error Response** (`Result<Client>`)
  - Returns a `crate::Error` if the connection fails.

### Example Error Handling
```rust
use google_cloud_rust::spanner;

match spanner::Client::new(database) {
    Ok(client) => println!("Connected"),
    Err(e) => {
        // e is google_cloud_rust::Error
        eprintln!("Connection failed: {}", e);
    }
}
```
```

--------------------------------

### KeyRange Struct

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/types.md

Defines a range of keys for selecting rows, with options for inclusive or exclusive start and end points.

```rust
pub struct KeyRange {
    pub start_closed: Option<ListValue>,
    pub start_open: Option<ListValue>,
    pub end_closed: Option<ListValue>,
    pub end_open: Option<ListValue>,
}
```

--------------------------------

### Get Session

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/spanner-raw.md

Retrieves an existing Spanner session by its unique resource name. Returns the session details if found.

```rust
pub fn get_session(&self, req: &GetSessionRequest) -> ::grpcio::Result<Session>
```

--------------------------------

### Publisher Client Constructor

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/pubsub-raw.md

Initializes a new PublisherClient with a gRPC channel.

```APIDOC
## Publisher Client Constructor

### Description
Initializes a new PublisherClient with a gRPC channel.

### Method
`new`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
let channel = ::grpcio::Channel::new_plain("localhost", 50051, ::grpcio::ChannelBuilder::new());
let client = PublisherClient::new(channel);
```

### Response
#### Success Response
`PublisherClient` instance

#### Response Example
None
```

--------------------------------

### Check SDK Configuration

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/googleapis-raw/README.md

Verify the Google Cloud SDK configuration by running this command.

```sh
gcloud info
```

--------------------------------

### Client::new

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/spanner-client.md

Creates a new Spanner client with automatic session initialization. It connects to spanner.googleapis.com:443, loads default credentials, and creates a session.

```APIDOC
## Client::new

### Description
Creates a new Spanner client with automatic session initialization. It connects to spanner.googleapis.com:443, loads default credentials, and creates a session.

### Method
```rust
pub fn new(database: &str) -> crate::Result<Client>
```

### Parameters
#### Path Parameters
- **database** (`&str`) - Required - Full database resource name: `projects/{projectId}/instances/{instanceId}/databases/{databaseName}`

### Returns
- **Client** (`Result<Client>`) - Newly initialized Spanner client on success

### Throws
- **Error** (`grpcio::Error`) - On invalid credentials, gRPC connection failure, session creation timeout or failure, or invalid metadata header construction.

### Example Usage
```rust
use google_cloud_rust::spanner;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let database = "projects/my-project/instances/my-instance/databases/my-database";
    let client = spanner::Client::new(database)?;
    
    // Client is ready for queries and transactions
    // Access session: client.session
    // Access database: client.database
    
    Ok(())
}
```
```

--------------------------------

### Spanner Query Timeout Handling

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/errors.md

Manages `DEADLINE_EXCEEDED` errors by setting a timeout on `CallOption` or optimizing query complexity. This example sets a 60-second timeout.

```rust
let opt = CallOption::default().timeout(Duration::from_secs(60));
client.execute_sql_opt(&request, opt)?;
```

--------------------------------

### Configure Default Compression Algorithm and Level

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/configuration.md

Set the default compression algorithm (e.g., GZIP) and compression level for gRPC channels. Use GZIP for large result sets and disable for small, frequent requests.

```rust
use grpcio::CompressionAlgorithm;

let channel = ChannelBuilder::new(env)
    .default_compression_algorithm(CompressionAlgorithm::GRPC_COMPRESS_GZIP)
    .default_compression_level(grpcio::CompressionLevel::new(6))
    .connect(endpoint);
```

--------------------------------

### Configure Pub/Sub Application Environment Variables

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/configuration.md

Set PUBSUB_TOPIC and PUBSUB_SUBSCRIPTION environment variables to specify the target Pub/Sub topic and subscription.

```bash
# Pub/Sub
export PUBSUB_TOPIC="projects/my-project/topics/my-topic"
export PUBSUB_SUBSCRIPTION="projects/my-project/subscriptions/my-sub"
```

--------------------------------

### Initialize High-Level Spanner Client

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/spanner-client.md

Creates a new Spanner client instance. Ensure you have valid Google credentials and a correct database resource name. The client automatically initializes a session for use.

```rust
use google_cloud_rust::spanner;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let database = "projects/my-project/instances/my-instance/databases/my-database";
    let client = spanner::Client::new(database)?;
    
    // Client is ready for queries and transactions
    // Access session: client.session
    // Access database: client.database
    
    Ok(())
}
```

--------------------------------

### QueryOptions Structure

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/types.md

Provides hints for query optimization, such as the optimizer version and statistics package to use.

```rust
pub struct QueryOptions {
    pub optimizer_version: String,
    pub optimizer_statistics_package: String,
}
```

--------------------------------

### Connect to Pub/Sub Emulator in Rust

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/configuration.md

Establish a connection to the Pub/Sub emulator using ChannelBuilder and disable authentication.

```rust
# In code
let channel = ChannelBuilder::new(env)
    .connect("localhost:8085");
let creds = ChannelCredentials::new();  // No auth
```

--------------------------------

### Configure Bigtable Channel for Bulk Operations

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/bigtable-raw.md

Use this snippet to set larger message size limits for Bigtable channels, suitable for bulk operations. Ensure you have the necessary credentials and environment setup.

```rust
let channel = ChannelBuilder::new(env)
    .max_send_message_len(1 << 28)      // 256 MB
    .max_receive_message_len(1 << 28)   // 256 MB
    .set_credentials(creds)
    .connect("bigtable.googleapis.com:443");
```

--------------------------------

### Configure gRPC Environment with EnvBuilder Options

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/configuration.md

Configure the gRPC environment using EnvBuilder, specifying completion queue threads and a custom name resolution target.

```rust
let env = Arc::new(
    EnvBuilder::new()
        .cq_count(4)                    // Completion queue threads
        .name_resolution_target(target) // Custom resolver
        .build()
);

```

--------------------------------

### Bigtable RowFilter Expression Example

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/bigtable-raw.md

Demonstrates a RowFilter expression combining column qualifier matching and a maximum number of cells per row. Use this to define complex server-side filtering logic for read operations.

```rust
RowFilter {
    chain: [
        { column_qualifier_regex_match: "^v\\d+$" },     // Match column names
        { max_num_cells: 5 }                              // Limit cells per row
    ],
    interleave: [
        { cells_per_row_offset_filter: 2 },
        { cells_per_row_limit_filter: 3 }
    ],
}
```

--------------------------------

### Configure Connection Lifecycle Options

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/configuration.md

Set maximum idle time, maximum connection age, and grace period before forcing a connection close.

```rust
.option("grpc.max_connection_idle_ms".to_string(), "300000".to_string())    // Close after 5 min idle
.option("grpc.max_connection_age_ms".to_string(), "600000".to_string())     // Recycle after 10 min
.option("grpc.max_connection_age_grace_ms".to_string(), "30000".to_string()) // Grace period before forcing close
```

--------------------------------

### Handle Bigtable Read Rows Errors

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/bigtable-raw.md

This example demonstrates how to handle potential errors when reading rows from Bigtable. It iterates through responses, processing successful chunks and logging any errors encountered during the read operation or request failure.

```rust
match client.read_rows(&request) {
    Ok(receiver) => {
        for response in receiver {
            match response {
                Ok(chunk) => { /* process chunk */ }
                Err(e) => eprintln!("Read error: {}", e),
            }
        }
    }
    Err(e) => eprintln!("Request failed: {}", e),
}
```

--------------------------------

### Enable Services with Cargo Features

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/README.md

Configure Cargo.toml to enable specific services in the google-cloud-rust-raw crate using features.

```toml
[dependencies]
google-cloud-rust-raw = { version = "0.16.1", features = ["spanner", "bigtable", "pubsub"] }
```

--------------------------------

### Login to Google Cloud

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/googleapis-raw/README.md

Authenticate your Google Cloud account using this command.

```sh
gcloud auth login
```

--------------------------------

### Create gRPC Channel with Google Default Credentials

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/configuration.md

Use this pattern to create a gRPC channel with Google Cloud credentials. It configures environment, loads credentials, and sets message size limits.

```rust
use grpcio::{Channel, ChannelBuilder, ChannelCredentials, EnvBuilder};
use std::sync::Arc;

fn create_channel(endpoint: &str) -> grpcio::Result<Channel> {
    // 1. Create environment
    let env = Arc::new(EnvBuilder::new().build());
    
    // 2. Load Google Cloud credentials
    let creds = ChannelCredentials::google_default_credentials()?;
    
    // 3. Build channel with configuration
    let channel = ChannelBuilder::new(Arc::clone(&env))
        .max_send_message_len(100 << 20)      // 100 MB
        .max_receive_message_len(100 << 20)   // 100 MB
        .set_credentials(creds)
        .connect(endpoint);
    
    Ok(channel)
}
```

--------------------------------

### Contextualizing Spanner Database Creation Errors

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/errors.md

Demonstrates how to wrap lower-level Spanner errors with more descriptive, context-specific `std::io::Error` types. This improves the clarity of error messages for common issues like database already existing or permission denied during creation.

```rust
fn create_database(instance: &str, db_name: &str) -> Result<(), Box<dyn std::error::Error>> {
    let admin_client = DatabaseAdminClient::new(channel.clone());
    let mut request = CreateDatabaseRequest::new();
    request.set_parent(instance.to_string());
    request.set_create_statement(format!("CREATE DATABASE `{}`", db_name));
    
    // Wrap lower-level errors with context
    admin_client.create_database(&request)
        .map_err(|e| {
            match e.get_status().code() {
                6 => Box::new(
                    std::io::Error::new(
                        std::io::ErrorKind::AlreadyExists,
                        format!("Database {} already exists", db_name)
                    )
                ) as Box<dyn std::error::Error>,
                7 => Box::new(
                    std::io::Error::new(
                        std::io::ErrorKind::PermissionDenied,
                        "Service account lacks spanner.admin role"
                    )
                ) as Box<dyn std::error::Error>,
                _ => Box::new(e) as Box<dyn std::error::Error>,
            }
        })?;
    
    Ok(())
}
```

--------------------------------

### Batch Create Sessions

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/spanner-raw.md

Efficiently creates multiple sessions in a single request, which is more performant than individual calls. Requires a database name, a session template, and the desired number of sessions.

```rust
pub fn batch_create_sessions(&self, req: &BatchCreateSessionsRequest) -> ::grpcio::Result<BatchCreateSessionsResponse>
```

--------------------------------

### CreateBackup

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/endpoints.md

Creates a backup of a BigTable table. It supports unary calls and returns OK, INVALID_ARGUMENT, or PERMISSION_DENIED status codes.

```APIDOC
## CreateBackup

### Description
Creates a backup of a BigTable table.

### Method
Unary

### Request
CreateBackupRequest

### Response
Operation

### Status Codes
OK, INVALID_ARGUMENT, PERMISSION_DENIED
```

--------------------------------

### Configure Spanner Application Environment Variables

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/configuration.md

Set SPANNER_DATABASE and SPANNER_INSTANCE environment variables to specify the target Spanner database and instance.

```bash
# Spanner
export SPANNER_DATABASE="projects/my-project/instances/my-instance/databases/my-db"
export SPANNER_INSTANCE="projects/my-project/instances/my-instance"
```

--------------------------------

### InstanceAdminClient Structure

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/spanner-raw.md

Defines the structure for the InstanceAdminClient, used for managing Cloud Spanner instances.

```rust
pub struct InstanceAdminClient { pub client: ::grpcio::Client }
```

--------------------------------

### Basic Spanner Client Connection Error Handling

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/errors.md

Demonstrates how to handle potential errors when establishing a connection to a Spanner database using a basic match statement.

```rust
use google_cloud_rust::spanner;

match spanner::Client::new(database) {
    Ok(client) => {
        println!("Connected to Spanner");
        // Use client
    }
    Err(e) => {
        eprintln!("Failed to connect: {}", e);
        std::process::exit(1);
    }
}
```

--------------------------------

### Configure Rust Client for Low Latency

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/configuration.md

Tune the Rust client for low latency by enabling GZIP compression and reducing the size of the header block.

```rust
let channel = ChannelBuilder::new(env)
    .default_compression_algorithm(CompressionAlgorithm::GRPC_COMPRESS_GZIP)  // Reduce network
    .option("grpc.max_send_header_block_length".to_string(), "8192".to_string())  // Smaller headers
    .connect(endpoint);
```

--------------------------------

### Integration with Raw API

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/spanner-client.md

Illustrates how to use the raw Spanner API client for operations not covered by the high-level client.

```APIDOC
## Integration with Raw API

### Description
This section details how to leverage the `google-cloud-rust-raw` crate for advanced Spanner operations that might not be exposed through the high-level client interface.

### Usage
To perform advanced operations, you can directly use types and clients from the `google-cloud-rust-raw` crate.

### Example
```rust
use google_cloud_rust_raw::spanner::v1::spanner::ExecuteSqlRequest;

// Assuming 'client' is an instance of google_cloud_rust::spanner::Client
let mut request = ExecuteSqlRequest::new();
request.set_session(client.session.get_name().to_string());
// Configure and execute the request using client.client.execute_sql(request, ...)
```
```

--------------------------------

### PartitionOptions Struct

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/types.md

Options for partitioning operations, such as desired partition size and maximum number of partitions.

```rust
pub struct PartitionOptions {
    pub partition_size_bytes: i64,
    pub max_partitions: i64,
}
```

--------------------------------

### InstanceAdminClient Methods

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/spanner-raw.md

The InstanceAdminClient is responsible for managing Cloud Spanner instances, including their creation, deletion, retrieval, listing, and updates.

```APIDOC
## InstanceAdminClient

Manages Cloud Spanner instances (compute and storage clusters).

### Key Methods:

- `create_instance(request)` — Create new instance
- `delete_instance(request)` — Delete instance
- `get_instance(request)` — Get instance metadata
- `list_instances(request)` — List instances in project
- `update_instance(request)` — Modify instance configuration
```

--------------------------------

### Enable gRPC Debug Logging via Environment Variables

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/errors.md

Sets environment variables to enable detailed debugging and tracing for gRPC communications. Use `GRPC_VERBOSITY=debug` for general debugging and `GRPC_TRACE` for specific component tracing.

```bash
# Environment variable to enable gRPC tracing
export GRPC_VERBOSITY=debug
export GRPC_TRACE=all

# Or for specific components
export GRPC_TRACE=http,channel,connectivity_state
```

--------------------------------

### Pub/Sub Topic Creation Error Handling

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/errors.md

Demonstrates handling `ALREADY_EXISTS` errors when creating a Pub/Sub topic. The code checks for the error and prints a message if the topic already exists.

```rust
match client.create_topic(&topic) {
    Ok(t) => println!("Created topic"),
    Err(e) if e.get_status().code() == 6 => println!("Topic exists"),
    Err(e) => return Err(e),
}

```

--------------------------------

### Configure ChannelBuilder Options

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/configuration.md

Set various options for a ChannelBuilder, including message size limits, credentials, keep-alive settings, flow control, and custom gRPC options.

```rust
let channel = ChannelBuilder::new(env)
    // Message size limits
    .max_send_message_len(limit_bytes)
    .max_receive_message_len(limit_bytes)
    
    // Credentials
    .set_credentials(creds)
    
    // Keep-alive and timeouts
    .keepalive_time(Duration::from_secs(30))
    .keepalive_timeout(Duration::from_secs(10))
    .keepalive_permit_without_calls(false)
    
    // Flow control
    .default_compression_algorithm(compression_algorithm)
    .default_compression_level(compression_level)
    
    // Channel arguments
    .option("grpc.max_connection_idle_ms".to_string(), "300000".to_string())
    .option("grpc.max_connection_age_ms".to_string(), "600000".to_string())
    
    // Connection
    .connect(endpoint);
```

--------------------------------

### Create Pub/Sub Subscription in Rust

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/pubsub-raw.md

Use this snippet to create a new subscription to a Pub/Sub topic. Configure push or pull delivery, acknowledgment deadlines, message retention, and filtering.

```rust
let mut subscription = Subscription::new();
subscription.set_name("projects/my-project/subscriptions/my-sub".to_string());
subscription.set_topic("projects/my-project/topics/my-topic".to_string());
subscription.set_ack_deadline_seconds(30);

let mut push_config = PushConfig::new();
push_config.set_push_endpoint("https://my-app.com/webhook".to_string());
subscription.set_push_config(push_config);

let created = client.create_subscription(&subscription)?;
```

--------------------------------

### Message Size Configuration for gRPC

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/README.md

Shows typical configurations for send and receive message sizes, including a specific setting for BigTable bulk operations.

```rust
# Standard configuration in examples:
# - Send: max_send_message_len(100 << 20) (100 MB)
# - Receive: max_receive_message_len(100 << 20) (100 MB)
# - BigTable: (1 << 28) (256 MB) for bulk operations
```

--------------------------------

### Connect to Spanner with Error Handling

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/spanner-client.md

Connects to a Cloud Spanner database, retrieving the database path from an environment variable or using a default. Includes basic error handling for connection failures.

```rust
use google_cloud_rust::spanner;
use google_cloud_rust::Result;

fn connect_to_database() -> Result<spanner::Client> {
    let db_path = std::env::var("SPANNER_DATABASE")
        .unwrap_or_else(|_| "projects/default/instances/default/databases/default".to_string());
    
    match spanner::Client::new(&db_path) {
        Ok(client) => {
            eprintln!("Connected to Spanner: {}", db_path);
            Ok(client)
        }
        Err(e) => {
            eprintln!("Failed to connect to Spanner: {}", e);
            Err(e)
        }
    }
}
```

--------------------------------

### BeginTransactionRequest Struct

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/types.md

Request to begin a new transaction, specifying the session and optional transaction options.

```rust
pub struct BeginTransactionRequest {
    pub session: String,
    pub options: Option<TransactionOptions>,
}
```

--------------------------------

### PushConfig Structure

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/types.md

Configures HTTP(S) push delivery for a subscription, specifying the push endpoint, attributes, and optional OIDC token for authentication.

```rust
pub struct PushConfig {
    pub push_endpoint: String,
    pub attributes: HashMap<String, String>,
    pub oidc_token: Option<OidcToken>,
    pub no_wrapper: bool,
}

pub struct OidcToken {
    pub service_account_email: String,
    pub audience: String,
}

```

--------------------------------

### ListInstances

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/endpoints.md

Lists all BigTable instances within the specified project.

```APIDOC
## ListInstances

### Description
Lists all BigTable instances within the specified project.

### Method
Unary

### Request
ListInstancesRequest

### Response
ListInstancesResponse

### Status Codes
OK, INVALID_ARGUMENT, PERMISSION_DENIED
```

--------------------------------

### Sample Row Keys for Table Splits

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/bigtable-raw.md

Retrieves representative row keys that divide the table into roughly equal-sized splits, useful for parallel scanning.

```rust
pub fn sample_row_keys(&self, req: &SampleRowKeysRequest) -> ::grpcio::Result<ClientSStreamReceiver<SampleRowKeysResponse>>
```

--------------------------------

### Common gRPC Metadata Headers

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/README.md

Lists essential metadata headers required by Google Cloud services for client requests.

```rust
# Common headers required by Google Cloud services:
# - google-cloud-resource-prefix: Resource name (database, topic, etc.)
# - x-goog-api-client: Client identifier, e.g., "googleapis-rs"
```

--------------------------------

### Execute SQL Query with Streaming Results

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/spanner-raw.md

Employ `execute_streaming_sql` for large result sets where data is streamed in chunks. The server streams back `PartialResultSet` as they become available.

```rust
pub fn execute_streaming_sql(&self, req: &ExecuteSqlRequest) -> ::grpcio::Result<ClientSStreamReceiver<PartialResultSet>>
```

```rust
let receiver = client.execute_streaming_sql(&req)?;
for partial_result in receiver {
    let chunk = partial_result?;
    // Process chunk.values
}
```

--------------------------------

### Configure BigTable Application Environment Variables

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/configuration.md

Set BIGTABLE_INSTANCE and BIGTABLE_TABLE environment variables to specify the target BigTable instance and table.

```bash
# BigTable
export BIGTABLE_INSTANCE="my-instance"
export BIGTABLE_TABLE="my-table"
```

--------------------------------

### Connect to Spanner Emulator in Rust

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/configuration.md

Establish a connection to the Spanner emulator using ChannelBuilder and disable TLS and authentication.

```rust
// In code
let channel = ChannelBuilder::new(env)
    .connect("localhost:9010");  // No TLS

// Disable authentication
let creds = ChannelCredentials::new();  // Empty credentials
```

--------------------------------

### PartitionQueryRequest Struct

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/types.md

Request to partition a query for parallel execution, specifying session, transaction, SQL, and partitioning options.

```rust
pub struct PartitionQueryRequest {
    pub session: String,
    pub transaction: Option<TransactionSelector>,
    pub sql: String,
    pub params: HashMap<String, Value>,
    pub param_types: HashMap<String, Type>,
    pub partition_options: Option<PartitionOptions>,
}
```

--------------------------------

### QueryOptions

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/types.md

Defines query optimization hints, such as the optimizer version and statistics package to use.

```APIDOC
## QueryOptions

### Description
Query optimization hints.

### Struct
`spanner::QueryOptions`

### Fields
- **optimizer_version** (String) - Optional - The optimizer version to use.
- **optimizer_statistics_package** (String) - Optional - The statistics package to use.
```

--------------------------------

### Set Metadata Headers for RPC Calls

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/configuration.md

Configure metadata headers, such as resource prefixes and client identifiers, for RPC calls. Use this to specify target resources or client information.

```rust
use grpcio::{CallOption, MetadataBuilder};

let mut meta = MetadataBuilder::new();
meta.add_str("google-cloud-resource-prefix", "projects/my-project/instances/my-instance/databases/my-db")?;
meta.add_str("x-goog-api-client", "googleapis-rs")?;
let opt = CallOption::default().headers(meta.build());

// Use in RPC call
client.execute_sql_opt(&request, opt)?;

```

--------------------------------

### Configure Rust Client for Low Resource Usage

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/configuration.md

Tune the Rust client for low resource usage by reducing the number of worker threads, decreasing message batch sizes, and limiting concurrent streams.

```rust
let env = Arc::new(EnvBuilder::new().cq_count(2).build());

let channel = ChannelBuilder::new(env)
    .max_send_message_len(10 << 20)     // Smaller batches
    .max_receive_message_len(10 << 20)
    .option("grpc.max_concurrent_streams".to_string(), "10".to_string())
    .connect(endpoint);
```

--------------------------------

### Per-Thread Channel Creation in Rust

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/configuration.md

For high-concurrency scenarios, create a separate gRPC channel for each thread to avoid contention and ensure optimal performance.

```rust
std::thread::spawn(move || {
    let channel = create_channel("spanner.googleapis.com:443")?;
    let client = SpannerClient::new(channel);
    // Use client in this thread
});
```

--------------------------------

### Partition Query

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/spanner-raw.md

Splits a query into partitions for parallel execution. Each partition can be read independently using its token.

```rust
pub fn partition_query(&self, req: &PartitionQueryRequest) -> ::grpcio::Result<PartitionResponse>
```

--------------------------------

### Low-Level Client Access

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/spanner-client.md

Explains how to access the underlying components of the Spanner client for advanced operations.

```APIDOC
## Low-Level Client Access

### Description
The `Client` struct provides public access to its internal fields, allowing for direct manipulation or inspection of the underlying Spanner client components.

### Fields
- `client` (`SpannerClient`)
  - Direct access to the underlying gRPC Spanner client for manual operations.
- `session` (`Session`)
  - The current session object used by the client.
- `database` (`&str`)
  - The name of the database the client is connected to.

### Example Usage
```rust
use google_cloud_rust::spanner;

let client = spanner::Client::new(db)?;
// Direct gRPC usage
// client.client.execute_sql(...)?;
```
```

--------------------------------

### list_topics

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/pubsub-raw.md

Lists topics within a specified project, with support for pagination.

```APIDOC
## list_topics

### Description
Lists topics within a specified project, with support for pagination.

### Method
`list_topics`

### Endpoint
N/A (gRPC method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **request** (`ListTopicsRequest`) - Required
  - `project` (String) - Required - Project resource name: `projects/{project}`
  - `page_size` (i32) - Optional - Max topics per page (0-100, default 10)
  - `page_token` (String) - Optional - Pagination token

### Request Example
```rust
let mut request = ListTopicsRequest::new();
request.set_project("projects/my-project".to_string());
request.set_page_size(50);
let response = client.list_topics(&request)?;
```

### Response
#### Success Response
- **ListTopicsResponse** (`ListTopicsResponse`)
  - `topics` (Vec<Topic>) - Topics on this page
  - `next_page_token` (String) - Token for next page, empty if last

#### Response Example
```json
{
  "topics": [
    {
      "name": "projects/my-project/topics/topic1"
    },
    {
      "name": "projects/my-project/topics/topic2"
    }
  ],
  "next_page_token": ""
}
```
```

--------------------------------

### Subscription Structure

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/types.md

Defines a Pub/Sub subscription, including its name, associated topic, push configuration, BigQuery/Cloud Storage configuration, acknowledgment deadline, and message ordering settings.

```rust
pub struct Subscription {
    pub name: String,
    pub topic: String,
    pub push_config: Option<PushConfig>,
    pub bigquery_config: Option<BigQuerySubscriptionConfig>,
    pub cloud_storage_config: Option<CloudStorageConfig>,
    pub ack_deadline_seconds: i32,
    pub retain_acked_messages: bool,
    pub message_retention_duration: Option<Duration>,
    pub labels: HashMap<String, String>,
    pub enable_message_ordering: bool,
    pub expiration_policy: Option<ExpirationPolicy>,
    pub filter: String,
    pub dead_letter_policy: Option<DeadLetterPolicy>,
}

```

--------------------------------

### Set Google Cloud Credentials

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/configuration.md

Export the GOOGLE_APPLICATION_CREDENTIALS environment variable to specify the path to your service account key file for authentication.

```bash
# Credentials
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
```

--------------------------------

### create_subscription

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/pubsub-raw.md

Creates a new subscription to a topic. You can configure it for push or pull delivery, set acknowledgment deadlines, message retention policies, and more.

```APIDOC
## create_subscription

### Description
Creates a new subscription to a topic.

### Method
```rust
pub fn create_subscription(&self, subscription: &Subscription) -> ::grpcio::Result<Subscription>
```

### Request
`Subscription`
- `name` (String) - Subscription resource name: `projects/{project}/subscriptions/{subscription}`
- `topic` (String) - Topic to subscribe to
- `push_config` (PushConfig, optional) - For push delivery
  - `push_endpoint` (String) - HTTP(S) endpoint URL
  - `attributes` (HashMap<String, String>) - Custom headers
  - `oidc_token` (OidcToken, optional) - OIDC authentication
- `pull_config` (PullConfig, default) - For pull delivery
  - `use_legacy_flow` (bool) - Legacy streaming pull
- `ack_deadline_seconds` (i32, optional, 10-600 sec, default 10) - Time to ack message
- `retain_acked_messages` (bool, default false) - Keep acked messages
- `message_retention_duration` (Duration) - How long to store messages
- `filter` (String, optional) - SQL expression to filter messages
- `dead_letter_policy` (DeadLetterPolicy, optional) - DLQ configuration
- `labels` (HashMap<String, String>) - Organization labels

### Response
`Subscription` - Created subscription

### Example
```rust
let mut subscription = Subscription::new();
subscription.set_name("projects/my-project/subscriptions/my-sub".to_string());
subscription.set_topic("projects/my-project/topics/my-topic".to_string());
subscription.set_ack_deadline_seconds(30);

let mut push_config = PushConfig::new();
push_config.set_push_endpoint("https://my-app.com/webhook".to_string());
subscription.set_push_config(push_config);

let created = client.create_subscription(&subscription)?;
```
```

--------------------------------

### List Sessions

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/api-reference/spanner-raw.md

Lists all sessions within a specified Spanner database. Supports pagination using `page_token` and `page_size` for efficient retrieval of large session sets.

```rust
pub fn list_sessions(&self, req: &ListSessionsRequest) -> ::grpcio::Result<ListSessionsResponse>
```

--------------------------------

### Pub/Sub Schema Management

Source: https://github.com/mozilla-services/google-cloud-rust/blob/master/_autodocs/endpoints.md

Methods for managing schemas in Google Cloud Pub/Sub.

```APIDOC
## CreateSchema

### Description
Creates a new schema.

### Method
Unary

### Request
CreateSchemaRequest

### Response
Schema

### Status Codes
OK, INVALID_ARGUMENT, ALREADY_EXISTS, PERMISSION_DENIED
```

```APIDOC
## GetSchema

### Description
Retrieves a schema by its name.

### Method
Unary

### Request
GetSchemaRequest

### Response
Schema

### Status Codes
OK, NOT_FOUND, PERMISSION_DENIED
```

```APIDOC
## ListSchemas

### Description
Lists all schemas in the project.

### Method
Unary

### Request
ListSchemasRequest

### Response
ListSchemasResponse

### Status Codes
OK, INVALID_ARGUMENT, PERMISSION_DENIED
```

```APIDOC
## DeleteSchema

### Description
Deletes a schema by its name.

### Method
Unary

### Request
DeleteSchemaRequest

### Response
Empty

### Status Codes
OK, NOT_FOUND, PERMISSION_DENIED
```

```APIDOC
## ValidateSchema

### Description
Validates a schema.

### Method
Unary

### Request
ValidateSchemaRequest

### Response
ValidateSchemaResponse

### Status Codes
OK, INVALID_ARGUMENT, PERMISSION_DENIED
```

```APIDOC
## ValidateMessage

### Description
Validates a message against a schema.

### Method
Unary

### Request
ValidateMessageRequest

### Response
ValidateMessageResponse

### Status Codes
OK, INVALID_ARGUMENT, PERMISSION_DENIED
```