Test using the emulator

The Google Cloud CLI provides a local, in-memory emulator for Bigtable, which you can use to test your application. Because the emulator stores data only in memory, it won't persist data across runs. It is intended to help you use Bigtable for local development and testing, not for production deployments.

You can use the emulator with all Cloud Bigtable client libraries.

The emulator does not provide administrative APIs to create or manage instances and clusters. After the emulator starts up, you can connect to it using any project and instance name to create tables and read or write data. The emulator doesn't support a secure connection.

Install and run the emulator

The two most common ways to run the emulator are by using the gcloud CLI and Docker. Choose the way that is appropriate for your application development and test workflow.

Set up authentication

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

gcloud CLI

Update your gcloud CLI installation to get the latest features:
```
gcloud components update beta
```
Run the following command to start the emulator:
```
gcloud beta emulators bigtable start
```
If the emulator is not installed already, you will be prompted to download and install the binary for the emulator.

The emulator prints the host and port number where it is running.

By default, the emulator chooses localhost:8086. To bind the emulator to a specific host and port, use the optional --host-port flag, replacing HOST and PORT:
```
gcloud beta emulators bigtable start --host-port=HOST:PORT
```
The following is an example:
```
gcloud beta emulators bigtable start --host-port=localhost:8086
```
Note: If you want to run multiple emulators, make sure that when you are starting the emulator, you specify the host and port explicitly.
Type Control-C to stop the emulator.

Docker

Make sure Docker is installed on your system and available on the system path.

Start the emulator:

docker run -p 127.0.0.1:8086:8086 --rm -ti google/cloud-sdk gcloud beta emulators bigtable start --host-port=0.0.0.0:8086

This command runs the emulator and maps the ports in the container to the same ports on your local host.

You can also use the emulator as part of your existing Docker Compose configuration (.yaml) file. For more information about Docker Compose, see Docker Compose Overview.

Use the client libraries with the emulator

Set the BIGTABLE_EMULATOR_HOST environment variable to use the client libraries with the emulator:

Linux / macOS

  export BIGTABLE_EMULATOR_HOST=localhost:8086

Windows

  set BIGTABLE_EMULATOR_HOST=localhost:8086

When your application starts, the client library automatically checks for BIGTABLE_EMULATOR_HOST and connects to the emulator if it is running.

Once BIGTABLE_EMULATOR_HOST is set, you can test the emulator by following the hello world samples.

To stop the emulator, type Control-C, then unset BIGTABLE_EMULATOR_HOST with the following command:

    unset BIGTABLE_EMULATOR_HOST

Java wrapper for the emulator

The Java wrapper bundles the built-in Bigtable emulator and provides a Java interface to write tests.

For more information about using the Java wrapper, see the GitHub repository.

The following documentation provides more information about the emulator Java packages:

Filters

The emulator supports all filters, except the Sink limiting filter.

Issues related to the Bigtable emulator are tracked in the google-cloud-go GitHub repository, where you can file bug reports and feature requests or comment on existing issues.