certusone
/
cosmos-sdk
mirror of https://github.com/certusone/cosmos-sdk.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
cosmos-sdk/x/group/internal/orm/spec
History
Marie Gauthier c7a933cd6e
feat: Add Table-Store (aka ORM) package - Table and Indexable (#9751) 
<!--
The default pull request template is for types feat, fix, or refactor.
For other templates, add one of the following parameters to the url:
- template=docs.md
- template=other.md
-->

## Description

ref: https://github.com/cosmos/cosmos-sdk/issues/9237, https://github.com/cosmos/cosmos-sdk/discussions/9156

This is the first step towards the migration of the [Table-Store (ORM) package](c99dbedd1f/orm) currently in regen-ledger into the SDK. This won't be exposed as a public API to start with but rather be internal to `x/group`.

This first PR brings these core concepts:
- `table` is the high level object for storage mapper functionality where entities are stored by an unique identifier called `RowID`
- `Indexable` types can be used to setup new tables.

There will be follow-up PRs for adding the following features:
- table types with auto-incrementing `uint64` primary keys and natural primary keys
- secondary indexes
- iterator and pagination
- import/export genesis


---

### Author Checklist

*All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.*

I have...

- [x] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [x] added `!` to the type prefix if API or client breaking change
- [x] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting))
- [x] provided a link to the relevant issue or specification
- [ ] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules) _not applicable_
- [x] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing)
- [ ] added a changelog entry to `CHANGELOG.md` _not applicable_
- [x] included comments for [documenting Go code](https://blog.golang.org/godoc)
- [x] updated the relevant documentation or specification
- [x] reviewed "Files changed" and left comments if necessary
- [x] confirmed all CI checks have passed

### Reviewers Checklist

*All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.*

I have...

- [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] confirmed `!` in the type prefix if API or client breaking change
- [ ] confirmed all author checklist items have been addressed 
- [ ] reviewed state machine logic
- [ ] reviewed API design and naming
- [ ] reviewed documentation is accurate
- [ ] reviewed tests and test coverage
- [ ] manually tested (if applicable)
 		2021-10-21 10:19:52 +00:00
..
README.md feat: Add Table-Store (aka ORM) package - Table and Indexable (#9751) 2021-10-21 10:19:52 +00:00

README.md

Abstract

The orm package provides a framework for creating relational database tables with primary and secondary keys.

Tables

type table struct {
	model       reflect.Type
	prefix      [2]byte
	afterSet   []AfterSetInterceptor
	afterDelete []AfterDeleteInterceptor
	cdc         codec.Codec
}

A table can be built given a codec.ProtoMarshaler model type, a prefix to access the underlying prefix store used to store table data as well as a Codec for marshalling/unmarshalling. In the prefix store, entities should be stored by an unique identifier called RowID which can be based either on an uint64 auto-increment counter, string or dynamic size bytes. Regular CRUD operations can be performed on a table, these methods take a sdk.KVStore as parameter to get the table prefix store.

The table struct does not:

  • enforce uniqueness of the RowID
  • enforce prefix uniqueness of keys, i.e. not allowing one key to be a prefix of another
  • optimize Gas usage conditions The table struct is private, so that we only have custom tables built on top of it, that do satisfy these requirements.