JDBC drivers power many traditional data tools, such as SQL Editors, BI and Visualization tools, ETL tools, and more. Space and Time (SXT) addition of a JDBC driver allows for wide adoption of those traditional tools.

📘

These instructions walk you through connecting to Space and Time via the open-source SQL editor DBeaver. The steps will vary slightly depending on your SQL editor, but the general concepts are the same.

Requirements

• Download the latest version of the SxT JDBC driver jar and save it somewhere on your local disk, for example, under the "Applications" or "Program Files" directory. Most use-cases only require the .jar file, the .pom file can be ignored:

  

• Download DBeaver(or another SQL editor or choice)

Set up the JDBC Driver

Step 1: Add a new driver

Add the .jar file as a new driver in your SQL editor. How you do this depends on the tool - below outlines instructions for DBeaver, but most tools will be somewhat similar.

DBeaver instructions:

• Open the "Database Menu" → "Driver Manager" → "New"
• Select the "Libraries" tab and "Add File"
• Navigate to the SxT JDBC driver .jar file linked in the Requirements section above
• Once you have the .jar file selected, click on the "Find Class" button and select Driver Class io.spaceandtime.jdbc.JdbcDriver. If the Find Class button doesn't work, try saving the connection first, then returning and hitting Find Class again.
• Hit "Ok" to save the new library and settings

Step 2: Configure the driver properties

Setting up the driver requires two driver properties:

• Class Name: io.spaceandtime.jdbc.JdbcDriver
• URL Template: jdbc:sxt:thin://{host}
  The {host} will be replaced by the host field when setting up new connections.

The driver setup screen should look someething like this:

Step 3: Create a new connection

Once the driver is setup, you can create a new connection. Again, this will vary depending on the tool used, however there are a few pieces of information you will need.

There are two ways you can use the JDBC driver to authenticate: username/password thru the Gateway (Secrets Proxy) or connecting directly to the Decentralized Network using public/private keypair. For either approach, the above connection setup information remains the same.

Connect via Gateway (Secrets Proxy)

This is the most straight forward, as it leverages the username and password from the Space and Time Studio. If you created your Studio account with a wallet,

Connect Directly to Decentralized Network

Always Required:

• Host - This will be the API base URL. Note: do NOT include http:// or https:// in this field.
• Username - This will be the userId you registered with Space and Time. For easy registration, use the Space and Time CLI.

Authenticate with Gateway (Secrets Proxy):

If you created your account using the Space and Time Studio, you can use

Authenticate with Decentralized Network:

When authenticating with the decentralized network, you will need to provide your public / private keypair. When entering this information into the JDBC connection screen:

📘

The user's private key NEVER leaves the JDBC driver/user's computer. Rather, the private key is used to generate a cryptographic signature that allows Space and Time servers to validate key ownership without transmitting the key itself.

• Password - Enter your account's private key, generated when you created a new user or added to a Gateway user. Putting the private key in the
  Optionally, you can choose to add the private key to a new User Property called privateKey, the same way as your public key, however is not recommended - most JDBC tools will store User Properties as plain text and allow copy access to the value, making it less secure
• publicKey - This will be the public key corresponding to the above private key. Please note publicKey needs to be configured manually, as this field does not exist by default.

Step 4: Test your connection

Before continuing, test your connection to ensure all properties were entered correctly.

DBeaver instructions:

• Select the "Test Connection" in the lower lefthand corner of the configuration screen

About Accessing and Permissioning Resources (Biscuits)

Space and Time use biscuits to manage the secure authorization between users and tables on a decentralized network. Establishing this authorization requires one additional step for the JDBC driver: add a biscuit to the JDBC driver properties. For a guide on how to do so, see this page.