Skip to content

A CLI tool to manage Cloud Spanner databases for testing.

License

Notifications You must be signed in to change notification settings

cloudspannerecosystem/spool

Folders and files

NameName
Last commit message
Last commit date

Latest commit

891d1a2 · Feb 26, 2025

History

12 Commits
Feb 26, 2025
Jul 13, 2020
Feb 26, 2025
Nov 5, 2019
Nov 5, 2019
Nov 5, 2019
Feb 26, 2025
Jul 13, 2020
Jul 13, 2020
Jul 13, 2020
Feb 26, 2025
Feb 26, 2025
Feb 26, 2025
Jul 13, 2020
Nov 5, 2019
Feb 26, 2025
Nov 5, 2019
Jul 13, 2020
Jul 13, 2020
Feb 26, 2025
Feb 26, 2025
Jul 14, 2020
Jul 14, 2020
Jul 13, 2020

Repository files navigation

spool

build and test

A CLI tool to manage Cloud Spanner databases for testing.

spool

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

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

$ spool --project=${PROJECT} --instance=${INSTANCE} --database=${SPOOL_DATABASE} setup

Usage

usage: spool [<flags>] <command> [<args> ...]

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 [<command>...]
    Show help.

  setup
    Setup the database for spool metadata.

  create --db-name-prefix=DB-NAME-PREFIX [<flags>]
    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 [<flags>]
    Print databases.

  put <database>
    Return the database to the pool.

  clean [<flags>]
    Drop all idle databases.

Sample CircleCI configuration

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)

$ 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)

$ docker compose up -d --build --force-recreate
$ export CLOUDSDK_ACTIVE_CONFIG_NAME=spool-test-config
$ make setup-emulator
$ make test
$ docker compose down