{"id":15056733,"url":"https://github.com/datastax/cql-proxy","last_synced_at":"2025-05-16T14:05:40.525Z","repository":{"id":39194334,"uuid":"379067204","full_name":"datastax/cql-proxy","owner":"datastax","description":"A client-side CQL proxy/sidecar.","archived":false,"fork":false,"pushed_at":"2025-04-11T07:11:51.000Z","size":443,"stargazers_count":171,"open_issues_count":37,"forks_count":84,"subscribers_count":27,"default_branch":"main","last_synced_at":"2025-04-13T10:08:06.890Z","etag":null,"topics":["cassandra","cql","cqlsh","proxy"],"latest_commit_sha":null,"homepage":"","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/datastax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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":"2021-06-21T21:28:24.000Z","updated_at":"2025-04-11T07:02:10.000Z","dependencies_parsed_at":"2024-08-23T08:26:57.426Z","dependency_job_id":"100ec229-696c-410c-bd59-b8f5a25a522b","html_url":"https://github.com/datastax/cql-proxy","commit_stats":{"total_commits":137,"total_committers":13,"mean_commits":"10.538461538461538","dds":"0.46715328467153283","last_synced_commit":"0aaf29d9d11cd7e286feed7a82bf8308fddc6dbd"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastax%2Fcql-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastax%2Fcql-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastax%2Fcql-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastax%2Fcql-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datastax","download_url":"https://codeload.github.com/datastax/cql-proxy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254544146,"owners_count":22088807,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["cassandra","cql","cqlsh","proxy"],"created_at":"2024-09-24T21:55:55.616Z","updated_at":"2025-05-16T14:05:40.479Z","avatar_url":"https://github.com/datastax.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cql-proxy\n\n[![GitHub Action](https://github.com/datastax/cql-proxy/actions/workflows/test.yml/badge.svg)](https://github.com/datastax/cql-proxy/actions/workflows/test.yml) [![Go Report Card](https://goreportcard.com/badge/github.com/datastax/cql-proxy)](https://goreportcard.com/report/github.com/datastax/cql-proxy)\n\n## Table of Contents\n\n- [What is the cql-proxy?](https://github.com/datastax/cql-proxy#what-is-cqlproxy)\n- [When to use cql-proxy](https://github.com/datastax/cql-proxy#when-to-use-cql-proxy)\n- [Configuration](https://github.com/datastax/cql-proxy#configuration)\n- [Getting started](https://github.com/datastax/cql-proxy#getting-started)\n  - [Locally build and run](https://github.com/datastax/cql-proxy#locally-build-and-run)\n  - [Run a `cql-proxy` docker image](https://github.com/datastax/cql-proxy#run-a-cql-proxy-docker-image)\n  - [Use Kubernetes](https://github.com/datastax/cql-proxy#use-kubernetes)\n- [Known issues](https://github.com/datastax/cql-proxy#known-issues)\n    - [Token-aware load balancing](https://github.com/datastax/cql-proxy#token-aware-load-balancing)\n\n\n## What is `cql-proxy`?\n\n![cql-proxy](cql-proxy.png)\n\n`cql-proxy` is designed to forward your application's CQL traffic to an appropriate database service. It listens on a local address and securely forwards that traffic.\n\n## When to use `cql-proxy`\n\nThe `cql-proxy` sidecar enables unsupported CQL drivers to work with [DataStax Astra][astra]. These drivers include both legacy DataStax [drivers] and community-maintained CQL drivers, such as the [gocql] driver and the [rust-driver].\n\n`cql-proxy` also enables applications that are currently using [Apache Cassandra][cassandra] or [DataStax Enterprise (DSE)][dse] to use Astra without requiring any code changes.  Your application just needs to be configured to use the proxy.\n\nIf you're building a new application using DataStax [drivers], `cql-proxy` is not required, as the drivers can communicate directly with Astra. DataStax drivers have excellent support for Astra out-of-the-box, and are well-documented in the [driver-guide] guide. \n\n## Configuration\n\nUse the `-h` or `--help` flag to display a listing all flags and their corresponding descriptions and environment variables (shown below as items starting with `$`):\n\n```sh\n$ ./cql-proxy -h\nUsage: cql-proxy\n\nFlags:\n  -h, --help                                              Show context-sensitive help.\n  -b, --astra-bundle=STRING                               Path to secure connect bundle for an Astra database. Requires '--username' and '--password'. Ignored if using the\n                                                          token or contact points option ($ASTRA_BUNDLE).\n  -t, --astra-token=STRING                                Token used to authenticate to an Astra database. Requires '--astra-database-id'. Ignored if using the bundle path\n                                                          or contact points option ($ASTRA_TOKEN).\n  -i, --astra-database-id=STRING                          Database ID of the Astra database. Requires '--astra-token' ($ASTRA_DATABASE_ID)\n      --astra-api-url=\"https://api.astra.datastax.com\"    URL for the Astra API ($ASTRA_API_URL)\n      --astra-timeout=10s                                 Timeout for contacting Astra when retrieving the bundle and metadata ($ASTRA_TIMEOUT)\n  -c, --contact-points=CONTACT-POINTS,...                 Contact points for cluster. Ignored if using the bundle path or token option ($CONTACT_POINTS).\n  -u, --username=STRING                                   Username to use for authentication ($USERNAME)\n  -p, --password=STRING                                   Password to use for authentication ($PASSWORD)\n  -r, --port=9042                                         Default port to use when connecting to cluster ($PORT)\n  -n, --protocol-version=\"v4\"                             Initial protocol version to use when connecting to the backend cluster (default: v4, options: v3, v4, v5, DSEv1,\n                                                          DSEv2) ($PROTOCOL_VERSION)\n  -m, --max-protocol-version=\"v4\"                         Max protocol version supported by the backend cluster (default: v4, options: v3, v4, v5, DSEv1, DSEv2)\n                                                          ($MAX_PROTOCOL_VERSION)\n  -a, --bind=\":9042\"                                      Address to use to bind server ($BIND)\n  -f, --config=CONFIG                                     YAML configuration file ($CONFIG_FILE)\n      --debug                                             Show debug logging ($DEBUG)\n      --health-check                                      Enable liveness and readiness checks ($HEALTH_CHECK)\n      --http-bind=\":8000\"                                 Address to use to bind HTTP server used for health checks ($HTTP_BIND)\n      --heartbeat-interval=30s                            Interval between performing heartbeats to the cluster ($HEARTBEAT_INTERVAL)\n      --idle-timeout=60s                                  Duration between successful heartbeats before a connection to the cluster is considered unresponsive and closed\n                                                          ($IDLE_TIMEOUT)\n      --readiness-timeout=30s                             Duration the proxy is unable to connect to the backend cluster before it is considered not ready\n                                                          ($READINESS_TIMEOUT)\n      --idempotent-graph                                  If true it will treat all graph queries as idempotent by default and retry them automatically. It may be\n                                                          dangerous to retry some graph queries -- use with caution ($IDEMPOTENT_GRAPH).\n      --num-conns=1                                       Number of connection to create to each node of the backend cluster ($NUM_CONNS)\n      --proxy-cert-file=STRING                            Path to a PEM encoded certificate file with its intermediate certificate chain. This is used to encrypt traffic\n                                                          for proxy clients ($PROXY_CERT_FILE)\n      --proxy-key-file=STRING                             Path to a PEM encoded private key file. This is used to encrypt traffic for proxy clients ($PROXY_KEY_FILE)\n      --rpc-address=STRING                                Address to advertise in the 'system.local' table for 'rpc_address'. It must be set if configuring peer proxies\n                                                          ($RPC_ADDRESS)\n      --data-center=STRING                                Data center to use in system tables ($DATA_CENTER)\n      --tokens=TOKENS,...                                 Tokens to use in the system tables. It's not recommended ($TOKENS)\n```\n\nTo pass configuration to `cql-proxy`, either command-line flags, environment variables, or a configuration file can be used. Using the `docker` method as an example, the following samples show how the token and database ID are defined with each method.\n### Using flags\n\n```sh\ndocker run -p 9042:9042 \\\n  --rm datastax/cql-proxy:v0.1.5 \\\n  --astra-token \u003castra-token\u003e --astra-database-id \u003castra-datbase-id\u003e\n```\n\n### Using environment variables\n\n```sh\ndocker run -p 9042:9042  \\\n  --rm datastax/cql-proxy:v0.1.5 \\\n  -e ASTRA_TOKEN=\u003castra-token\u003e -e ASTRA_DATABASE_ID=\u003castra-datbase-id\u003e\n```\n\n### Using a configuration file\n\nProxy settings can also be passed using a configuration file with the `--config /path/to/proxy.yaml` flag. This can be mixed and matched with command-line flags and environment variables. Here are some example configuration files:\n\n```yaml\ncontact-points:\n  - 127.0.0.1\nusername: cassandra\npassword: cassandra\nport: 9042\nbind: 127.0.0.1:9042\n# ...\n```\n\nor with a Astra token:\n\n```yaml\nastra-token: \u003castra-token\u003e\nastra-database-id: \u003castra-database-id\u003e\nbind: 127.0.0.1:9042\n# ...\n```\n\nAll configuration keys match their command-line flag counterpart, e.g. `--astra-bundle` is\n`astra-bundle:`,  `--contact-points` is `contact-points:` etc.\n\n#### Setting up peer proxies\n\nMulti-region failover with DC-aware load balancing policy is the most useful case for a multiple proxy setup.\n\nWhen configuring `peers:` it is required to set `--rpc-address` (or `rpc-address:` in the yaml) for each proxy and it must match is corresponding `peers:` entry. Also, `peers:` is only available in the configuration file and cannot be set using a command-line flag.\n\n##### Multi-region setup\n\nHere's an example of configuring multi-region failover with two proxies. A proxy is started for each region of the cluster connecting to it using that region's bundle. They all share a common configuration file that contains the full list of proxies.\n\n*Note:* Only bundles are supported for multi-region setups.\n\n```sh\ncql-proxy --astra-bundle astra-region1-bundle.zip --username token --password \u003castra-token\u003e \\\n  --bind 127.0.0.1:9042 --rpc-address 127.0.0.1 --data-center dc-1 --config proxy.yaml\n```\n\n```sh\ncql-proxy ---astra-bundle astra-region2-bundle.zip --username token --password \u003castra-token\u003e \\\n  --bind 127.0.0.2:9042 --rpc-address 127.0.0.2 --data-center dc-2 --config proxy.yaml\n```\n\nThe peers settings are configured using a yaml file. It's a good idea to explicitly provide the `--data-center` flag, otherwise; these values are pulled from the backend cluster and would need to be pulled from the `system.local` and `system.peers` table to properly setup the peers `data-center:` values. Here's an example `proxy.yaml`:\n\n```yaml\npeers:\n  - rpc-address: 127.0.0.1\n    data-center: dc-1\n  - rpc-address: 127.0.0.2\n    data-center: dc-2\n```\n\n*Note:* It's okay for the `peers:` to contain entries for the current proxy itself because they'll just be omitted.\n\n## Getting started\n\nThere are three methods for using `cql-proxy`:\n\n- Locally build and run `cql-proxy`\n- Run a docker image that has `cql-proxy` installed\n- Use a Kubernetes container to run `cql-proxy`\n### Locally build and run\n\n1. Build `cql-proxy`.\n\n    ```sh\n    go build\n    ```\n\n2. Run with your desired database.\n\n   - [DataStax Astra][astra] cluster:\n\n      ```sh\n      ./cql-proxy --astra-token \u003castra-token\u003e --astra-database-id \u003castra-database-id\u003e\n      ```\n\n      The `\u003castra-token\u003e` can be generated using these [instructions]. The proxy also supports using the [Astra Secure Connect Bundle][bundle] along with a client ID and secret generated using these [instructions]:\n\n      ```\n      ./cql-proxy --astra-bundle \u003cyour-secure-connect-zip\u003e \\\n      --username \u003castra-client-id\u003e --password \u003castra-client-secret\u003e\n      ```\n\n   - [Apache Cassandra][cassandra] cluster:\n\n      ```sh\n      ./cql-proxy --contact-points \u003ccluster node IPs or DNS names\u003e [--username \u003cusername\u003e] [--password \u003cpassword\u003e]\n      ```\n### Run a `cql-proxy` docker image\n\n1. Run with your desired database.\n\n   - [DataStax Astra][astra] cluster:\n\n      ```sh\n      docker run -p 9042:9042 \\\n        datastax/cql-proxy:v0.1.5 \\\n        --astra-token \u003castra-token\u003e --astra-database-id \u003castra-database-id\u003e\n      ```\n\n      The `\u003castra-token\u003e` can be generated using these [instructions]. The proxy also supports using the [Astra Secure Connect Bundle][bundle], but it requires mounting the bundle to a volume in the container:\n\n      ```sh\n      docker run -v \u003cyour-secure-connect-bundle.zip\u003e:/tmp/scb.zip -p 9042:9042 \\\n      --rm datastax/cql-proxy:v0.1.5 \\\n      --astra-bundle /tmp/scb.zip --username \u003castra-client-id\u003e --password \u003castra-client-secret\u003e\n      ```\n   - [Apache Cassandra][cassandra] cluster:\n\n      ```sh\n      docker run -p 9042:9042 \\\n        datastax/cql-proxy:v0.1.5 \\\n        --contact-points \u003ccluster node IPs or DNS names\u003e [--username \u003cusername\u003e] [--password \u003cpassword\u003e]\n      ```\n  If you wish to have the docker image removed after you are done with it, add `--rm` before the image name `datastax/cql-proxy:v0.1.5`.\n\n### Use Kubernetes\n\nUsing Kubernetes with `cql-proxy` requires a number of steps:\n\n1. Generate a token following the Astra [instructions](https://docs.datastax.com/en/astra/docs/manage-application-tokens.html#_create_application_token). This step will display your Client ID, Client Secret, and Token; make sure you download the information for the next steps. Store the secure bundle in `/tmp/scb.zip` to match the example below.\n\n2. Create `cql-proxy.yaml`. You'll need to add three sets of information: arguments, volume mounts, and volumes. A full example can be found [here](k8s/cql-proxy.yml).\n\n - Argument: Modify the local bundle location, username and password, using the client ID and client secret obtained in the last step to the container argument.   \n\n      ```\n      command: [\"./cql-proxy\"]\n      args: [\"--astra-bundle=/tmp/scb.zip\",\"--username=Client ID\",\"--password=Client Secret\"]\n      ```\n\n- Volume mounts: Modify `/tmp/` as a volume mount as required.\n\n      volumeMounts:\n        - name: my-cm-vol\n        mountPath: /tmp/\n \n\n- Volume: Modify the `configMap` filename as required. In this example, it is named `cql-proxy-configmap`. Use the same name for the `volumes` that you used for the `volumeMounts`. \n\n      volumes:\n        - name: my-cm-vol\n          configMap:\n            name: cql-proxy-configmap        \n    \n3. Create a configmap. Use the same secure bundle that was specified in the `cql-proxy.yaml`.\n      \n      ```sh\n      kubectl create configmap cql-proxy-configmap --from-file /tmp/scb.zip \n      ```\n\n4. Check the configmap that was created. \n\n    ```sh\n    kubectl describe configmap cql-proxy-configmap\n      \n      Name:         cql-proxy-configmap\n      Namespace:    default\n      Labels:       \u003cnone\u003e\n      Annotations:  \u003cnone\u003e\n\n      Data\n      ====\n\n      BinaryData\n      ====\n      scb.zip: 12311 bytes\n    ```\n\n5. Create a Kubernetes deployment with the YAML file you created:\n\n     ```sh\n     kubectl create -f cql-proxy.yaml\n     ```\n\n6. Check the logs:\n    ```sh\n    kubectl logs \u003cdeployment-name\u003e\n    ```\n## Known issues\n\n### Token-aware load balancing\n\nDrivers that use token-aware load balancing may print a warning or may not work when using cql-proxy. Because cql-proxy abstracts the backend cluster as a single endpoint this doesn't always work well with token-aware drivers that expect there to be at least \"replication factor\" number of nodes in the cluster. Many drivers print a warning (which can be ignored) and fallback to something like round-robin, but other drivers might fail with an error. For the drivers that fail with an error it is required that they disable token-aware or configure the round-robin load balancing policy.\n\n[astra]: https://astra.datastax.com/\n[drivers]: https://docs.datastax.com/en/driver-matrix/doc/driver_matrix/common/driverMatrix.html\n[gocql]: https://github.com/gocql/gocql\n[rust-driver]: https://github.com/scylladb/scylla-rust-driver\n[driver-guide]: https://docs.datastax.com/en/astra/docs/connecting-to-astra-databases-using-datastax-drivers.html\n[cassandra]: https://cassandra.apache.org/\n[dse]: https://www.datastax.com/products/datastax-enterprise\n[instructions]: https://docs.datastax.com/en/astra/docs/manage-application-tokens.html\n[bundle]: https://docs.datastax.com/en/astra/docs/obtaining-database-credentials.html#_getting_your_secure_connect_bundle\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatastax%2Fcql-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatastax%2Fcql-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatastax%2Fcql-proxy/lists"}