testConnection

(To be removed) Test JDBC data source connection

The testConnection function will be removed in a future release. Use the testConnection function of the SQLConnectionOptions object instead. For details, see Version History.

Syntax

status = testConnection(opts,username,password)

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

Description

status = testConnection(opts,username,password) tests the JDBC data source connection specified by the JDBCConnectionOptions 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 JDBC Data Source

Create, configure, test, and save a JDBC data source for a Microsoft^® SQL Server^® database.

Create an SQL Server data source.

opts = configureJDBCDataSource('Vendor','Microsoft SQL Server')

opts = 

  JDBCConnectionOptions with properties:

                      Vendor: 'Microsoft SQL Server'
              DataSourceName: ''

                DatabaseName: ''
                      Server: 'localhost'
                  PortNumber: 1433
                    AuthType: 'Server'

          JDBCDriverLocation: ''

opts is a JDBCConnectionOptions object with these properties:

• Vendor — Database vendor name

• DataSourceName — Name of the data source

• DatabaseName — Name of the database

• Server — Name of the database server

• PortNumber — Port number

• AuthType — Authentication type

• JDBCDriverLocation — Full path of the JDBC driver file

Configure the data source by setting the JDBC connection options for the data source SQLServerDataSource, database server dbtb04, port number 54317, full path to the JDBC driver file, and Windows® authentication.

opts = setConnectionOptions(opts, ...
    'DataSourceName','SQLServerDataSource', ...
    'Server','dbtb04','PortNumber',54317, ...
    'JDBCDriverLocation','C:\Drivers\sqljdbc4.jar', ...
    'AuthType','Windows')

opts = 

  JDBCConnectionOptions with properties:

                      Vendor: 'Microsoft SQL Server'
              DataSourceName: 'SQLServerDataSource'

                DatabaseName: ''
                      Server: 'dbtb04'
                  PortNumber: 54317
                    AuthType: 'Windows'

          JDBCDriverLocation: 'C:\Drivers\sqljdbc4.jar'

The setConnectionOptions function sets the DataSourceName, Server, PortNumber, AuthType, and JDBCDriverLocation properties in the JDBCConnectionOptions 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.

saveAsJDBCDataSource(opts)

You can connect to the new data source using the database function or the Database Explorer app.

Input Arguments

opts — JDBC connection options

JDBCConnectionOptions object

JDBC connection options, specified as a JDBCConnectionOptions object.

username — Username

character vector | string scalar

Username required to access the database, specified as a character vector or string scalar. If no username is required, specify an empty value "". Provide this username if you do not store it as part of the data source when using the Database Explorer app to make a connection.

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 "". Provide this password if you do not store it as part of the data source when using the Database Explorer app to make a connection.

Data Types: char | string

Output Arguments

status — Connection status

logical

Connection status, returned as a logical true if the connection test passes or a logical 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 resulting failure in database connection.

Alternative Functionality

App

You can test a JDBC data source connection by using the JDBC Data Source Configuration dialog box in the Database Explorer app. In the Data Source section of the Database Explorer tab, select Configure Data Source > Configure JDBC data source.

Version History

Introduced in R2019b

R2020b: testConnection function will be removed

The testConnection function will be removed in a future release. Use the testConnection function of the SQLConnectionOptions object instead. Some differences between the workflows might require updates to your code.

Update Code

Use the testConnection function with the SQLConnectionOptions object to test the specified JDBC connection options.

In prior releases, you configured a JDBC data source using the JDBCConnectionOptions object. For example:

opts = configureJDBCDataSource('Vendor','Microsoft SQL Server');
opts = setConnectionOptions(opts, ...
    'DataSourceName','SQLServerDataSource', ...
    'Server','dbtb04','PortNumber',54317, ...
    'JDBCDriverLocation','C:\Drivers\sqljdbc4.jar', ...
    'AuthType','Windows');
username = "";
password = "";
status = testConnection(opts,username,password);
saveAsJDBCDataSource(opts)

Now you can set JDBC connection options and save the data source using the SQLConnectionOptions object instead.

vendor = "Microsoft SQL Server";
opts = databaseConnectionOptions("jdbc",vendor);
opts = setoptions(opts, ...
    'DataSourceName',"SQLServerDataSource", ...
    'JDBCDriverLocation',"C:\Drivers\sqljdbc4.jar", ...
    'DatabaseName',"toystore_doc",'Server',"dbtb04", ...
    'PortNumber',54317,'AuthType',"Windows");
username = "";
password = "";
status = testConnection(opts,username,password);
saveAsDataSource(opts)