‣ CQL Proxy
This page is a copy
This page is a copy of CQL PROXY Reference Documentation. if you encounter some discrepancies please open a JIRA in our repository.
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.
cql-proxy was made as a genrally available release on
2/16/2022. See this blog for additional details.
Please give it a try and let us know what you think!
When to use
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.
--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) -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) --num-conns=1 Number of connection to create to each node of the backend cluster ($NUM_CONNS) --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.
docker run -p 9042:9042 \ --rm datastax/cql-proxy:v0.1.2 \ --astra-token <astra-token> --astra-database-id <astra-datbase-id>
Using environment variables¶
docker run -p 9042:9042 \ --rm datastax/cql-proxy:v0.1.2 \ -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:
All configuration keys match their command-line flag counterpart, e.g.
Setting up peer proxies¶
Multi-region failover with DC-aware load balancing policy is the most useful case for a multiple proxy setup.
peers: it is required to set
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.
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 --passowrd <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 --passowrd <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.peers table to properly setup the peers
data-center: values. Here's an example
Note: It's okay for the
peers: to contain entries for the current proxy itself because they'll just be omitted.
There are three methods for using
- Locally build and run
- Run a docker image that has
- Install locally on a Mac with Homebrew
- Use a Kubernetes container to run
Locally build and run¶
Run with your desired database.
DataStax Astra cluster:
<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:
Apache Cassandra cluster:
cql-proxy docker image¶
Run with your desired database.
- DataStax Astra cluster:
docker run -p 9042:9042 \ datastax/cql-proxy:v0.1.2 \ --astra-token <astra-token> --astra-database-id <astra-database-id>
<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.2 \ --astra-bundle /tmp/scb.zip --username <astra-client-id> --password <astra-client-secret>
Apache Cassandra cluster:
If you wish to have the docker image removed after you are done with it, add
--rmbefore the image name
Homebrew on a Mac¶
Install with one simple command:
Using Kubernetes with
cql-proxy requires a number of steps:
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.zipto match the example below.
cql-proxy.yaml. You'll need to add three sets of information: arguments, volume mounts, and volumes.
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
configMapfilename as required. In this example, it is named
cql-proxy-configmap. Use the same name for the
volumesthat you used for the
volumes: - name: my-cm-vol configMap: name: cql-proxy-configmap
Create a configmap. Use the same secure bundle that was specified in the
- Check the configmap that was created.
kubectl describe configmap config Name: config Namespace: default Labels: <none> Annotations: <none> Data ==== BinaryData ==== scb.zip: 12311 bytes
- Create a Kubernetes deployment with the YAML file you created:
- Check the logs:
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.