Idiomatic Ruby client libraries for Google Cloud Spanner APIs.

• Homepage
• Reference documentation

This repository includes client libraries for Google Cloud Spanner services.

Most directories each correspond to a client library RubyGem, including its code, tests, gemspec, and documentation. Some client libraries also include handwritten samples in the samples directory, and/or autogenerated samples in the snippets directory.

Most client libraries in this repository are automatically generated by the GAPIC Generator. A small number are written and maintained by hand. You can identify a generated client library by the presence of .OwlBot.yaml in the library directory. For the most part, do not try to edit generated libraries by hand, because changes will be overwritten by the code generator.

A few directories include support files, including:

• .github includes configuration for GitHub Actions and bots that help to maintain this repository.
• .kokoro includes configuration for internal Google processes that help to maintain this repository.
• .toys includes scripts for running CI, releases, and maintenance tasks.
• acceptance and integration include shared fixtures for acceptance tests.
• obsolete contains older libraries that are obsolete and no longer maintained.

Issues for client libraries hosted here can be filed in the issues tab. However, this is not an official support channel. If you have support questions, file a support request through the normal Google support channels, or post questions on a forum such as StackOverflow.

Pull requests are welcome. Please see the section below on contributing.

Some maintenance tasks can be run in the actions tab by authorized personnel.

These client library RubyGems each include classes and methods that can be used to make authenticated calls to specific Google APIs. Some libraries also include additional convenience code implementing common client-side workflows or best practices.

In general, you can expect to:

1. Activate access to the API by creating a project on the Google Cloud Console, enabling billing if necessary, and enabling the API.

2. Choose a library and install it, typically by adding it to your bundle. For example, here is how you might add a the Translation service client to your Gemfile:

   # Gemfile
   
   # ... previous libraries ...
   gem "google-cloud-spanner", "~> 3.2"

3. Instantiate a client object. This object represents an authenticated connection to the service. For example, here is how you might create a client for the spanner service:

   require "google/cloud/spanner"
   
   spanner_client = Google::Cloud::Spanner.new

   Depending on your environment and authentication needs, you might need to provide credentials to the client object.

4. Make API calls by invoking methods on the client. For example, here is how you might translate a phrase:

   instances = spanner.list_instances max: 10
   puts instances.first.name

To access a Google Cloud API, you will generally need to activate it in the cloud console. This typically involves three steps:

1. If you have not created a Google Cloud Project, do so. Point your browser to the Google Cloud Console, sign up if needed, and create or choose a project. Make note of the project number (which is numeric) or project ID (which is usually three or more words separated by hyphens). Many services will require you to pass that information in when calling an API.

2. For most services, you will need to provide billing information. If this is your first time using Google Cloud Platform, you may be eligible for a free trial.

3. Enable the API you want to use. Click the "APIs & Services" tab in the left navigation, then click the "Enable APIs and Services" button near the top. Search for the API you want by name, and click "Enable". A few APIs may be enabled automatically for you, but most APIs need to be enabled explicitly.

Once you have a project set up and have enabled an API, you are ready to begin using a client library to call the API.

Most API calls must be accompanied by authentication information proving that the caller has sufficient permissions to make the call. For an overview of authentication with Google, see https://cloud.google.com/docs/authentication.

These API client libraries provide several mechanisms for attaching credentials to API calls.

• If your application runs on an Google Cloud Platform hosting environment such as Google Compute Engine, Google Container Engine, Google App Engine, Google Cloud Run, or Google Cloud Functions, the environment will provide "ambient" credentials which client libraries will recognize and use automatically. You can generally configure these credentials in the hosting environment, for example per-VM in Google Compute Engine.

• You can also provide your own service account credentials by including a service account key file in your application's file system and setting the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path to that file. Client libraries will read this environment variable if it is set.

• Finally, you can override credentials in code by setting the credentials field in the client configuration. This can be set globally on the client class or provided when you construct a client object.

See https://cloud.google.com/docs/authentication/production for more information on these and other methods of providing credentials.

These libraries are currently supported on Ruby 2.6 through Ruby 3.1. Older versions of Ruby may still work, but are unsupported and not recommended.

In general, Google provides official support for Ruby versions that are actively supported by Ruby Core--that is, Ruby versions that are either in normal maintenance or in security maintenance, and not end of life. See https://www.ruby-lang.org/en/downloads/branches/ for details about the Ruby support schedule.

The libraries in this repository follow Semantic Versioning.

Libraries are released at one of two different support quality levels:

GA: Libraries defined at the GA (general availability) quality level, indicated by a gem version number greater than or equal to 1.0, are stable. The code surface will not change in backwards-incompatible ways unless absolutely necessary (e.g. because of critical security issues), or unless accompanying a semver-major version update (such as version 1.x to 2.x.) Issues and requests against GA libraries are addressed with the highest priority.

Preview: Libraries defined at a Preview quality level, indicated by a gem version number less than 1.0, are expected to be mostly stable and we're working towards their release candidate. However, these libraries may get backwards-incompatible updates from time to time. We will still address issues and requests with a high priority.

Note that the gem version is distinct from the service version. Some backend services have mulitple versions, for example versions v2 and v3 of the translation service. These are treated as separate services and will have separate versioned clients, e.g. the google-cloud-translate-v2 and google-cloud-translate-v3 gems. These gems will in turn have their own gem versions, tracking the development of the two services.

Contributions to this repository are welcome. However, please note that many of the clients in this repository are automatically generated. The Ruby files in those clients will have a comment to that effect near the top; changes to those files will not be accepted as they will simply be overwritten by the code generator. If in doubt, please open an issue and ask the maintainers. See the CONTRIBUTING document for more information on how to get started.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See Code of Conduct for more information.

This library is licensed under Apache 2.0. Full license text is available in LICENSE.

Please report bugs at the project on Github.

If you have questions about how to use the clients or APIs, ask on Stack Overflow.