connection

Relational database JDBC connection

Description

Create a database connection using a JDBC driver. For details about JDBC drivers and the alternative ODBC drivers, see Choose Between ODBC and JDBC Drivers.

You can use the connection object to connect to various databases using different drivers that you install and administer. For details, see Connect to Database.

Creation

Create a connection object using the database function.

Properties

Connection Properties

DataSource — Data source name

'' (default) | character vector

This property is read-only.

Database name for JDBC connection, specified as a character vector. DataSource is the name of your database. The name differs for different database systems. For example, DataSource is the SID or the service name when you are connecting to an Oracle^® database. Or, DataSource is the catalog name when you are connecting to a MySQL^® database. For details about your database name, contact your database administrator or refer to your database documentation.

The data source name is an empty character vector when the connection is invalid.

Example: 'MS SQL Server'

Data Types: char

UserName — User name

'' (default) | character vector

This property is read-only.

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

Example: 'username'

Data Types: char

Message — Database connection status message

'' (default) | character vector

This property is read-only.

Database connection status message, specified as a character vector. The status message is empty when the database connection is successful. Otherwise, this property contains an error message.

Example: 'JDBC Driver Error: [Micro ...'

Data Types: char

Type — Database connection type

'JDBC Connection Object'

This property is read-only.

Database connection type, specified as the value 'JDBC Connection Object' that means a database connection created using a JDBC driver.

Data Types: char

JDBC Connection Properties

Driver — JDBC driver

'' (default) | character vector

This property is read-only.

JDBC driver, specified as a character vector when connecting to a database using a JDBC driver URL. This property depends on the URL property.

Example: 'com.mysql.jdbc.jdbc2.opti ...'

Data Types: char

URL — Database connection URL

'' (default) | character vector

This property is read-only.

Database connection URL, specified as a character vector for a vendor-specific string. This property depends on the Driver property.

Example: 'jdbc:mysql://sname:1234/ ...'

Data Types: char

Database Properties

AutoCommit — Flag to autocommit transactions

'on' (default) | 'off'

Flag to autocommit transactions, specified as one of these values:

• 'on' — Database transactions are automatically committed to the database.

• 'off' — Database transactions must be committed to the database manually.

Example: 'AutoCommit','off'

ReadOnly — Read-only database data

'off' (default) | 'on'

Read-only database data, specified as one of these values:

• 'on' — Database data is read-only.

• 'off' — Database data is writable.

Data Types: char

LoginTimeout — Login timeout

0 (default) | positive numeric scalar

This property is read-only.

Login timeout, specified as a positive numeric scalar. The login timeout specifies the number of seconds that the driver waits while trying to connect to a database before throwing an error.

When no login timeout for the connection attempt is specified, the value is 0.

When login timeout is not supported by the database, the value is -1.

Data Types: double

MaxDatabaseConnections — Maximum database connections

-1 (default) | positive numeric scalar

This property is read-only.

Maximum database connections, specified as a positive, numeric scalar.

The value is 0 when there is no upper limit to the maximum number of database connections.

When the maximum number of database connections is not supported by the database, the value is -1.

Data Types: double

Catalog and Schema Information

DefaultCatalog — Default catalog name

'' (default) | character vector

This property is read-only.

Default catalog name, specified as a character vector.

When a database does not specify a default catalog, the value is an empty character vector ''.

Example: 'catalog'

Data Types: char

Catalogs — Catalog names

{} (default) | cell array of character vectors

This property is read-only.

Catalog names, specified as a cell array of character vectors.

When a database does not contain catalogs, the value is an empty cell array {}.

Example: {'catalog1', 'catalog2'}

Data Types: cell

Schemas — Schema names

{} (default) | cell array of character vectors

This property is read-only.

Schema names, specified as a cell array of character vectors.

When a database does not contain schemas, the value is an empty cell array {}.

Example: {'schema1', 'schema2', 'schema3'}

Data Types: cell

Database and Driver Information

DatabaseProductName — Database product name

'' (default) | character vector

This property is read-only.

Database product name, specified as a character vector.

When the database connection is invalid, the value is an empty character vector ''.

Example: 'Microsoft SQL Server'

Data Types: char

DatabaseProductVersion — Database product version

'' (default) | character vector

This property is read-only.

Database product version, specified as a character vector.

When the database connection is invalid, the value is an empty character vector ''.

Example: '11.00.2100'

Data Types: char

DriverName — Driver name

'' (default) | character vector

This property is read-only.

Driver name of a JDBC driver, specified as a character vector.

When the database connection is invalid, the value is an empty character vector ''.

Example: 'sqlncli11.dll'

Data Types: char

DriverVersion — Driver version

'' (default) | character vector

This property is read-only.

Driver version of a JDBC driver, specified as a character vector.

When the database connection is invalid, the value is an empty character vector ''.

Example: '11.00.5058'

Data Types: char

Object Functions

close	Close and invalidate database and driver resource utilizer
commit	Make database changes permanent
execute	Execute SQL statement using relational database connection
fetch	Import data into MATLAB workspace from execution of SQL statement
isopen	Determine if database connection is open
rollback	Undo database changes
executeSQLScript	Execute SQL script on database
select	Execute SQL SELECT statement and import data into MATLAB
sqlfind	Find information about all table types in database
sqlinnerjoin	Inner join between two database tables
sqlouterjoin	Outer join between two database tables
sqlread	Import data into MATLAB from database table
sqlwrite	Insert MATLAB data into database table
sqlupdate	Update rows in database table
update	Replace data in database table with MATLAB data
runstoredprocedure	Call stored procedure with and without input and output arguments

Examples

Connect to Oracle Using JDBC Driver

Create a JDBC connection to an Oracle database. To create this connection, you must configure a JDBC data source. For more information, see the databaseConnectionOptions function. Then, import data from the database into MATLAB^®, perform simple data analysis, and close the database connection.

This example assumes that you are connecting to an Oracle Database 12c Enterprise Edition Release 12.1.0.2.0 using the Oracle JDBC Driver 12.1.0.1.0.

Connect to the database using a JDBC data source name, user name, and password.

datasource = 'dsname';
username = 'username';
password = 'pwd';

conn = database(datasource,username,password)

conn = 

  connection with properties:

                  DataSource: 'dsname'
                    UserName: 'username'
                      Driver: 'oracle.jdbc.pool.OracleDa ...'
                         URL: 'jdbc:oracle:thin:@(DESCRI ...'
                     Message: ''
                        Type: 'JDBC Connection Object'
  Database Properties:

                  AutoCommit: 'on'
                    ReadOnly: 'off'
                LoginTimeout: 0
      MaxDatabaseConnections: 0

  Catalog and Schema Information:

              DefaultCatalog: ''
                    Catalogs: {}
                     Schemas: {'schema1', 'schema2', 'schema3' ... and 39 more}

  Database and Driver Information:

         DatabaseProductName: 'Oracle'
      DatabaseProductVersion: 'Oracle Database 12c Enter ...'
                  DriverName: 'Oracle JDBC driver'
               DriverVersion: '12.1.0.1.0'

conn has an empty Message property, which indicates a successful connection.

The property sections of the connection object are:

• Database Properties — Information about the database configuration

• Catalog and Schema Information — Names of catalogs and schemas in the database

• Database and Driver Information — Names and versions of the database and driver

Import all data from the table inventoryTable into MATLAB using the select function. Display the data.

selectquery = 'SELECT * FROM inventoryTable';
data = select(conn,selectquery)

ans = 

    productnumber    quantity    price         inventorydate     
    _____________    ________    _____    _______________________

     1               1700        14.5     '2014-09-23 09:38:34.0'
     2               1200         9.3     '2014-07-08 22:50:45.0'
     3                356        17.2     '2014-05-14 07:14:28.0'
     ...

Determine the highest product quantity in the table.

max(data.Quantity)

ans =

        9000

Close the database connection.

close(conn)

Alternative Functionality

You can connect to an SQLite database file by creating the sqlite object. This connection uses the MATLAB interface to SQLite that does not require installing or administering a database or driver. For details, see Interact with Data in SQLite Database Using MATLAB Interface to SQLite.

Version History

Introduced before R2006a