Connect to IBM Cloud Object Storage Data as a Linked Server

You can use the SQL Gateway to configure a TDS (SQL Server) remoting service and set up a linked server for IBM Cloud Object Storage data. After you have started the service, you can use the UI in SQL Server Management Studio or call stored procedures to create the linked server. You can then work with IBM Cloud Object Storage data just as you would a linked SQL Server instance.

Connect to IBM Cloud Object Storage as an ODBC Data Source

If you have not already, first specify connection properties in an ODBC DSN (data source name). This is the last step of the driver installation. You can use the Microsoft ODBC Data Source Administrator to create and configure ODBC DSNs.

Register a New Instance of Cloud Object Storage

If you do not already have Cloud Object Storage in your IBM Cloud account, follow the procedure below to install an instance of SQL Query in your account:

1. Log in to your IBM Cloud account.
2. Navigate to the page, choose a name for your instance and click Create. You will be redirected to the instance of Cloud Object Storage you just created.

Connecting using OAuth Authentication

There are certain connection properties you need to set before you can connect. You can obtain these as follows:

API Key

To connect with IBM Cloud Object Storage, you need an API Key. You can obtain this as follows:

1. Log in to your IBM Cloud account.
2. Navigate to the Platform API Keys page.
3. On the middle-right corner click "Create an IBM Cloud API Key" to create a new API Key.
4. In the pop-up window, specify the API Key name and click "Create". Note the API Key as you can never access it again from the dashboard.

Cloud Object Storage CRN

If you have multiple accounts, you will need to specify the CloudObjectStorageCRN explicitly. To find the appropriate value, you can:

• Query the Services view. This will list your IBM Cloud Object Storage instances along with the CRN for each.
• Locate the CRN directly in IBM Cloud. To do so, navigate to your IBM Cloud Dashboard. In the Resource List, Under Storage, select your Cloud Object Storage resource to get its CRN.

Connecting to Data

You can now set the following to connect to data:

• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
• ApiKey: Set this to your API key which was noted during setup.
• CloudObjectStorageCRN (Optional): Set this to the cloud object storage CRN you want to work with. While the connector attempts to retrieve this automatically, specifying this explicitly is recommended if you have more than Cloud Object Storage account.

When you connect, the connector completes the OAuth process.

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

Configure the TDS Remoting Service

See the SQL Gateway Overview for a guide to configure a TDS remoting service in the SQL Gateway UI. The TDS remoting service is a daemon process that listens for TDS requests from clients.

Create a Linked Server for IBM Cloud Object Storage Data

After you have configured and started the daemon, create the linked server and connect. You can use the UI in SQL Server Management Studio or call stored procedures.

Create a Linked Server from the UI

Follow the steps below to create a linked server from the Object Explorer.

1. Open SQL Server Management Studio and connect to an instance of SQL Server.
2. In the Object Explorer, expand the node for the SQL Server database. In the Server Objects node, right-click Linked Servers and click New Linked Server. The New Linked Server dialog is displayed.
3. In the General section, click the Other Data Source option and enter the following information after naming the linked server:
   • Provider: Select the SQL Server Native Client Provider that corresponds to your version of SQL Server. For example, SQL Server Native Client 11.0.

   • Data Source: Enter the host and port the TDS remoting service is running on, separated by a comma.

     Note that a value of "localhost" in this input refers to the machine where SQL Server is running so be careful when creating a linked server in Management Studio when not running on the same machine as SQL Server.

   • Catalog: Enter the CData system DSN, CData IBMCloudObjectStorage Sys.
4. In the Security section, select the option to have the connection "made using this security context" and enter the username and password of a user you created in the Users tab of the SQL Gateway.

Create a Linked Server Programmatically

In addition to using the SQL Server Management Studio UI to create a linked server, you can use stored procedures. The following inputs are required:

• server: The linked server name.
• provider: Enter "SQLNCLI", for the SQL Server Native Client Provider.

• datasrc: The host and port the service is running on, separated by a comma.

  Note that a value of "localhost" in the datasrc input refers to the machine where SQL Server is running, so be careful when creating a linked server in Management Studio when not running on the same machine as SQL Server.

• catalog: Enter the system DSN configured for the service.
• srvproduct: Enter the product name of the data source; this can be an arbitrary value, such as "CData SQL Gateway" or an empty string.

1. Call sp_addlinkedserver to create the linked server:

   EXEC sp_addlinkedserver @server='IBMCloudObjectStorage', @provider='SQLNCLI', @datasrc='< MachineIPAddress >,1434', @catalog='CData IBMCloudObjectStorage Sys', @srvproduct=''; GO

2. Call the sp_addlinkedsrvlogin stored procedure to allow SQL Server users to connect with the credentials of an authorized user of the service. Note that the credentials you use to connect to the service must specify a user you configured on the Users tab of the SQL Gateway.

   EXEC sp_addlinkedsrvlogin @rmtsrvname='IBMCloudObjectStorage', @rmtuser='admin', @rmtpassword='test', @useself='FALSE', @locallogin=NULL; GO

Connect from SQL Server Management Studio

SQL Server Management Studio uses the SQL Server Client OLE DB provider, which requires the ODBC driver to be used inprocess. You must enable the "Allow inprocess" option for the SQL Server Native Client Provider in Management Studio to query the linked server from SQL Server Management Studio. To do this, open the properties for the provider you are using under Server Objects -> Linked Servers -> Providers. Check the "Allow inprocess" option and save the changes.

Execute Queries

You can now execute queries to the IBM Cloud Object Storage linked server from any tool that can connect to SQL Server. Set the table name accordingly: