README.md

# Gerrit Cloud Spanner refdb

This plugin provides an implementation of the Gerrit global refdb backed by
[Cloud Spanner](https://cloud.google.com/spanner).

Requirements for using this plugin are:

- Gerrit v3.6 or later
- Cloud spanner as a provisioned instance
- Optional, for testing: a locally hosted
[emulator](https://cloud.google.com/spanner/docs/emulator)

## Typical use case

A global refdb implementation is a requirement for a Gerrit multi-master
scenario in a multi-site setup to ensure refs are updated consistently across
multiple Gerrit primary sites.

Refer to the
[Gerrit multi-site plugin](https://gerrit.googlesource.com/plugins/multi-site/+/master/DESIGN.md)
for more details on the high level architecture.

## Use with Cloud Spanner emulator

The [in-memory Cloud Spanner emulator](https://cloud.google.com/spanner/docs/emulator)
can be used during development. There are several limitations of the emulator
that differ from the production service.

An easy way to run the emulator is to use gcloud CLI and Docker. Following the
install instructions [here](https://cloud.google.com/spanner/docs/emulator#install)
will provide a local instance that the plugin can access. The gcloud CLI
commands will be sent to the emulator instead of the production service. A test
spanner instance and database will need to be created.

```
gcloud spanner instances create test-instance --config=emulator-config --description="Test Instance" --nodes=1

gcloud spanner databases create global-refdb --instance=test-instance
```

There are several
[limitations](https://cloud.google.com/spanner/docs/emulator#limitations)
of the emulator which differ from the production service.

## Use with simulated multi-site setup

In order to easily set up and begin testing the @PLUGIN@ plugin, the
multi-site plugin's
[local environment setup](https://gerrit.googlesource.com/plugins/multi-site/+/refs/heads/master/setup_local_env/)
can be used.

This simulates a multi-site setup using two local gerrit instances. Build the
release.war to include @PLUGIN@ and follow the linked example setup.

## Configuration options

Configuration details can be found in the
[@PLUGIN@ config documentation](src/main/resources/Documentation/config.md).

When not used with the emulator, the plugin requires the path to credentials in
the config to authenticate with google. To create the key see the
[official documentation](https://cloud.google.com/iam/docs/keys-create-delete).