testConnection

Test Apache Cassandra database connection

Since R2021a

Syntax

status = testConnection(opts,username,password)

[status,message] = testConnection(opts,username,password)

Description

status = testConnection(opts,username,password) tests the Apache Cassandra^® database connection specified by the CassandraConnectionOptions object opts, a user name, and a password.

[status,message] = testConnection(opts,username,password) also returns the error message associated with testing the database connection.

Examples

Create Cassandra Data Source and Set Connection Options

Configure an Apache™ Cassandra® database connection by creating a Cassandra data source, setting the Cassandra connection options, and saving the data source.

Create a Cassandra data source for a Cassandra database connection.

vendor = "Cassandra";
opts = databaseConnectionOptions("native",vendor)

opts = 
  CassandraConnectionOptions with properties:

              DataSourceName: ""
                      Vendor: "Cassandra"

               ContactPoints: "localhost"
                  PortNumber: 9042
                  SSLEnabled: false
                LoginTimeout: 5
              RequestTimeout: 12

opts is an CassandraConnectionOptions object with these properties:

• DataSourceName — Name of the data source

• Vendor — Database vendor name

• ContactPoints — Contact points

• PortNumber — Port number

• SSLEnabled — SSL-enabled connection

• LoginTimeout — Login timeout

• RequestTimeout — Request timeout

Configure the data source by setting the Cassandra connection options for the data source CassandraDataSource, local host address for one node in the cluster, port number 9042, SSL encryption that is disabled, login timeout of 5 seconds, and request timeout of 12 seconds.

opts = setoptions(opts, ...
    "DataSourceName","CassandraDataSource", ...
    "ContactPoints","localhost","PortNumber",9042, ...
    "SSLEnabled",false,"LoginTimeout",5, ...
    "RequestTimeout",12)

opts = 
  CassandraConnectionOptions with properties:

              DataSourceName: "CassandraDataSource"
                      Vendor: "Cassandra"

               ContactPoints: "localhost"
                  PortNumber: 9042
                  SSLEnabled: false
                LoginTimeout: 5
              RequestTimeout: 12

The setoptions function sets the DataSourceName, ContactPoints, PortNumber, SSLEnabled, LoginTimeout, and RequestTimeout properties in the CassandraConnectionOptions object.

Test the database connection with a blank user name and password. The testConnection function returns the logical 1, which indicates the database connection is successful.

username = "";
password = "";
status = testConnection(opts,username,password)

status = logical
   1

Save the configured data source.

saveAsDataSource(opts)

Retrieve Message for Apache Cassandra Database Connection Test

Create and configure a Cassandra data source to a Cassandra database. Test the database connection to the Cassandra data source and retrieve the error message.

Create a Cassandra data source for a Cassandra database connection.

vendor = "Cassandra";
opts = databaseConnectionOptions("native",vendor)

opts = 
  CassandraConnectionOptions with properties:

              DataSourceName: ""
                      Vendor: "Cassandra"

               ContactPoints: "localhost"
                  PortNumber: 9042
                  SSLEnabled: false
                LoginTimeout: 5
              RequestTimeout: 12

opts is a CassandraConnectionOptions object with these properties:

• DataSourceName — Name of the data source

• Vendor — Database vendor name

• ContactPoints — Contact points

• PortNumber — Port number

• SSLEnabled — SSL-enabled connection

• LoginTimeout — Login timeout

• RequestTimeout — Request timeout

Configure the data source by setting the Cassandra connection options for the data source CassandraDataSource, local host address for one node in the cluster, port number 1500, SSL encryption that is disabled, login timeout of 5 seconds, and request timeout of 12 seconds. In this case, the port number is invalid.

opts = setoptions(opts, ...
    "DataSourceName","CassandraDataSource", ...
    "ContactPoints","localhost","PortNumber",1500, ...
    "SSLEnabled",false,"LoginTimeout",5, ...
    "RequestTimeout",12)

opts = 
  CassandraConnectionOptions with properties:

              DataSourceName: "CassandraDataSource"
                      Vendor: "Cassandra"

               ContactPoints: "localhost"
                  PortNumber: 1500
                  SSLEnabled: false
                LoginTimeout: 5
              RequestTimeout: 12

The setoptions function sets the DataSourceName, ContactPoints, PortNumber, SSLEnabled, LoginTimeout, and RequestTimeout properties in the CassandraConnectionOptions object.

Test the database connection using a blank user name and password. The testConnection function returns the logical 0, which indicates the database connection fails because the port number is invalid. Retrieve and display the error message for the failed connection.

username = "";
password = "";
[status,message] = testConnection(opts,username,password)

status =

  logical

   0


message =

    'Cassandra exception: Underlying connection error: Connect error 'connection refused''

Input Arguments

opts — Database connection options

CassandraConnectionOptions object

Database connection options, specified as a CassandraConnectionOptions object.

username — User name

character vector | string scalar

User name required to access the database, specified as a character vector or string scalar. If no user name is required, specify an empty value "".

Data Types: char | string

password — Password

character vector | string scalar

Password required to access the database, specified as a character vector or string scalar. If no password is required, specify an empty value "".

Data Types: char | string

Output Arguments

status — Connection status

logical

Connection status, returned as a logical true if the connection test passes or false if the connection test fails.

message — Error message

character vector

Error message, returned as a character vector. If the connection test passes, then the error message is an empty character vector. Otherwise, the error message contains text from the failed database connection.

Version History

Introduced in R2021a