How to Access Permissioned Tables via JDBC

📘

Blockchain tables are all public_read tables, meaning no biscuits are required to SELECT from them. If you are only querying onchain data, you can skip the biscuit setup process entirely.

Space and Time use biscuits to manage the secure authorization between users and tables on a decentralized network. Because most JDBC applications don't have biscuits built into their default workflow, establishing this authorization requires one additional step for the JDBC driver: add a biscuit to the JDBC driver properties.

Adding Biscuits to a JDBC Application: DBeaver

All JDBC applications will have slightly variations in how the application allows access to each element, however the steps themselves should be very similar. For this example, we are working with the open-source SQL editor DBeaver, as it is common, free, and fairly standard.

1. Open or edit the connection object, in DBeaver found by right-clicking the connection object and select Edit Connection from the context menu, which will open a new window:

   

2. In the "Connection Settings" window, click the driver properties tab and add a new property - in DBeaver this is done by clicking the small green plus icon at the bottom (not shown here), which opens a small modal input box. For the Property Name, enter biscuit_SCHEMA.TABLE_NAME - that is, "biscuit_" in all lower case, followed by your table's "SCHEMA.TABLE_NAME" in all upper case, with no spaces in-between:

   

   🚧

   Be careful when entering the properties name - it must be biscuit_SCHEMA.TABLE_NAME with lower case biscuit_ and upper case SCHEMA.TABLE_NAME (using your table's schema and table_name). Also make sure there are not white-space characters such as space, tab, newline, etc. anywhere in the string (front, back, or middle).

   Click OK when done, which will add the property name to your list of properties, with a blank value.

3. Add your biscuit key as the new property's Value. In DBeaver, clicking into the Value field should make it editable. Again, make sure there is no whitespace around the biscuit, then simply click out of the field when done.

   

4. Click on "OK" to close the "Connection Settings" window, and Save when prompted. If that connection was active when you started, it will also prompt you to reconnect, which is required before the new settings will take effect.

👍

Congratulations! You should now be able to access your table with permissions granted by the biscuit.

More tables!

One biscuit is required per permissioned table. For example, if you wanted access to 3 private tables from the JDBC connection, "TableA", "TableB", and "TableC", you would need 3 new JDBC properties.

Roadmap (JDBC)

Work is continually underway to make this process more dynamic for users, allowing the JDBC driver to be smarter when selecting a biscuit while enabling the biscuit scope to span beyond a single table. Check back periodically as we progress!