https://github.com/cloudspannerecosystem/spool
A CLI tool to manage Cloud Spanner databases for testing.
https://github.com/cloudspannerecosystem/spool
Last synced: 5 months ago
JSON representation
A CLI tool to manage Cloud Spanner databases for testing.
- Host: GitHub
- URL: https://github.com/cloudspannerecosystem/spool
- Owner: cloudspannerecosystem
- License: mit
- Created: 2019-11-05T06:49:54.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2025-10-27T06:21:17.000Z (8 months ago)
- Last Synced: 2025-10-29T05:52:22.678Z (8 months ago)
- Language: Go
- Size: 441 KB
- Stars: 25
- Watchers: 4
- Forks: 6
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# spool
[](https://github.com/cloudspannerecosystem/spool/actions/workflows/build_and_test.yaml)
A CLI tool to manage [Cloud Spanner](https://cloud.google.com/spanner) databases for testing.
Please feel free to report issues and send pull requests, but note that this
application is not officially supported as part of the Cloud Spanner product.
## Motivation
When the development of spool started, the [Cloud Spanner
Emulator](https://cloud.google.com/spanner/docs/emulator) wasn't available yet.
When using Cloud Spanner instances for continuous integration tests, it is
inefficient to create a new test database on every run.
This tool lets you reuse test databases in CI tests.
## Installation
```shell
$ go get -u github.com/cloudspannerecosystem/spool/cmd/spool
```
## Setup
Spool requires a database for metadata to manage databases.
The following command sets up the database.
```shell
$ spool --project=${PROJECT} --instance=${INSTANCE} --database=${SPOOL_DATABASE} setup
```
## Usage
```shell
usage: spool [] [ ...]
A CLI tool to manage Cloud Spanner databases for testing.
Flags:
--help Show context-sensitive help (also try --help-long and --help-man).
-p, --project=PROJECT Set GCP project ID. (use $SPANNER_PROJECT_ID or $GOOGLE_CLOUD_PROJECT as default value)
-i, --instance=INSTANCE Set Cloud Spanner instance name. (use $SPANNER_INSTANCE_ID as default value)
-d, --database=DATABASE Set Cloud Spanner database name. (use $SPOOL_SPANNER_DATABASE_ID as default value)
-s, --schema=SCHEMA Set schema file path.
Commands:
help [...]
Show help.
setup
Setup the database for spool metadata.
create --db-name-prefix=DB-NAME-PREFIX []
Add new databases to the pool.
get
Get a idle database from the pool.
get-or-create --db-name-prefix=DB-NAME-PREFIX
Get or create a idle database from the pool.
list []
Print databases.
put
Return the database to the pool.
clean []
Drop all idle databases.
```
## Sample CircleCI configuration
```yaml
version: 2
jobs:
build:
docker:
- image: golang:1.13-stretch
environment:
PROJECT: project
INSTANCE: instance
SPOOL_DATABASE: spool
PATH_TO_SCHEMA_FILE: path/to/schema.sql
DATABASE_PREFIX: spool
working_directory: /go/src/github.com/user/repo
steps:
- checkout
- run:
name: set GitHub token
command: |
rm -f ~/.gitconfig
echo "machine github.com login ${GITHUB_TOKEN}" > ~/.netrc
- run:
name: install spool
command: go get -u github.com/cloudspannerecosystem/spool/cmd/spool
- run:
name: get database for testing
command: |
DATABASE=$(spool --project=${PROJECT} --instance=${INSTANCE} --database=${SPOOL_DATABASE} --schema=${PATH_TO_SCHEMA_FILE} get-or-create --db-name-prefix=${DATABASE_PREFIX})
echo "export DATABASE=${DATABASE}" >> ${BASH_ENV}
- run:
name: run tests
command: echo "run your tests with /projects/${PROJECT}/instances/${INSTANCE}/databases/${DATABASE}"
- run:
name: release database
when: always
command: spool --project=${PROJECT} --instance=${INSTANCE} --database=${SPOOL_DATABASE} --schema=${PATH_TO_SCHEMA_FILE} put ${DATABASE}
cleanup-old-test-db:
docker:
- image: golang:1.13-stretch
environment:
PROJECT: project
INSTANCE: instance
SPOOL_DATABASE: spool
PATH_TO_SCHEMA_FILE: path/to/schema.sql
working_directory: /go/src/github.com/user/repo
steps:
- checkout
- run:
name: set GitHub token
command: |
rm -f ~/.gitconfig
echo "machine github.com login ${GITHUB_TOKEN}" > ~/.netrc
- run:
name: install spool
command: go get -u github.com/cloudspannerecosystem/spool/cmd/spool
- run:
name: cleanup databases
command: spool --project=${PROJECT} --instance=${INSTANCE} --database=${SPOOL_DATABASE} --schema=${PATH_TO_SCHEMA_FILE} clean --all --force --ignore-used-within-days=7
workflows:
version: 2
build-workflow:
jobs:
- build:
context: org-global
cleanup-workflow:
triggers:
- schedule:
cron: '0 9 * * *'
filters:
branches:
only: master
jobs:
- cleanup-old-test-db:
context: org-global
```
## How to development
Setup environment (do it once)
```shell
$ export CLOUDSDK_ACTIVE_CONFIG_NAME=spool-test-config
$ gcloud config configurations create --no-activate $CLOUDSDK_ACTIVE_CONFIG_NAME
$ gcloud config set auth/disable_credentials true
$ gcloud config set project spool-test
$ gcloud config set api_endpoint_overrides/spanner http://localhost:9020/
```
Setup environment (do this before execute testing)
```shell
$ docker compose up -d --build --force-recreate
$ export CLOUDSDK_ACTIVE_CONFIG_NAME=spool-test-config
$ make setup-emulator
$ make test
$ docker compose down
```