# Test using the emulator

The [Google Cloud CLI](https://docs.cloud.google.com/sdk) 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.

> [!NOTE]
> **Note:** You can't use the emulator in the HBase shell.

## Install and run the emulator

The two most common ways to run the emulator are by using the
[gcloud CLI](https://docs.cloud.google.com/sdk/gcloud/reference/beta/emulators/bigtable) and [Docker](https://www.docker.com).
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](https://console.cloud.google.com/?cloudshell=true)


At the bottom of the Google Cloud console, a
[Cloud Shell](https://docs.cloud.google.com/shell/docs/how-cloud-shell-works)
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

1. Update your gcloud CLI installation to get the latest
   features:

       gcloud components update beta

2. 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.

   <br />

   By default, the emulator chooses `localhost:8086`. To bind the emulator to a
   specific host and port, use the optional `--host-port` flag, replacing
   <var translate="no">HOST</var> and <var translate="no">PORT</var>:

       gcloud beta emulators bigtable start --host-port=HOST:PORT

   The following is an example:

       gcloud beta emulators bigtable start --host-port=localhost:8086

   > [!NOTE]
   > **Note:** If you want to run multiple emulators, make sure that when you are starting the emulator, you specify the host and port explicitly.

3. Type Control-C to stop the emulator.

   <br />

### Docker

1. Make sure [Docker](https://www.docker.com/products/docker-desktop)
   is installed on your system and available on the system path.

2. 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](https://docs.docker.com/compose/).

## 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](https://docs.cloud.google.com/bigtable/docs/samples-python-hello).

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](https://github.com/googleapis/google-cloud-java/tree/main/java-bigtable/google-cloud-bigtable-emulator).

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

- [com.google.cloud.bigtable.emulator.core](https://docs.cloud.google.com/java/docs/reference/google-cloud-bigtable/latest/com.google.cloud.bigtable.emulator.core)
- [com.google.cloud.bigtable.emulator.v2](https://docs.cloud.google.com/java/docs/reference/google-cloud-bigtable/latest/com.google.cloud.bigtable.emulator.v2)

## Filters

The emulator supports all filters, except the [`Sink`](https://docs.cloud.google.com/bigtable/docs/using-filters#sink) limiting filter.

Issues related to the Bigtable emulator are tracked in the
[google-cloud-go](https://github.com/googleapis/google-cloud-go/labels/api%3A%20bigtable) GitHub repository, where you can file bug
reports and feature requests or comment on existing issues.