• Stars
    star
    172
  • Rank 221,201 (Top 5 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created over 3 years ago
  • Updated 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A client-side CQL proxy/sidecar.

cql-proxy

GitHub Action Go Report Card

Table of Contents

What is cql-proxy?

cql-proxy

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.

When to use cql-proxy

The cql-proxy sidecar enables unsupported CQL drivers to work with DataStax Astra. These drivers include both legacy DataStax drivers and community-maintained CQL drivers, such as the gocql driver and the rust-driver.

cql-proxy also enables applications that are currently using Apache Cassandra or DataStax Enterprise (DSE) to use Astra without requiring any code changes. Your application just needs to be configured to use the proxy.

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

Configuration

Use the -h or --help flag to display a listing all flags and their corresponding descriptions and environment variables (shown below as items starting with $):

$ ./cql-proxy -h
Usage: cql-proxy

Flags:
  -h, --help                                              Show context-sensitive help.
  -b, --astra-bundle=STRING                               Path to secure connect bundle for an Astra database. Requires '--username' and '--password'. Ignored if using the
                                                          token or contact points option ($ASTRA_BUNDLE).
  -t, --astra-token=STRING                                Token used to authenticate to an Astra database. Requires '--astra-database-id'. Ignored if using the bundle path
                                                          or contact points option ($ASTRA_TOKEN).
  -i, --astra-database-id=STRING                          Database ID of the Astra database. Requires '--astra-token' ($ASTRA_DATABASE_ID)
      --astra-api-url="https://api.astra.datastax.com"    URL for the Astra API ($ASTRA_API_URL)
      --astra-timeout=10s                                 Timeout for contacting Astra when retrieving the bundle and metadata ($ASTRA_TIMEOUT)
  -c, --contact-points=CONTACT-POINTS,...                 Contact points for cluster. Ignored if using the bundle path or token option ($CONTACT_POINTS).
  -u, --username=STRING                                   Username to use for authentication ($USERNAME)
  -p, --password=STRING                                   Password to use for authentication ($PASSWORD)
  -r, --port=9042                                         Default port to use when connecting to cluster ($PORT)
  -n, --protocol-version="v4"                             Initial protocol version to use when connecting to the backend cluster (default: v4, options: v3, v4, v5, DSEv1,
                                                          DSEv2) ($PROTOCOL_VERSION)
  -m, --max-protocol-version="v4"                         Max protocol version supported by the backend cluster (default: v4, options: v3, v4, v5, DSEv1, DSEv2)
                                                          ($MAX_PROTOCOL_VERSION)
  -a, --bind=":9042"                                      Address to use to bind server ($BIND)
  -f, --config=CONFIG                                     YAML configuration file ($CONFIG_FILE)
      --debug                                             Show debug logging ($DEBUG)
      --health-check                                      Enable liveness and readiness checks ($HEALTH_CHECK)
      --http-bind=":8000"                                 Address to use to bind HTTP server used for health checks ($HTTP_BIND)
      --heartbeat-interval=30s                            Interval between performing heartbeats to the cluster ($HEARTBEAT_INTERVAL)
      --idle-timeout=60s                                  Duration between successful heartbeats before a connection to the cluster is considered unresponsive and closed
                                                          ($IDLE_TIMEOUT)
      --readiness-timeout=30s                             Duration the proxy is unable to connect to the backend cluster before it is considered not ready
                                                          ($READINESS_TIMEOUT)
      --idempotent-graph                                  If true it will treat all graph queries as idempotent by default and retry them automatically. It may be
                                                          dangerous to retry some graph queries -- use with caution ($IDEMPOTENT_GRAPH).
      --num-conns=1                                       Number of connection to create to each node of the backend cluster ($NUM_CONNS)
      --proxy-cert-file=STRING                            Path to a PEM encoded certificate file with its intermediate certificate chain. This is used to encrypt traffic
                                                          for proxy clients ($PROXY_CERT_FILE)
      --proxy-key-file=STRING                             Path to a PEM encoded private key file. This is used to encrypt traffic for proxy clients ($PROXY_KEY_FILE)
      --rpc-address=STRING                                Address to advertise in the 'system.local' table for 'rpc_address'. It must be set if configuring peer proxies
                                                          ($RPC_ADDRESS)
      --data-center=STRING                                Data center to use in system tables ($DATA_CENTER)
      --tokens=TOKENS,...                                 Tokens to use in the system tables. It's not recommended ($TOKENS)

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

Using flags

docker run -p 9042:9042 \
  --rm datastax/cql-proxy:v0.1.4 \
  --astra-token <astra-token> --astra-database-id <astra-datbase-id>

Using environment variables

docker run -p 9042:9042  \
  --rm datastax/cql-proxy:v0.1.4 \
  -e ASTRA_TOKEN=<astra-token> -e ASTRA_DATABASE_ID=<astra-datbase-id>

Using a configuration file

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

contact-points:
  - 127.0.0.1
username: cassandra
password: cassandra
port: 9042
bind: 127.0.0.1:9042
# ...

or with a Astra token:

astra-token: <astra-token>
astra-database-id: <astra-database-id>
bind: 127.0.0.1:9042
# ...

All configuration keys match their command-line flag counterpart, e.g. --astra-bundle is astra-bundle:, --contact-points is contact-points: etc.

Setting up peer proxies

Multi-region failover with DC-aware load balancing policy is the most useful case for a multiple proxy setup.

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

Multi-region setup

Here'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.

Note: Only bundles are supported for multi-region setups.

cql-proxy --astra-bundle astra-region1-bundle.zip --username token --password <astra-token> \
  --bind 127.0.0.1:9042 --rpc-address 127.0.0.1 --data-center dc-1 --config proxy.yaml
cql-proxy ---astra-bundle astra-region2-bundle.zip --username token --password <astra-token> \
  --bind 127.0.0.2:9042 --rpc-address 127.0.0.2 --data-center dc-2 --config proxy.yaml

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

peers:
  - rpc-address: 127.0.0.1
    data-center: dc-1
  - rpc-address: 127.0.0.2
    data-center: dc-2

Note: It's okay for the peers: to contain entries for the current proxy itself because they'll just be omitted.

Getting started

There are three methods for using cql-proxy:

  • Locally build and run cql-proxy
  • Run a docker image that has cql-proxy installed
  • Use a Kubernetes container to run cql-proxy

Locally build and run

  1. Build cql-proxy.

    go build
  2. Run with your desired database.

    • DataStax Astra cluster:

      ./cql-proxy --astra-token <astra-token> --astra-database-id <astra-database-id>

      The <astra-token> can be generated using these instructions. The proxy also supports using the Astra Secure Connect Bundle along with a client ID and secret generated using these instructions:

      ./cql-proxy --astra-bundle <your-secure-connect-zip> \
      --username <astra-client-id> --password <astra-client-secret>
      
    • Apache Cassandra cluster:

      ./cql-proxy --contact-points <cluster node IPs or DNS names> [--username <username>] [--password <password>]

Run a cql-proxy docker image

  1. Run with your desired database.

    • DataStax Astra cluster:

      docker run -p 9042:9042 \
        datastax/cql-proxy:v0.1.4 \
        --astra-token <astra-token> --astra-database-id <astra-database-id>

      The <astra-token> can be generated using these instructions. The proxy also supports using the Astra Secure Connect Bundle, but it requires mounting the bundle to a volume in the container:

      docker run -v <your-secure-connect-bundle.zip>:/tmp/scb.zip -p 9042:9042 \
      --rm datastax/cql-proxy:v0.1.4 \
      --astra-bundle /tmp/scb.zip --username <astra-client-id> --password <astra-client-secret>
    • Apache Cassandra cluster:

      docker run -p 9042:9042 \
        datastax/cql-proxy:v0.1.4 \
        --contact-points <cluster node IPs or DNS names> [--username <username>] [--password <password>]

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

Use Kubernetes

Using Kubernetes with cql-proxy requires a number of steps:

  1. Generate a token following the Astra instructions. 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.

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

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

    command: ["./cql-proxy"]
    args: ["--astra-bundle=/tmp/scb.zip","--username=Client ID","--password=Client Secret"]
    
  • Volume mounts: Modify /tmp/ as a volume mount as required.

    volumeMounts:
      - name: my-cm-vol
      mountPath: /tmp/
    
  • 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.

    volumes:
      - name: my-cm-vol
        configMap:
          name: cql-proxy-configmap        
    
  1. Create a configmap. Use the same secure bundle that was specified in the cql-proxy.yaml.

    kubectl create configmap cql-proxy-configmap --from-file /tmp/scb.zip 
  2. Check the configmap that was created.

    kubectl describe configmap cql-proxy-configmap
      
      Name:         cql-proxy-configmap
      Namespace:    default
      Labels:       <none>
      Annotations:  <none>
    
      Data
      ====
    
      BinaryData
      ====
      scb.zip: 12311 bytes
  3. Create a Kubernetes deployment with the YAML file you created:

    kubectl create -f cql-proxy.yaml
  4. Check the logs:

    kubectl logs <deployment-name>

Known issues

Token-aware load balancing

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

More Repositories

1

spark-cassandra-connector

DataStax Connector for Apache Spark to Apache Cassandra
Scala
1,944
star
2

python-driver

DataStax Python Driver for Apache Cassandra
Python
1,387
star
3

nodejs-driver

DataStax Node.js Driver for Apache Cassandra
JavaScript
1,238
star
4

csharp-driver

DataStax C# Driver for Apache Cassandra
C#
638
star
5

php-driver

[MAINTENANCE ONLY] DataStax PHP Driver for Apache Cassandra
C
433
star
6

cpp-driver

DataStax C/C++ Driver for Apache Cassandra
C++
403
star
7

cass-operator

The DataStax Kubernetes Operator for Apache Cassandra
Go
256
star
8

ruby-driver

[MAINTENANCE ONLY] DataStax Ruby Driver for Apache Cassandra
Ruby
227
star
9

graph-book

The Code Examples and Notebooks for The Practitioners Guide to Graph Data
Shell
185
star
10

astra-assistants-api

Drop in replacement for the OpenAI Assistants API
Python
146
star
11

ragstack-ai

RAGStack is an out of the box solution simplifying Retrieval Augmented Generation (RAG) in AI apps.
Python
133
star
12

metric-collector-for-apache-cassandra

Drop-in metrics collection and dashboards for Apache Cassandra
Java
111
star
13

dsbulk

DataStax Bulk Loader (DSBulk) is an open-source, Apache-licensed, unified tool for loading into and unloading from Apache Cassandra(R), DataStax Astra and DataStax Enterprise (DSE)
Java
82
star
14

zdm-proxy

An open-source component designed to seamlessly handle the real-time client application activity while a migration is in progress.
Go
76
star
15

docker-images

Docker images published by DataStax.
Shell
73
star
16

dynamo-cassandra-proxy

Preview version of an open source tool that enables developers to run their AWS DynamoDB™ workloads on Apache Cassandra™. With the proxy, developers can run DynamoDB workloads outside of AWS (including on premises, other clouds, and in hybrid configurations).
Java
73
star
17

cstar_perf

Apache Cassandra performance testing platform
Python
72
star
18

ai-chatbot-starter

A starter app to build AI powered chat bots with Astra DB and LlamaIndex
Python
70
star
19

zdm-proxy-automation

An Ansible-based automation suite to deploy and manage the Zero Downtime Migration Proxy
Go
61
star
20

ragbot-starter

An Astra DB and OpenAI chatbot
TypeScript
61
star
21

wikichat

Python
56
star
22

graph-examples

Java
52
star
23

fallout

Distributed System Testing as a Service
Java
51
star
24

pulsar-jms

DataStax Starlight for JMS, a JMS API for Apache Pulsar ®
Java
48
star
25

reactive-pulsar

Reactive Streams adapter for Apache Pulsar Java Client
Java
48
star
26

pulsar-helm-chart

Apache Pulsar Helm chart
Mustache
47
star
27

SwiftieGPT

TypeScript
47
star
28

kafka-examples

Examples of using the DataStax Apache Kafka Connector.
Java
46
star
29

kaap

KAAP, Kubernetes Autoscaling for Apache Pulsar
Java
45
star
30

cassandra-quarkus

An Apache Cassandra(R) extension for Quarkus
Java
40
star
31

cdc-apache-cassandra

Datastax CDC for Apache Cassandra
Java
35
star
32

pulsar-admin-console

Pulsar Admin Console is a web based UI that administrates topics, namespaces, sources, sinks and various aspects of Apache Pulsar features.
Vue
35
star
33

sstable-to-arrow

Java
34
star
34

simulacron

Simulacron - An Apache Cassandra® Native Protocol Server Simulator
Java
32
star
35

astra-cli

Command Line Interface for DataStax Astra
Java
31
star
36

code-samples

Code samples from DataStax
Scala
31
star
37

starlight-for-rabbitmq

Starlight for RabbitMQ, a proxy layer between RabbitMQ/AMQP0.9.1 clients and Apache Pulsar
Java
29
star
38

dse-metric-reporter-dashboards

Prometheus & Grafana dashboards for DSE metric collector
Python
28
star
39

diagnostic-collection

Diagnostic Collector for Apache Cassandra
Python
28
star
40

cassandra-data-migrator

Cassandra Data Migrator - Migrate & Validate data between origin and target Apache Cassandra®-compatible clusters.
Java
28
star
41

spark-cassandra-stress

A tool for testing the DataStax Spark Connector against Apache Cassandra or DSE
Scala
26
star
42

cla-enforcer

A Contributor License Agreement enforcement bot
Ruby
25
star
43

pulsar-heartbeat

Pulsar Heartbeat monitors Pulsar cluster availability, tracks latency of Pulsar message pubsub, and reports failures of the Pulsar cluster. It produces synthetic workloads to measure end-to-end message pubsub latency.
Go
23
star
44

astrapy

AstraPy is a Pythonic interface for DataStax Astra DB and the Data API
Python
21
star
45

cassandra-data-apis

Data APIs for Apache Cassandra
Go
20
star
46

cassandra-log4j-appender

Cassandra appenders for Log4j
Java
20
star
47

terraform-provider-astra

A project that allows DataStax Astra users to manage their full database lifecycle for Astra Serverless databases (built on Apache Cassandra(TM)) using Terraform
Go
20
star
48

labs

DataStax Labs preview program
Java
19
star
49

starlight-for-kafka

DataStax - Starlight for Kafka
Java
17
star
50

dc-failover-demo

Fault Tolerant Applications with Apache Cassandra™ Demo
HCL
17
star
51

astra-sdk-java

Set of client side libraries to help with Astra Platform usage
Java
17
star
52

movies_plus_plus

TypeScript
17
star
53

kafka-sink

Apache Kafka® sink for transferring events/messages from Kafka topics to Apache Cassandra®, DataStax Astra and DataStax Enterprise (DSE).
Java
17
star
54

astrajs

A monorepo containing tools for interacting with DataStax Astra and Stargate
JavaScript
15
star
55

astra-db-ts

Typescript client for Astra DB Vector
TypeScript
15
star
56

native-protocol

An implementation of the Apache Cassandra® native protocol
Java
14
star
57

pulsar-sink

An Apache Pulsar® sink for transferring events/messages from Pulsar topics to Apache Cassandra®, DataStax Astra or DataStax Enterprise (DSE) tables.
Java
14
star
58

block-explorer

TypeScript
13
star
59

go-cassandra-native-protocol

Cassandra Native Protocol bindings for the Go language
Go
13
star
60

cassandra-reactive-demo

A demo application that interacts with Apache Cassandra(R) using the Java driver 4.4+ and reactive programming
Java
12
star
61

adelphi

Automation tool for testing C* OSS that assembles cassandra-diff, nosqlbench, fqltool
Python
10
star
62

pulsar-transformations

Java
10
star
63

astra-db-java

Java Client for DataStax Astra DB and the Data API
Java
10
star
64

dsbulk-migrator

Java
9
star
65

release-notes

Release Notes for DataStax Products
9
star
66

gatling-dse-plugin

Scala
8
star
67

gocql-astra

Support for gocql on Astra
Go
8
star
68

snowflake-connector

Datastax Snowflake Sink Connector for Apache Pulsar
Java
8
star
69

vault-plugin-secrets-datastax-astra

HashiCorp Vault Plugin for Datstax Astra
Go
8
star
70

pulsar-3rdparty-connector

This project provides simple templates and instructions to build Apache Pulsar connectors on base of the existing Apache Kafka connectors.
Shell
8
star
71

astra-client-go

Go
7
star
72

dsbench-labs

DSBench - A Database Testing Power Tool
7
star
73

remote-junit-runner

JUnit runner that executes tests in a remote JVM
Java
7
star
74

cass-config-builder

Configuration builder for Apache Cassandra based on definitions at datastax/cass-config-definitions
Clojure
7
star
75

astra-db-chatbot-starter

Python
6
star
76

java-driver-scala-extras

Scala extensions and utilities for the DataStax Java Driver
Scala
6
star
77

burnell

A proxy to Pulsar cluster
Go
6
star
78

ai-agent-java

AI Agent Starter in Java
6
star
79

gatling-dse-stress

Scala
5
star
80

gatling-dse-simcatalog

Scala
4
star
81

ds-support-diagnostic-collection

Scripts for collection of diagnostic information from DSE/Cassandra clusters running on various platforms
Shell
4
star
82

java-quotient-filter

A Java Quotient Filter implementation.
Java
4
star
83

charts

DataStax Helm Charts
Shell
4
star
84

pulsar-ansible

Shell
4
star
85

ragstack-ai-ts

TypeScript
4
star
86

astra-ide-plugin

Kotlin
3
star
87

terraform-helm-oci-release

HCL
3
star
88

cass-config-definitions

Shell
3
star
89

go-cassandra-simple-client

A simple Go client for the Cassandra native protocol
3
star
90

doyouknowyourstuff

Astro
3
star
91

terraform-datastax-ai-stack

3
star
92

astra-db-recommendations-starter

TypeScript
2
star
93

java-driver-examples-osgi

Examples showing the usage of the DataStax Java driver in OSGi applications.
Java
2
star
94

nodejs-driver-graph

DataStax Node.js Driver Extensions for DSE Graph
JavaScript
2
star
95

aws-secrets-manager-integration-astra

Python
2
star
96

starlight-for-grpc

Java
2
star
97

homebrew-luna-streaming-shell

Shell
2
star
98

astra-block-examples

Various Astra Block Examples
TypeScript
2
star
99

cassandra-drivers-smoke-test

Smoke tests for Apache Cassandra using the DataStax Drivers
Shell
2
star
100

junitpytest

JUnit5 plugin to run pytest via Gradle
Java
2
star