Connect with the Python driver
DataStax recommends the Data API and clients for Serverless (Vector) databases. You can use the Data API to perform CQL operations on your table data in Serverless (Vector) databases. DataStax recommends drivers only for Serverless (Non-Vector) databases, legacy applications that rely on a driver, or for CQL functions that aren’t supported by the Data API. For more information, see Compare connection methods. |
To use the DataStax Python driver, you need to install the driver and its dependencies, and then connect the driver to your Astra DB Serverless database. Once connected, you can write scripts that use the driver to run commands against your database.
Prerequisites
-
Set the following environment variables:
-
ASTRA_DB_ID
: The database ID -
ASTRA_DB_REGION
: A region where your database is deployed and where you want to connect to the database, such asus-east-2
-
ASTRA_DB_KEYSPACE
: A keyspace in your database, such asdefault_keyspace
-
ASTRA_DB_APPLICATION_TOKEN
: An application token with the Database Administrator role.The
token.json
has the following format:{ "clientId": "CLIENT_ID", "secret": "CLIENT_SECRET", "token": "APPLICATION_TOKEN" }
For driver authentication, you can use either
clientId
andsecret
or the literal stringtoken
and theAstraCS
token value. If you are on an older driver version that doesn’t support thetoken
option, then you might need to useclientId
andsecret
. For more information, see Token details.
-
-
Download your database’s Secure Connect Bundle (SCB).
-
Install Python 3.7 or later.
-
Install pip version 23.0 or later.
Install the Python driver
-
Install the DataStax Python driver:
pip install cassandra-driver
Make sure you use a driver version that is compatible with Astra DB. For more information, see DataStax driver matrix.
Connect the Python driver
-
In the root of your Python project, create a
connect_database.py
file:cd python_project touch connect_database.py
-
In
connect_database.py
, add code to import the necessary libraries and establish a connection to your database.-
Production configuration
-
Basic configuration
Use this configuration is for proofs of concept or production use.
This configuration initializes a session to connect to your database with the
cassandra-driver
. It uses an SCB and authentication credentials stored in environment variables. Additionally, it includes options for connection timeout, request timeout, and protocol version.connect-database.pyimport os from cassandra.cluster import Cluster, ExecutionProfile, EXEC_PROFILE_DEFAULT, ProtocolVersion from cassandra.auth import PlainTextAuthProvider import json cloud_config= { 'secure_connect_bundle': "PATH_TO_SCB", 'connect_timeout': 30 } auth_provider=PlainTextAuthProvider("token", os.environ["ASTRA_DB_APPLICATION_TOKEN"]) profile = ExecutionProfile(request_timeout=30) cluster = Cluster( cloud=cloud_config, auth_provider=auth_provider, execution_profiles={EXEC_PROFILE_DEFAULT: profile}, protocol_version=ProtocolVersion.V4 ) session = cluster.connect()
Replace
PATH_TO_SCB
with the absolute path to your database’s Secure Connect Bundle (SCB) (secure-connect-DATABASE_NAME.zip
).DataStax doesn’t recommend this configuration for basic proofs of concept or production use.
The basic configuration initializes a session to connect to your database with the
cassandra-driver
. It uses an SCB and authentication credentials stored in environment variables.connect-database.pyimport os from cassandra.cluster import Cluster from cassandra.auth import PlainTextAuthProvider import json session = Cluster( cloud={"secure_connect_bundle": "PATH_TO_SCB"}, auth_provider=PlainTextAuthProvider("token", os.environ["ASTRA_DB_APPLICATION_TOKEN"]), ).connect()
Replace
PATH_TO_SCB
with the absolute path to your database’s Secure Connect Bundle (SCB) (secure-connect-DATABASE_NAME.zip
). -
The connection code creates a Cluster
instance to connect to your Astra DB database.
You typically have one instance of Cluster for each Astra DB database that you want to interact with.
Run commands with the Python driver
After you connect to the database, you can use the driver to perform operations on your database. For example:
-
Add code to run a CQL query and print the output to the console:
row = session.execute("select release_version from system.local").one() if row: print(row[0]) else: print("An error occurred.")
-
Save and run your Python script:
python ./connect_database.py
The output prints the
release_version
value from thesystem.local
table in your Astra DB database.
You can extend or modify this example script to run other commands against your database or connect to other databases. For more examples and information, see Python driver quickstart, Python driver documentation, and Developing applications with DataStax drivers.