testConnection

Test PostgreSQL native interface database connection

Since R2020b

Syntax

status = testConnection(opts,username,password)

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

Description

status = testConnection(opts,username,password) tests the PostgreSQL native interface database connection specified by the SQLConnectionOptions 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 PostgreSQL Native Interface Data Source

Create, configure, test, and save a PostgreSQL native interface data source for a PostgreSQL database.

Create a PostgreSQL native interface data source for a PostgreSQL native interface database connection.

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

opts = 
  SQLConnectionOptions with properties:

              DataSourceName: ""
                      Vendor: "PostgreSQL"

                DatabaseName: ""
                      Server: "localhost"
                  PortNumber: 5432

opts is an SQLConnectionOptions object with these properties:

• DataSourceName — Name of the data source

• Vendor — Database vendor name

• DatabaseName — Name of the database

• Server — Name of the database server

• PortNumber — Port number

Configure the data source by setting the database connection options for the data source PostgreSQLDataSource, database name toystore_doc, database server dbtb00, and port number 5432.

opts = setoptions(opts, ...
    'DataSourceName',"PostgreSQLDataSource", ...
    'DatabaseName',"toystore_doc",'Server',"dbtb00", ...
    'PortNumber',5432)

opts = 
  SQLConnectionOptions with properties:

              DataSourceName: "PostgreSQLDataSource"
                      Vendor: "PostgreSQL"

                DatabaseName: "toystore_doc"
                      Server: "dbtb00"
                  PortNumber: 5432

The setoptions function sets the DataSourceName, DatabaseName, Server, and PortNumber properties in the SQLConnectionOptions object.

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

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

status = logical
   1

Save the configured data source.

saveAsDataSource(opts)

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

Retrieve Message for PostgreSQL Native Interface Database Connection Test

Create and configure a PostgreSQL native interface data source to a PostgreSQL database. Test the database connection to the PostgreSQL native interface data source and retrieve the error message.

Create a PostgreSQL native interface data source for a PostgreSQL database connection.

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

opts = 
  SQLConnectionOptions with properties:

              DataSourceName: ""
                      Vendor: "PostgreSQL"

                DatabaseName: ""
                      Server: "localhost"
                  PortNumber: 5432

opts is an SQLConnectionOptions object with these properties:

• DataSourceName — Name of the data source

• Vendor — Database vendor name

• DatabaseName — Name of the database

• Server — Name of the database server

• PortNumber — Port number

Configure the data source by setting the database connection options for the data source PostgreSQLDataSource, database name toystore_doc, database server dbtb00, and port number 5432.

opts = setoptions(opts, ...
    'DataSourceName',"PostgreSQLDataSource", ...
    'DatabaseName',"toystore_doc",'Server',"dbtb00", ...
    'PortNumber',5432)

opts = 
  SQLConnectionOptions with properties:

              DataSourceName: "PostgreSQLDataSource"
                      Vendor: "PostgreSQL"

                DatabaseName: "toystore_doc"
                      Server: "dbtb00"
                  PortNumber: 5432

The setoptions function sets the DataSourceName, DatabaseName, Server, and PortNumber properties in the SQLConnectionOptions object.

Test the database connection using an incorrect user name and password. The testConnection function returns the logical 0, which indicates the database connection fails. Retrieve and display the error message for the failed connection.

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

status = logical
   0

message =
    'Driver Error: FATAL:  password authentication failed for user "wronguser"
    FATAL:  password authentication failed for user "wronguser"
    '

Input Arguments

opts — Database connection options

SQLConnectionOptions object

Database connection options, specified as an SQLConnectionOptions 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 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 describing the failed database connection.

Version History

Introduced in R2020b