Skip to content

Home

Jump to bottom
Hosur Narahari edited this page Aug 31, 2018 · 3 revisions

1. Introduction

Fabric jdbc driver is a jdbc driver to interact with Hyperledger Fabric blockchain network. Querying on blocks, transactions, transaction actions, read write sets; creating and querying assets; creating and dropping asset schema are some of the operations supported by this driver. Sample JDBC connection is created as follows.

java.sql.Connection conn = java.sql.DriverManager.getConnection(<jdbcURL>, <username>, “”);

jdbcURL is of the form jdbc:fabric:// <config directory path>: <fabric channel name>

Details of each operation is explained in detail in further sections of this document.

2. Installation

Config directory structure passed in jdbc url looks as below.

< config directory >

├── config.properties

├── db.properties

├── hyperledger.properties

├── artifacts

│   ├── channel

│    └── crypto-config

│      ├── ordererOrganizations

│      │   └── < orderer domain >

│      │       ├── ca

│      │       ├── msp

│      │       │   ├── admincerts

│      │       │   ├── cacerts

│      │       │   └── tlscacerts

│      │       ├── orderers

│      │       │   └── orderer.< orderer domain >

│      │       │       ├── msp

│      │       │       │   ├── admincerts

│      │       │       │   ├── cacerts

│      │       │       │   ├── keystore

│      │       │       │   ├── signcerts

│      │       │       │   └── tlscacerts

│      │       │       └── tls

│      │       ├── tlsca

│      │       └── users

│      │           └── Admin@< orderer domain >

│      │               ├── msp

│      │               │   ├── admincerts

│      │               │   ├── cacerts

│      │               │   ├── keystore

│      │               │   ├── signcerts

│      │               │   └── tlscacerts

│      │               └── tls

│      └── peerOrganizations

│          ├── < org1 domain >

│          │   ├── ca

│          │   ├── msp

│          │   │   ├── admincerts

│          │   │   ├── cacerts

│          │   │   └── tlscacerts

│          │   ├── peers

│          │   │   ├── peer0.< org1 domain >

│          │   │   │   ├── msp

│          │   │   │   │   ├── admincerts

│          │   │   │   │   ├── cacerts

│          │   │   │   │   ├── keystore

│          │   │   │   │   ├── signcerts

│          │   │   │   │   └── tlscacerts

│          │   │   │   └── tls

│          │   │   └── ..

│          │   ├── tlsca

│          │   └── users

│          │       ├── Admin@< org1 domain >

│          │       ├── msp

│          │        │   ├── admincerts

│          │        │   ├── cacerts

│          │        │   ├── keystore

│          │        │   ├── signcerts

│          │        │   └── tlscacerts

│          │        └── tls

│          └── .. 

└── src

    ├── < smart contract 1 >

    └── ..

config.properties file contains details of information of peers of an organization and other configuration properties. db.properties file contains connection details to MySQL database. hyperledger.properties file contains admin user details.

Directories under crypto-config directory mentioned in the above tree structure are automatically generated by Hyperledger fabric cryptogen tool and contains various certificates and keystore files.

3. Select Query

Whole block structure of Hyperledger Fabric ledger can be queried using select query. Fabric block structure is divided into 4 tables, viz. block, transaction, transaction_action and read_write_set. The structure of these tables are as shown in tables 3.1 to 3.4.

Column Name Column Description
previous_hash Hash of previous block
block_data_hash Hash of all the data in the hash
trans_actions_metadata Validation codes of all transactions in the block
transaction_count Number of transactions in the block
block_no Height of the block in the ledger
channel_id Unique id of channel to which the block belongs

Table 3.1(block)

Column Name Column Description
block_no Height of the block in the ledger
transaction_id Unique id of the transaction
header_type
message_protocol_version
timestamp Local time when the message was created by the sender
epoch The epoch in which this transaction header is generated.
channel_id Unique id of channel to which the transaction belongs
creator_msp Identifier of associated membership service provider
creator_signature Signature of the creator
nonce Arbitrary number that may be used once. Can be used to detect replay attacks

Table 3.2(transaction)

Column Name Column Description
block_no Height of the block in the ledger
transaction_id Unique id of the transaction
id_generation_alg User specified ID generation algorithm
chaincode_type Chaincode type (golang, node etc.)
chaincode_name Name of the Chaincode
chaincode_version Version of the Chaincode for invoke transaction
chaincode_path Path of the Chaincode used in deploy transaction
chaincode_args Chaincode function and its arguments
time_out Time out for response from peer
rw_datamodel Data Model of read write set
response_message Message associated with the response code
response_status Status code of response similar to HTTP codes
response_payload A payload that can be used to include metadata with the response
endorsements Endorsements of proposal, which is signature of an endorser over a proposal response

Table 3.3(transaction_action)

Column Name Column Description
block_no Height of the block in the ledger
transaction_id Unique id of the transaction
namespace Represents Chaincode
read_key Key used in read operation
read_block_no Height of the block that committed the key
read_tx_num Height of the transaction within block(starting with 1) that committed the key
range_query_start_key Start key of a range query
range_query_end_key End key of a range query
range_query_itr_exausted
range_query_reads_info
write_key Key used in write operation
is_delete True if it is a delete operation
write_value Value that is being written against write key

Table 3.4(read_write_set)

Select query consists of standard SQL syntax with SELECT, FROM, WHERE, GROUP BY, HAVING, ORDER BY and LIMIT clauses. There are 3 types of filter conditions in where clause, viz. range conditions marked in bold and italics in tables 3.1 to 3.4 (where any operator like <, > etc. can be used), direct query conditions marked in bold in tables 3.1 to 3.4 (where only = operator can be used) and other filter conditions which can’t be directly queried by fabric APIs. Select query without where clause can’t be queried as it’s requires fetching huge amount of data. Also some other where conditions which requires fetching huge amount of data can’t be queried.

Examples:

  1. SELECT * FROM block where block_no <= 10
  2. Select block_no, count(transaction_id) as cnt from transaction where block_no <= 100 group by block_no having count(transaction_id) > 1 order by block_no limit 10
  3. Select write_key, write_value from read_write_set where transaction_id = ’4fe9a863f976d3b3fb362050d6b09d01d1a91af5d9de6ac6ec461c752c8849e3’ and write_key=’PROD1004’

4. Create Chaincode

Hyperledger fabric Chaincode, which represents a business logic can be created by using below SQL statement.

CREATE CHAINCODE <CHAINCODE NAME> AS <CHAINCODE PATH> WITH VERSION <VERSION NUMBER> [WITH ARGS <ARGUMENTS TO INIT METHOD OF CHAINCODE>][INSTALL ONLY | INSTANTIATE ONLY]

Chaincode path in above statement is relative path to <config folder>/src as all chaincodes should be stored in this location.

Examples:

  1. Create Chaincode assetchain as ‘samples/example_cc’ with version ‘1.0’ with args ‘a’, 200, ‘b’, 500

  2. CREATE CHAINCODE assettransfer AS 'assettransfer' WITH VERSION '1.1' INSTALL ONLY

5. Insert Asset

New asset records can be inserted into Hyperledger fabric’s world state using below SQL statement.

INSERT INTO <CHAINCODE NAME> VALUES (<VALUE 1>, <VALUE 2>, ..  )

Order of the values passed is same as what invoke method of Chaincode expects.

Examples:

  1. Insert into assetchain values (‘transfer’, ‘a’, ‘b’, 100)

6. Create Asset

Asset’s schema can be created by using below SQL statement.

CREATE ASSET <ASSET NAME> (
  <Column1> <Column Type1>,
  <Column2> <Column Type2>,
  …
) 
WITH STORAGE TYPE <JSON/CSV>
[FIELDS DELIMITED BY <FIELD DELIMITER>]
[RECORDS DELIMITED BY <RECORD DELIMITER>]

To create asset schema, MySQL should be configured by providing connection details in db.properties file under config path. Also asset_schema table should be created in MySQL using script given with fabric-jdbc-driver kit.

If storage type is JSON, then there is no need to give column definitions, field delimiter and record delimiter since JSON is semi-structured data with field information as part of the data.

Examples:

  1. Create asset PRODUCT with storage type JSON
  2. Create asset SERVICE ( Id int, Name string, Price double ) With storage type CSV Fields delimited by ‘,’ Records delimited by ‘\n’

7. Call Asset

Asset records can be queried from Hyperledger fabric network using any of the below 2 SQL statement.

CALL <CHAINCODE NAME> (<ARG1>, <ARG2>, ..) [AS ASSET <ASSET NAME>]

Order of arguments passed is same as what invoke method of Chaincode expects. With the first approach, result set is returned; with the data parsed according to asset definition. With the second approach, result set is returned; with a single column named data, which contains raw data returned by Chaincode function. Examples:

  1. Call assetchain (‘queryBalance’, ‘a’) AS ENTITY
  2. Call assetchain (‘queryBalance’, ‘b’)

8. Delete Asset

Asset records can be deleted from Hyperledger fabric network using below SQL statement.

DELETE <CHAINCODE NAME> (<ARG1>, <ARG2>, ..)

Order of arguments passed is same as what invoke method of Chaincode expects.

Examples:

  1. Delete assetchain (‘deleteEntity’, ‘b’)

9. Drop Asset

Asset’s schema created before from section 6 can be dropped using below SQL statement.

DROP ASSET <ASSET NAME>

Examples:

  1. DROP ASSET PRODUCT

10. Upgrade Chaincode

If there is any change in business logic of Hyperledger fabric’s Chaincode, then it can be upgraded using below SQL statement.

UPGRADE CHAINCODE <CHAINCODE NAME> AS <CHAINCODE PATH> WITH VERSION <VERSION NUMBER> [WITH ARGS <ARGUMENTS TO INIT METHOD OF CHAINCODE>] [INSTALL ONLY | UPGRADE ONLY]

Chaincode path in above statement is relative path to /src as all chaincodes should be stored in this location.

Examples:

  1. Upgrade Chaincode assetchain as ‘samples/example_cc_new’ with version ‘2.0’ with args ‘a’, 40

  2. UPGRADE CHAINCODE assettransfer as 'assettransfer' WITH VERSION '2.0' UPGRADE ONLY

11. Create User

User can be registered with Certificate Authority using below SQL statement.

CREATE USER <USER NAME> IDENTIFIED BY <SECRET> AFFILIATED TO <DEPARTMENT AFFILIATION>

This command can only be executed by user having admin privileges.

Examples:

  1. Create user testuser identified by 'testpasswd' affiliated to org1.department1
Clone this wiki locally