mirror of
https://github.com/corda/corda.git
synced 2024-12-24 15:16:45 +00:00
440 lines
25 KiB
ReStructuredText
440 lines
25 KiB
ReStructuredText
Database tables
|
|
===============
|
|
|
|
A Corda node database contains tables corresponding to the various services that the node provides.
|
|
It also contains custom tables defined by the CorDapps that are installed on the node.
|
|
Currently all these tables share the same database schema, but in a future release they will be isolated from each other.
|
|
|
|
.. note:: Unless specified otherwise the node tables are for internal use and can change between versions.
|
|
|
|
Some tables, especially the ones where the ``Ledger`` is maintained are append-only and the data will never change.
|
|
|
|
.. warning:: Manually adding, removing or updating any data should only be done with great care. Corda is a distributed ledger and modifying
|
|
data could lead to unexpected behaviour and inconsistent views of the ledger.
|
|
|
|
Network map
|
|
-----------
|
|
|
|
|
|
Node Infos
|
|
^^^^^^^^^^
|
|
|
|
These are tables that store the NodeInfo of other network participants.
|
|
They are just a local cache that is kept in sync with the network map server.
|
|
By calling ``rpc.clearNetworkMapCache()`` all these tables will be cleared and recreated from the network map server.
|
|
|
|
Read more here: :doc:`network-map`
|
|
|
|
.. image:: resources/database/node_info_tables.png
|
|
:scale: 50%
|
|
:align: center
|
|
|
|
============================== ==========================================================================================
|
|
NODE_INFOS Stores ``NodeInfo`` objects. The principal table.
|
|
============================== ==========================================================================================
|
|
NODE_INFO_ID Primary key
|
|
NODE_INFO_HASH Hash of the binary nodeInfo file
|
|
PLATFORM_VERSION Declared version of the participant node.
|
|
SERIAL Version of the NodeInfo
|
|
============================== ==========================================================================================
|
|
|
|
|
|
============================== ==========================================================================================
|
|
NODE_INFO_HOSTS Many-to-one addresses to node
|
|
============================== ==========================================================================================
|
|
HOSTS_ID Primary key
|
|
HOST_NAME Host name of the participant's node
|
|
PORT Port
|
|
NODE_INFO_ID FK to NODE_INFOS
|
|
============================== ==========================================================================================
|
|
|
|
|
|
============================== ==========================================================================================
|
|
NODE_INFO_PARTY_CERT Legal identity for a network participant
|
|
============================== ==========================================================================================
|
|
PARTY_NAME The X500 name
|
|
OWNING_KEY_HASH The public key
|
|
ISMAIN If this is a main identity
|
|
PARTY_CERT_BINARY The certificate chain
|
|
============================== ==========================================================================================
|
|
|
|
|
|
============================== ==========================================================================================
|
|
NODE_LINK_NODEINFO_PARTY Many-to-Many link between the hosts and the legal identities
|
|
============================== ==========================================================================================
|
|
NODE_INFO_ID FK to Node_info
|
|
PARTY_NAME FK to NODE_INFO_PARTY_CERT
|
|
============================== ==========================================================================================
|
|
|
|
|
|
|
|
Node identities
|
|
^^^^^^^^^^^^^^^
|
|
|
|
The following four tables are used by the ``IdentityService`` and are created from the NodeInfos.
|
|
They are append only tables used for persistent caching.
|
|
They will also be cleared on ``rpc.clearNetworkMapCache()``.
|
|
Read more in :doc:`api-identity` and :doc:`node-services`
|
|
|
|
|
|
============================== ==========================================================================================
|
|
NODE_IDENTITIES Maps a public key hash to an identity.
|
|
============================== ==========================================================================================
|
|
PK_HASH The public key hash.
|
|
IDENTITY_VALUE The certificate chain.
|
|
============================== ==========================================================================================
|
|
|
|
|
|
============================== ==========================================================================================
|
|
NODE_NAMED_IDENTITIES Maps the X500 name of a participant to a public key hash.
|
|
============================== ==========================================================================================
|
|
NAME The x500 name.
|
|
PK_HASH The public key hash.
|
|
============================== ==========================================================================================
|
|
|
|
|
|
============================== ==========================================================================================
|
|
NODE_IDENTITIES_NO_CERT Maps a public key hash to the X500 name of a participant.
|
|
============================== ==========================================================================================
|
|
PK_HASH The public key hash.
|
|
NAME The x500 name.
|
|
============================== ==========================================================================================
|
|
|
|
|
|
============================== ==========================================================================================
|
|
NODE_HASH_TO_KEY Maps a public key hash to a public key.
|
|
============================== ==========================================================================================
|
|
PK_HASH The public key hash.
|
|
PUBLIC_KEY The public key.
|
|
============================== ==========================================================================================
|
|
|
|
|
|
Network parameters
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
Read more here: :doc:`network-map`.
|
|
Each downloaded network parameters file will create an entry in this table.
|
|
The historical network parameters are used when validating transactions, which makes this table logically part of the ``Ledger``.
|
|
It is an append only table and the size will be fairly small.
|
|
|
|
|
|
============================== ==========================================================================================
|
|
NODE_NETWORK_PARAMETERS Stores the downloaded network parameters.
|
|
============================== ==========================================================================================
|
|
HASH The hash of the downloaded file. Used as a primary key.
|
|
EPOCH The version of the parameters
|
|
PARAMETERS_BYTES The serialized bytes
|
|
SIGNATURE_BYTES The signature
|
|
CERT First signer certificate in the certificate chain.
|
|
PARENT_CERT_PATH Parent certificate path of signer.
|
|
============================== ==========================================================================================
|
|
|
|
|
|
Ledger
|
|
------
|
|
|
|
The ledger data is formed of transactions and attachments.
|
|
In future versions this data will be encrypted using SGX.
|
|
Read more in :doc:`key-concepts-ledger`
|
|
|
|
Attachments
|
|
^^^^^^^^^^^
|
|
|
|
Read more in :doc:`tutorial-attachments` and :doc:`node-services`
|
|
|
|
.. image:: resources/database/attachments_tables.png
|
|
:scale: 50%
|
|
:align: center
|
|
|
|
============================== ==========================================================================================
|
|
NODE_ATTACHMENTS Stores attachments
|
|
============================== ==========================================================================================
|
|
ATT_ID The hash of the content of the file.
|
|
CONTENT The binary content
|
|
FILENAME Not used at the moment.
|
|
INSERTION_DATE Date.
|
|
UPLOADER One of: ``p2p``, ``app``, ``rpc``, ``unknown``. Currently used for for determining if this attachment is safe to execute during transaction verification.
|
|
VERSION The version of the JAR file.
|
|
============================== ==========================================================================================
|
|
|
|
|
|
============================== ==========================================================================================
|
|
NODE_ATTACHMENTS_CONTRACTS Many-to-one contracts per attachment. Empty for non-contract attachments.
|
|
============================== ==========================================================================================
|
|
ATT_ID Foreign key
|
|
CONTRACT_CLASS_NAME The fully qualified contract class name. E.g.: ``net.corda.finance.contracts.asset.Cash``
|
|
============================== ==========================================================================================
|
|
|
|
|
|
============================== ==========================================================================================
|
|
NODE_ATTACHMENTS_SIGNERS Many-to-one JAR signers of an attachment. Empty if not signed.
|
|
============================== ==========================================================================================
|
|
ATT_ID Foreign key
|
|
SIGNER Hex encoded public key of the JAR signer.
|
|
============================== ==========================================================================================
|
|
|
|
|
|
|
|
Transactions
|
|
^^^^^^^^^^^^
|
|
|
|
These are all the transactions that the node has created or has ever downloaded as part of transaction resolution. This table can grow very large.
|
|
It is an append-only table, and the data will never change.
|
|
Read more in :doc:`node-services` - ``DBTransactionStorage``
|
|
This is the key ledger table used as a source of truth. In the future the content will be encrypted to preserve confidentiality.
|
|
|
|
============================== ==========================================================================================
|
|
NODE_TRANSACTIONS Corda transactions in a binary format
|
|
============================== ==========================================================================================
|
|
TX_ID The hash of the transaction. Primary key.
|
|
TRANSACTION_VALUE The binary representation of the transaction.
|
|
STATE_MACHINE_RUN_ID The flow id associated with this transaction.
|
|
STATUS ``VERIFIED`` or ``UNVERIFIED``
|
|
============================== ==========================================================================================
|
|
|
|
|
|
|
|
|
Contract upgrades
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
Read more in :doc:`contract-upgrade`
|
|
|
|
============================== ==========================================================================================
|
|
NODE_CONTRACT_UPGRADES Represents an authorisation to upgrade a state_ref to a contract.
|
|
============================== ==========================================================================================
|
|
STATE_REF The authorised state.
|
|
CONTRACT_CLASS_NAME The contract.
|
|
============================== ==========================================================================================
|
|
|
|
This table should be empty when no states are authorised for upgrade or after authorised states have been upgraded.
|
|
|
|
|
|
|
|
Scheduling
|
|
^^^^^^^^^^
|
|
|
|
Read more in :doc:`event-scheduling`
|
|
|
|
============================== ==========================================================================================
|
|
NODE_SCHEDULED_STATES Contains scheduled states
|
|
============================== ==========================================================================================
|
|
OUTPUT_INDEX Reference to a state - index in transaction
|
|
TRANSACTION_ID Reference to a state - transaction id
|
|
SCHEDULED_AT Timestamp when this state will execute.
|
|
============================== ==========================================================================================
|
|
|
|
|
|
This table should be empty when no events are scheduled.
|
|
|
|
|
|
Storage of private keys
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
============================== ==========================================================================================
|
|
NODE_OUR_KEY_PAIRS Stores the anonymous identities
|
|
============================== ==========================================================================================
|
|
PUBLIC_KEY_HASH Primary key
|
|
PRIVATE_KEY Binary private key
|
|
PUBLIC_KEY Binary public key
|
|
============================== ==========================================================================================
|
|
|
|
============================== ==========================================================================================
|
|
PK_HASH_TO_EXT_ID_MAP Maps public keys to external ids. Mainly used by CorDapps that need to simulate accounts.
|
|
============================== ==========================================================================================
|
|
EXTERNAL_ID External id
|
|
PUBLIC_KEY_HASH Public key hash
|
|
============================== ==========================================================================================
|
|
|
|
These tables should be append only.
|
|
|
|
|
|
Node state machine
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
Read more in :doc:`node-services`
|
|
|
|
============================== ==========================================================================================
|
|
NODE_CHECKPOINTS Stores the flow checkpoints.
|
|
============================== ==========================================================================================
|
|
CHECKPOINT_ID Primary key
|
|
CHECKPOINT_VALUE Serialized application stack.
|
|
============================== ==========================================================================================
|
|
|
|
This table will see the most intense read-write activity. Depending on the installed flows and the traffic on the node the I/O operations on this
|
|
table will be the main bottleneck of the node performance.
|
|
There will be an entry for every running flow.
|
|
Draining the node means waiting for this table to become emtpy. Read more in: :doc:`node-operations-upgrade-cordapps`.
|
|
|
|
|
|
============================== ==========================================================================================
|
|
NODE_MESSAGE_IDS Used for de-duplication of messages received by peers.
|
|
============================== ==========================================================================================
|
|
MESSAGE_ID Message id
|
|
INSERTION_TIME Insertion time
|
|
SENDER P2p sender
|
|
SEQUENCE_NUMBER Sequence number
|
|
============================== ==========================================================================================
|
|
|
|
|
|
Key value store
|
|
^^^^^^^^^^^^^^^
|
|
|
|
============================== ==========================================================================================
|
|
NODE_PROPERTIES General key value store. Currently only used for the flow draining mode.
|
|
============================== ==========================================================================================
|
|
PROPERTY_KEY The key
|
|
PROPERTY_VALUE The value
|
|
============================== ==========================================================================================
|
|
|
|
|
|
Vault tables
|
|
------------
|
|
|
|
Read more about the vault here :doc:`key-concepts-vault`.
|
|
|
|
Note that the vault tables are guaranteed to remain backwards compatible and are safe to be used directly by third party applications.
|
|
|
|
|
|
============================== ==========================================================================================
|
|
VAULT_STATES Principal vault table.
|
|
============================== ==========================================================================================
|
|
OUTPUT_INDEX Reference to a state - index in transaction
|
|
TRANSACTION_ID Reference to a state - transaction id
|
|
CONSUMED_TIMESTAMP When the state was consumed.
|
|
CONTRACT_STATE_CLASS_NAME Contract class
|
|
LOCK_ID The soft lock id
|
|
LOCK_TIMESTAMP The soft lock timestamp
|
|
NOTARY_NAME The notary
|
|
RECORDED_TIMESTAMP Recorded timestamp
|
|
STATE_STATUS ``CONSUMED`` or ``UNCONSUMED``
|
|
RELEVANCY_STATUS ``RELEVANT`` or ``NOT_RELEVANT``
|
|
CONSTRAINT_TYPE The contract constraint.
|
|
CONSTRAINT_DATA The hash or the composite key depending on the ``CONSTRAINT_TYPE``
|
|
============================== ==========================================================================================
|
|
|
|
The ``VAULT_STATES`` table contains an entry for every relevant state.
|
|
This table records the status of states and allows CorDapps to soft lock states it intends to consume.
|
|
Depending on the installed CorDapps this table can grow. For example when fungible states are used.
|
|
|
|
In case this table grows too large, the DBA can choose to archive old consumed states.
|
|
The actual content of the states can be retrieved from the ``NODE_TRANSACTIONS`` table by deserializing the binary representation.
|
|
|
|
============================== ==========================================================================================
|
|
VAULT_TRANSACTION_NOTES Allows additional notes per transaction
|
|
============================== ==========================================================================================
|
|
SEQ_NO Primary key
|
|
TRANSACTION_ID The transaction
|
|
NOTE The note
|
|
============================== ==========================================================================================
|
|
|
|
============================== ==========================================================================================
|
|
STATE_PARTY Maps participants to states
|
|
============================== ==========================================================================================
|
|
OUTPUT_INDEX Reference to a state - index in transaction
|
|
TRANSACTION_ID Reference to a state - transaction id
|
|
PUBLIC_KEY_HASH The pk of the participant
|
|
X500_NAME The name of the participant or null if unknown.
|
|
============================== ==========================================================================================
|
|
|
|
============================== ==========================================================================================
|
|
V_PKEY_HASH_EX_ID_MAP This is a database view used to map states to external ids.
|
|
============================== ==========================================================================================
|
|
OUTPUT_INDEX Reference to a state - index in transaction
|
|
TRANSACTION_ID Reference to a state - transaction id
|
|
PUBLIC_KEY_HASH The public key of the participant.
|
|
EXTERNAL_ID The external id.
|
|
============================== ==========================================================================================
|
|
|
|
|
|
Fungible states
|
|
^^^^^^^^^^^^^^^
|
|
|
|
.. image:: resources/database/vault_fungible_states.png
|
|
:scale: 50%
|
|
:align: center
|
|
|
|
|
|
============================== ==========================================================================================
|
|
VAULT_FUNGIBLE_STATES Properties specific to fungible states
|
|
============================== ==========================================================================================
|
|
OUTPUT_INDEX Reference to a state - index in transaction
|
|
TRANSACTION_ID Reference to a state - transaction id
|
|
ISSUER_NAME Issuer
|
|
ISSUER_REF Reference number used by the issuer
|
|
OWNER_NAME X500 name of the owner, or null if unknown
|
|
QUANTITY The amount.
|
|
============================== ==========================================================================================
|
|
|
|
|
|
============================== ==========================================================================================
|
|
VAULT_FUNGIBLE_STATES_PARTS Many-to-one participants to a fungible state
|
|
============================== ==========================================================================================
|
|
OUTPUT_INDEX Reference to a state - index in transaction
|
|
TRANSACTION_ID Reference to a state - transaction id
|
|
PARTICIPANTS X500 name of participant.
|
|
============================== ==========================================================================================
|
|
|
|
|
|
Linear states
|
|
^^^^^^^^^^^^^
|
|
|
|
.. image:: resources/database/vault_linear_states.png
|
|
:scale: 50%
|
|
:align: center
|
|
|
|
============================== ==========================================================================================
|
|
VAULT_LINEAR_STATES Properties specific to linear states
|
|
============================== ==========================================================================================
|
|
OUTPUT_INDEX Reference to a state - index in transaction
|
|
TRANSACTION_ID Reference to a state - transaction id
|
|
EXTERNAL_ID The external id of this linear state.
|
|
UUID The internal id of this linear state.
|
|
============================== ==========================================================================================
|
|
|
|
|
|
============================== ==========================================================================================
|
|
VAULT_LINEAR_STATES_PARTS Many-to-one participants to a linear state
|
|
============================== ==========================================================================================
|
|
OUTPUT_INDEX Reference to a state - index in transaction
|
|
TRANSACTION_ID Reference to a state - transaction id
|
|
PARTICIPANTS X500 name of participant.
|
|
============================== ==========================================================================================
|
|
|
|
|
|
|
|
|
|
Liquibase database migration
|
|
----------------------------
|
|
|
|
These are `Liquibase <https://www.liquibase.org>`_ proprietary tables used by Corda internally to manage schema change and evolution.
|
|
|
|
============================== ==========================================================================================
|
|
DATABASECHANGELOG Read more: `DATABASECHANGELOG <https://www.liquibase.org/documentation/databasechangelog_table.html>`_
|
|
============================== ==========================================================================================
|
|
ID
|
|
AUTHOR
|
|
FILENAME
|
|
DATEEXECUTED
|
|
ORDEREXECUTED
|
|
EXECTYPE
|
|
MD5SUM
|
|
DESCRIPTION
|
|
COMMENTS
|
|
TAG
|
|
LIQUIBASE
|
|
CONTEXTS
|
|
LABELS
|
|
DEPLOYMENT_ID
|
|
============================== ==========================================================================================
|
|
|
|
|
|
============================== ==========================================================================================
|
|
DATABASECHANGELOGLOCK Read more: `DATABASECHANGELOGLOCK <https://www.liquibase.org/documentation/databasechangeloglock_table.html>`_
|
|
============================== ==========================================================================================
|
|
ID
|
|
LOCKED
|
|
LOCKGRANTED
|
|
LOCKEDBY
|
|
============================== ==========================================================================================
|
|
|