{"id":42482636,"url":"https://github.com/cloudspannerecosystem/cassandra-to-spanner-proxy","last_synced_at":"2026-01-28T11:15:50.966Z","repository":{"id":259328247,"uuid":"870481167","full_name":"cloudspannerecosystem/cassandra-to-spanner-proxy","owner":"cloudspannerecosystem","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-21T21:17:18.000Z","size":2744,"stargazers_count":12,"open_issues_count":9,"forks_count":7,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-08-21T22:53:10.709Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudspannerecosystem.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/code-of-conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-10-10T06:00:51.000Z","updated_at":"2025-08-21T21:17:22.000Z","dependencies_parsed_at":"2024-10-24T12:52:15.375Z","dependency_job_id":"63fd4a50-e86d-47e4-939a-2a4ee5f33191","html_url":"https://github.com/cloudspannerecosystem/cassandra-to-spanner-proxy","commit_stats":null,"previous_names":["cloudspannerecosystem/cassandra-to-spanner-proxy"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/cloudspannerecosystem/cassandra-to-spanner-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudspannerecosystem%2Fcassandra-to-spanner-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudspannerecosystem%2Fcassandra-to-spanner-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudspannerecosystem%2Fcassandra-to-spanner-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudspannerecosystem%2Fcassandra-to-spanner-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudspannerecosystem","download_url":"https://codeload.github.com/cloudspannerecosystem/cassandra-to-spanner-proxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudspannerecosystem%2Fcassandra-to-spanner-proxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28844866,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T10:53:21.605Z","status":"ssl_error","status_checked_at":"2026-01-28T10:53:20.789Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-28T11:15:49.793Z","updated_at":"2026-01-28T11:15:50.958Z","avatar_url":"https://github.com/cloudspannerecosystem.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cassandra to Cloud Spanner Proxy Adapter\n\u003e [!NOTE] \n\u003e We introduced the newer official [java-spanner-cassandra](https://github.com/googleapis/java-spanner-cassandra/blob/main/README.md) and [go-spanner-cassandra](https://github.com/googleapis/go-spanner-cassandra/blob/main/README.md) clients. See https://cloud.google.com/spanner/docs/non-relational/connect-cassandra-adapter for more information.\n\u003e \n## Current Released  Version\n\nVersion `1.1.1`\n\n## Introduction\nCassandra to Cloud Spanner Proxy Adapter is designed to forward your application's CQL traffic to Spanner database service. It listens on a local address and securely forwards that traffic.\n\n## Table of Contents\n- [When to use cassandra-to-spanner-proxy?](#when-to-use-cassandra-to-spanner-proxy)\n- [Prerequisites](#prerequisites)\n- [Cloud Spanner Instructions](#cloud-spanner-instructions)\n- [Getting started](#getting-started)\n  - [Locally build and run](#locally-build-and-run)\n  - [Run a `cassandra-to-spanner-proxy` via docker](#run-a-cassandra-to-spanner-proxy-via-docker)\n  - [Use Kubernetes](#use-kubernetes)\n- [Infrastructure Provisioning on GCP using Terraform](./deployment/infra-tf/README.md)\n- [CQLSH support](./docs/cqlsh.md)\n- [Stale Read Support](./docs/StaleRead.md)\n- [Configuration Options](./docs/config_options.md)\n- [Limitations for Proxy Application](#limitations-for-proxy-application)\n- [Setting Up systemd](./systemd/Readme.md)\n- [Instrument with OpenTelemetry](#instrument-with-opentelemetry)\n- [Differences from Cassandra](./docs/differences_from_cassandra.md)\n- [Run Unit/Integration tests locally](./docs/setup_ut_it.md)\n- [Generating Mock Files Using Mockery](./mocks/README.md)\n- [Frequently Asked Questions](./docs/faq.md)\n## When to use cassandra-to-spanner-proxy ?\n\n`cassandra-to-spanner-proxy`  enables applications that are currently using Apache Cassandra or DataStax Enterprise (DSE) and would like to switch to use Cloud Spanner. This Proxy Adapter can be used as Plug-N-Play for the Client Application without the need of any code changes in the Client Application.\n\n## Prerequisites\n\nYou will need a [Google Cloud Platform Console][developer-console] project with the Cloud Spanner [API enabled][enable-api].\nYou will need to [enable billing][enable-billing] to use Google Cloud Spanner.\n[Follow these instructions][create-project] to get your project set up.\n\nEnsure that you run\n\n```sh\ngcloud auth application-default login\n```\n\nto set up your local development environment with authentication credentials.\n\nSet the GCLOUD_PROJECT environment variable to your Google Cloud project ID:\n\n```sh\ngcloud config set project [MY_PROJECT_NAME]\n```\n\n## Cloud Spanner Instructions\n\n- Database and all the tables should be created in advance before executing the queries using the adapter.\n- A table should be created as below which will have the metadata information of the cassandra tables and its columns.\n\n    ```sql\n        CREATE TABLE IF NOT EXISTS TableConfigurations (\n            `KeySpaceName` STRING(MAX),\n            `TableName` STRING(MAX),\n            `ColumnName` STRING(MAX),\n            `ColumnType` STRING(MAX),\n            `IsPrimaryKey` BOOL,\n            `PK_Precedence` INT64,\n        ) PRIMARY KEY (TableName, ColumnName, KeySpaceName);\n    ```\n![proxy_adapter_table_config sample data](docs/images/config_spanner.png)\n\n- Make sure to insert all the table and column information into the above table before running the application.\n\n## Getting started\n\nWe can setup the `cassandra-to-spanner-proxy` adapter via 3 different methods as mentioned below\n\n- Locally build and run `cassandra-to-spanner-proxy`\n- Run a docker image that has `cassandra-to-spanner-proxy` installed\n- Use a Kubernetes container to run `cassandra-to-spanner-proxy`\n\n\n### Locally build and run\n\nSteps to run the adapter locally are as mentioned below:\n\n- Clone the repository (https://github.com/cloudspannerecosystem/cassandra-to-spanner-proxy.git)\n- Update `config.yaml` (or set up the `CONFIG_FILE` environment variable with the appropriate config file path), to specify listeners, project, instance, database details as well as additional configuration like enabling/disabling OTEL, keyspace flattening , Spanner session related configuration etc. See [advanced config options](docs/config_options.md) for more details.\n    ```yaml\n    cassandra_to_spanner_configs:\n    projectId: YOUR_PROJECT_ID\n    configTableName: YOUR_CONFIG_TABLE_NAME\n    keyspaceFlatter: True\n\n    listeners:\n    - name: YOUR_CLUSTER_NAME_1\n        port: PORT_1\n        spanner:\n            instanceId: YOUR_SPANNER_INSTANCE_ID\n            databaseId: YOUR_SPANNER_DATABASE\n\n    ```\n\n- Build the proxy application by running the below command on the root directory.\n    ```sh\n    CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o cassandra-to-spanner-proxy .\n- Run the Application\n    ```sh\n    ./cassandra-to-spanner-proxy\n- Optional Arguments with the default values.\n  * **cql-version**: CQL version, **default value: \"3.4.5\"**\n  * **partitioner**: Partitioner, **default value: \"org.apache.cassandra.dht.Murmur3Partitioner\"**\n  * **release-version**: Release Version, **default value: \"4.0.0.6816\"**\n  * **data-center**: Data center, **default value: \"datacenter1\"**\n  * **protocol-version**: Initial protocol version to use when connecting to the backend cluster, **default value: v4**\n  * **log-level**: , set log level - [info/debug/error/warn] **default value: info**\n- Run the Application with the arguments example\n    ```sh\n    ./cassandra-to-spanner-proxy --log-level error\n- Application will be listening on PORT **9042**.\n\n### Run a `cassandra-to-spanner-proxy` via docker\n\n- Build the docker image\n    ```sh\n    docker run -p 9042:9042 \\\n  -e GOOGLE_APPLICATION_CREDENTIALS=\"/var/run/secret/cloud.google.com/spanner-adaptor-service-account.json\" \\\n  -v \u003c\u003cpath to service account\u003e\u003e/spanner-adaptor-service-account.json:/var/run/secret/cloud.google.com/ \\\n  -d cassandra-spanner-proxy\n\n    ```\n\n### Use Kubernetes\n\n- [Deployment via k8](./deployment/k8/README.md)\n\n### Infrastructure provisioning on GCP using Terraform\n- [Infrastructure provisioning on GCP](./deployment/infra-tf/README.md)\n\n### CQLSH with proxy\n Users can connect and use `cqlsh` with the proxy. Detailed document -  [cqlsh.md](./docs/cqlsh.md)\n\n## Limitations for Proxy Application\n\nDetailed document - [Limitations](./docs/limitations.md)\n\n### Run a `cassandra-to-spanner-proxy` via systemd.\n\nWhy systemd? - It can automatically restart crashed services, which is crucial for maintaining the availability of applications and system functions. systemd also provides mechanisms for service sandboxing and security.\n\nGo through this document for setting up systemd for this project in your linux system - [Setting Up systemd](./systemd/Readme.md)\n\n### Instrument with OpenTelemetry\n\nThe Proxy Adapter supports OpenTelemetry metrics and traces, which gives insight into the adapter internals and aids in debugging/troubleshooting production issues.\n\nSee [OpenTelemetry](otel/README.md) for integrating OpenTelemetry (OTEL) with Your Application\n\n[developer-console]: https://console.developers.google.com/\n[enable-api]: https://console.cloud.google.com/flows/enableapi?apiid=spanner.googleapis.com\n[enable-billing]: https://cloud.google.com/apis/docs/getting-started#enabling_billing\n[create-project]: https://cloud.google.com/resource-manager/docs/creating-managing-projects\n[cloud-cli]: https://cloud.google.com/cli\n\n## FAQ\nSee [Frequently Asked Questions](docs/faq.md) for answers to frequently asked questions.\n\n## License\n\n[Apache License 2.0](LICENSE)\n\n## Getting Support\n\nThe Cassandra to Cloud Spanner Proxy Adapter is a [Cloud Spanner Ecosystem](https://www.cloudspannerecosystem.dev/about)\nproject  is maintained by the Google Spanner team. We'd love for you to\n[report issues, file feature requests][new-issue], and [send pull requests][new-pr]\n(see [Contributing](CONTRIBUTING.md)). You may file bugs and feature\nrequests using GitHub's issue tracker or using the existing Cloud Spanner\nsupport channels.\n\n[new-issue]: https://github.com/cloudspannerecosystem/cassandra-to-spanner-proxy/issues/new\n[new-pr]: https://github.com/cloudspannerecosystem/cassandra-to-spanner-proxy/compare\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudspannerecosystem%2Fcassandra-to-spanner-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudspannerecosystem%2Fcassandra-to-spanner-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudspannerecosystem%2Fcassandra-to-spanner-proxy/lists"}