Creating a JDBC Data Source

You can create a JDBC data source to connect from your Java application. Creating a JDBC data source based on the CData JDBC Driver for Cloudant consists of three basic steps:

• Add the driver JAR file to the classpath. The JAR file is located in the lib subfolder of the installation directory. Note that the .lic file must be located in the same folder as the JAR file.
• Provide the driver class. For example:
  

  cdata.jdbc.cloudant.CloudantDriver

• Provide the JDBC URL. For example:
  

  jdbc:cloudant:User=abc123; Password=abcdef;
  
  or
  
  jdbc:cdata:cloudant:User=abc123; Password=abcdef;

  The second format above can be used whenever there is a conflict in your application between drivers using the same URL format to ensure you are using the CData driver. The URL must start with either "jdbc:cloudant:" or "jdbc:cdata:cloudant:" and can include any of the connection properties in name-value pairs separated with semicolons.

Authenticating to Cloudant

Cloudant supports three type of authentication:

• Auto (default): the driver decides how to authenticate you, based on the other connection properties you have set.
• Basic: Basic username/password authentication. Set AuthScheme to Basic.
• OAuth: Performs authentication based on the OAuth standard. Set AuthScheme to OAuth and supply the values for the Cloudant instance APIKey and URL.

IBM Cloudant Legacy

To connect via IBM Cloudant Legacy, ensure that you have a valid IBM Cloudant service credential.

To create an IBM Cloudant service credential:

1. Log in to the IBM Cloud dashboard.
2. Navigate to the Menu icon > Resource List, and open your IBM Cloudant service instance.
3. In the menu, click Service credentials.
4. Click New credential. Cloudant displays a Add new credential window.
5. Enter a name for the new credential.
6. Click Add. Your credentials are added to the Service credentials table.
7. Click Actions > View credentials.
8. Extract the values for User and Password from the JSON file.

Use the values you just obtained to set the User and Password.

IBM Cloud IAM

IBM Cloud IAM is OAuth-based authentication accessed via a web browser.

To authenticate to IBM Cloud, set AuthScheme to OAuth and supply the ApiKey and the Url of the target Cloudant instance (for example, https://0c9d3837-8304-4aab-a65a-648169970943-bluemix.cloudant.com).

After setting InitiateOAuth to GETANDREFRESH (default), you are ready to connect.

When you connect, the driver completes the OAuth process.

1. Extracts the access token and authenticates requests.
2. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.

Retrieving OAuth connection properties

To retrieve the OAuth connection properties:

1. Create an account in IBM Cloud.
2. Obtain the ApiKey:
   1. Log in to your IBM Cloud account.
   2. Navigate to Platform API Keys page.
   3. To create a new API Key, click Create an IBM Cloud API Key. Cloudant displays a pop-up form.
   4. Specify the API Key name and click Create. Cloudant displays the ApiKey you just created.
      Save this information for future reference.

Registering a new instance of Cloudant

If you do not already have Cloud Object Storage in your IBM Cloud account, you can install an instance of SQL Query in your account:

1. Log in to your IBM Cloud account.
2. Navigate to the Cloudant page.
3. Choose a name for your instance and click Create. You are redirected to that Cloudant instance.

Authenticating to a Local Instance

Cloudant supports authenticating to data in local instances from version 1.1.0 and above.

To authenticate to your local instance, set these parameters:

1. Url: The Url of your local instance. For example: http://localhost:8006
2. User: Your username.
3. Password: Your password.