[Hyperledger Fabric v1.1] 6. Architecture Reference: CouchDB as the State Database

해당 글은 Hyperledger Fabric 페이지의 게시글을 번역 및 정리한 자료입니다.

원본 사이트 : http://hyperledger-fabric.readthedocs.io/en/release-1.1/couchdb_as_state_database.html

 상태 데이터베이스 옵션

상태 데이터베이스 옵션에는 LevelDB 및 CouchDB가 포함됩니다. LevelDB는 피어 프로세스에 포함 된 기본 키 - 값 상태 데이터베이스입니다. CouchDB는 선택적 외부 상태 데이터베이스입니다. CouchDB는 LevelDB 키 - 값 저장소와 마찬가지로 체인 코드로 모델링 된 모든 이진 데이터를 저장할 수 있습니다 (CouchDB 첨부 기능은 JSON이 아닌 바이너리 데이터에 내부적으로 사용됩니다). 그러나 JSON 문서 저장소 인 CouchDB는 체인 코드 값 (예 : 자산)을 JSON 데이터로 모델링 할 때 체인 코드 데이터에 대한 추가 쿼리를 추가적으로 지원합니다.

LevelDB 및 CouchDB는 키 가져 오기 및 설정 (자산)과 키 기반 쿼리와 같은 핵심 체인 코드 작업을 지원합니다. 키는 범위별로 쿼리 할 수 ​​있으며 복합 키는 여러 매개 변수에 대해 등가 쿼리를 사용할 수 있도록 모델링 할 수 있습니다. 예를 들어 소유자인 asset_id의 복합 키를 사용하여 특정 엔터티가 소유 한 모든 자산을 쿼리 할 수 ​​있습니다. 이러한 키 기반 쿼리는 원장에 대한 읽기 전용 쿼리 및 원장을 업데이트하는 트랜잭션에 사용할 수 있습니다.

자산을 JSON으로 모델링하고 CouchDB를 사용하는 경우 chaincode 내의 CouchDB JSON 쿼리 언어를 사용하여 체인 코드 데이터 값에 대해 복잡한 리치 쿼리를 수행 할 수도 있습니다. 이러한 유형의 쿼리는 원장의 내용을 이해하는 데 탁월합니다. 이러한 유형의 쿼리에 대한 제안 응답은 일반적으로 클라이언트 응용 프로그램에 유용하지만 일반적으로 주문 서비스에 대한 트랜잭션으로 제출되지는 않습니다. 실제로 체인 코드 실행과 풍부한 쿼리에 대한 커밋 시간 사이에 결과 집합이 안정적이라는 보장이 없으므로 응용 프로그램이 결과 집합이 체인 코드 실행 시간과 안정성 사이에서 안정적임을 보장 할 수없는 경우 리치 쿼리가 업데이트 트랜잭션에 사용하기에 적합하지 않습니다. 커밋 시간, 또는 후속 트랜잭션의 잠재적 변경을 처리 할 수 ​​있습니다. 

예를 들어, CouchDB는 피어와 함께 별도의 데이터베이스 프로세스로 실행되므로 설정, 관리 및 작업과 관련하여 추가 고려 사항이 있습니다. 기본 임베디드 LevelDB로 시작하는 것을 고려해 볼 수 있으며 추가로 복잡한 리치 쿼리가 필요한 경우 CouchDB로 이동하십시오. 체인 코드 자산 데이터를 JSON으로 모델링하는 것이 좋습니다. 그러면 나중에 필요할 경우 복잡한 리치 쿼리를 수행 할 수 있습니다.

JSON 문서는 최상위 레벨에서 다음 필드 이름을 사용할 수 없습니다. 내부 용으로 예약되어 있습니다.

• _deleted
• _id
• _rev
• ~version

Chaincode에서 CouchDB 사용

대부분의 체인 코드 shim API는 LevelDB 또는 CouchDB 상태 데이터베이스와 함께 사용할 수 있습니다. GetState, PutState, GetStateByRange, GetStateByPartialCompositeKey입니다. 또한 CouchDB를 상태 데이터베이스로 활용하고 체인 코드에서 JSON으로 자산을 모델링 할 때 GetQueryResult API를 사용하고 CouchDB 쿼리 문자열을 전달하여 상태 데이터베이스의 JSON에 대해 풍부한 쿼리를 수행 할 수 있습니다. 쿼리 문자열은 CouchDB JSON 쿼리 구문을 따릅니다.

marbles02 패브릭 샘플은 chaincode에서 CouchDB 쿼리를 사용하는 방법을 보여줍니다. 그것은 소유자 ID를 chaincode에 전달하여 매개 변수화 된 쿼리를 보여주는 queryMarblesByOwner () 함수를 포함합니다. 그런 다음 JSON 쿼리 구문을 사용하여 "대리석"의 docType 및 소유자 ID와 일치하는 JSON 문서의 상태 데이터를 쿼리합니다.

{"selector":{"docType":"marble","owner":<OWNER_ID>}}

JSON 쿼리를 효율적으로 만들기 위해서는 CouchDB의 인덱스가 필요하며 정렬 된 모든 JSON 쿼리에 필요합니다. 인덱스는 / META-INF / statedb / couchdb / indexes 디렉토리의 chaincode와 함께 패키지화 할 수 있습니다. 각 색인은 확장자가 * .json 인 자체 텍스트 파일에 정의되어야하며 색인 정의는 CouchDB 색인 JSON 구문에 따라 JSON으로 형식이 지정됩니다. 예를 들어 위의 대리석 쿼리를 지원하기 위해 docType 및 owner 필드에 대한 샘플 인덱스가 제공됩니다.

{"index":{"fields":["docType","owner"]},"ddoc":"indexOwnerDoc", "name":"indexOwner","type":"json"}

체인 코드의 META-INF / statedb / couchdb / indexes 디렉토리에있는 인덱스는 배포용 체인 코드로 패키지됩니다. 체인 코드가 피어에 설치되고 피어의 채널 중 하나에서 인스턴스화되면 피어의 채널 및 체인 코드 특정 상태 데이터베이스 (CouchDB를 사용하도록 구성된 경우)에 인덱스가 자동으로 배포됩니다. 먼저 체인 코드를 설치 한 다음 채널에 체인 코드를 인스턴스화하면 체인 코드 인스턴스화시 색인이 배치됩니다. 체인 코드가 이미 채널에서 인스턴스화 된 경우 나중에 체인 코드를 피어에 설치하면 체인 코드 설치시 색인이 배치됩니다.

배포시 인덱스는 체인 코드 쿼리에 의해 자동으로 활용됩니다. CouchDB는 쿼리에서 사용되는 필드에 따라 사용할 인덱스를 자동으로 결정할 수 있습니다. 또는 selector 쿼리에서 인덱스는 use_index 키워드를 사용하여 지정할 수 있습니다.

동일한 인덱스가 설치되는 체인 코드의 후속 버전에도 존재할 수 있습니다. 색인을 변경하려면 동일한 색인 이름을 사용하지만 색인 정의를 변경하십시오. 설치 / 인스턴스 생성시, 인덱스 정의는 피어의 상태 데이터베이스에 다시 배포됩니다.

많은 양의 데이터가 있고 나중에 체인 코드를 설치하면 설치시 인덱스 생성에 약간의 시간이 걸릴 수 있습니다. 마찬가지로 대량의 데이터가 이미 있고 체인 코드의 후속 버전을 인스턴스화하는 경우 인덱스 생성에 약간의 시간이 걸릴 수 있습니다. 인덱스가 초기화되는 동안 체인 코드 쿼리가 시간 초과 될 수 있으므로이 때 상태 데이터베이스를 쿼리하는 체인 코드 함수를 호출하지 마십시오. 트랜잭션 처리 중에 블록이 원장에게 커밋됨에 따라 인덱스가 자동으로 새로 고쳐집니다.

CouchDB 설정

stateDatabase 구성 옵션을 goleveldb에서 CouchDB로 변경하여 CouchDB를 상태 데이터베이스로 사용할 수 있습니다. 또한 couchDBAddress는 피어가 사용할 CouchDB를 가리 키도록 구성해야합니다. CouchDB가 사용자 이름과 암호로 구성되어 있으면 사용자 이름과 암호 등록 정보에 관리자 사용자 이름과 암호가 입력되어야합니다. 추가 옵션은 couchDBConfig 섹션에 제공되며 문서화되어 있습니다. core.yaml에 대한 변경 사항은 피어를 재시작 한 후 즉시 적용됩니다.

docker 환경 변수를 전달하여 core.yaml 값을 무시할 수도 있습니다 (예 : CORE_LEDGER_STATE_STATEDATABASE 및 CORE_LEDGER_STATE_COUCHDBCONFIG_COUCHDBADDRESS)

다음은 core.yaml의 stateDatabase 섹션입니다.

state:
  # stateDatabase - options are "goleveldb", "CouchDB"
  # goleveldb - default state database stored in goleveldb.
  # CouchDB - store state database in CouchDB
  stateDatabase: goleveldb
  couchDBConfig:
     # It is recommended to run CouchDB on the same server as the peer, and
     # not map the CouchDB container port to a server port in docker-compose.
     # Otherwise proper security must be provided on the connection between
     # CouchDB client (on the peer) and server.
     couchDBAddress: couchdb:5984
     # This username must have read and write authority on CouchDB
     username:
     # The password is recommended to pass as an environment variable
     # during start up (e.g. LEDGER_COUCHDBCONFIG_PASSWORD).
     # If it is stored here, the file must be access control protected
     # to prevent unintended users from discovering the password.
     password:
     # Number of retries for CouchDB errors
     maxRetries: 3
     # Number of retries for CouchDB errors during peer startup
     maxRetriesOnStartup: 10
     # CouchDB request timeout (unit: duration, e.g. 20s)
     requestTimeout: 35s
     # Limit on the number of records to return per query
     queryLimit: 10000

Docker에서 호스팅되는 CouchDB Docker로 압축 된 스크립팅 환경 압축 된 스크립팅 환경 변수는 COUCHDB_USER 및 COUCHDB_PASSWORD 환경 변수에 전달됩니다.

Fabric과 함께 제공된 도커 이미지 외부의 CouchDB 설치의 경우 local.ini 파일을 관리자 아이디와 비밀번호로 설정해야합니다.

Docker 작성 스크립트는 컨테이너 작성시 사용자 이름과 암호 만 설정합니다. 컨테이너를 만든 후에 사용자 이름이나 암호를 변경하면 local.ini 파일을 편집해야합니다.