feat: Add Table-Store (aka ORM) package - Genesis

x/group/internal/orm/auto_uint64.go

@@ -3,9 +3,13 @@ package orm
 import (
 	"github.com/cosmos/cosmos-sdk/codec"
 	sdk "github.com/cosmos/cosmos-sdk/types"
+	"github.com/cosmos/cosmos-sdk/types/errors"
 )
 
-var _ Indexable = &AutoUInt64Table{}
+var (
+	_ Indexable       = &AutoUInt64Table{}
+	_ TableExportable = &AutoUInt64Table{}
+)
 
 // AutoUInt64Table is the table type with an auto incrementing ID.
 type AutoUInt64Table struct {
@@ -106,3 +110,27 @@ func (a AutoUInt64Table) PrefixScan(store sdk.KVStore, start, end uint64) (Itera
 func (a AutoUInt64Table) ReversePrefixScan(store sdk.KVStore, start uint64, end uint64) (Iterator, error) {
 	return a.table.ReversePrefixScan(store, EncodeSequence(start), EncodeSequence(end))
 }
+
+// Sequence returns the sequence used by this table
+func (a AutoUInt64Table) Sequence() Sequence {
+	return a.seq
+}
+
+// Export stores all the values in the table in the passed ModelSlicePtr and
+// returns the current value of the associated sequence.
+func (a AutoUInt64Table) Export(store sdk.KVStore, dest ModelSlicePtr) (uint64, error) {
+	_, err := a.table.Export(store, dest)
+	if err != nil {
+		return 0, err
+	}
+	return a.seq.CurVal(store), nil
+}
+
+// Import clears the table and initializes it from the given data interface{}.
+// data should be a slice of structs that implement PrimaryKeyed.
+func (a AutoUInt64Table) Import(store sdk.KVStore, data interface{}, seqValue uint64) error {
+	if err := a.seq.InitVal(store, seqValue); err != nil {
+		return errors.Wrap(err, "sequence")
+	}
+	return a.table.Import(store, data, seqValue)
+}

x/group/internal/orm/genesis.go

@@ -0,0 +1,19 @@
+package orm
+
+import (
+	sdk "github.com/cosmos/cosmos-sdk/types"
+)
+
+// TableExportable
+type TableExportable interface {
+	// Export stores all the values in the table in the passed
+	// ModelSlicePtr. If the table has an associated sequence, then its
+	// current value is returned, otherwise 0 is returned by default.
+	Export(sdk.KVStore, ModelSlicePtr) (uint64, error)
+
+	// Import clears the table and initializes it from the given data
+	// interface{}. data should be a slice of structs that implement
+	// PrimaryKeyed. The seqValue is optional and only
+	// used with tables that have an associated sequence.
+	Import(sdk.KVStore, interface{}, uint64) error
+}

x/group/internal/orm/genesis_test.go

@@ -0,0 +1,57 @@
+package orm
+
+import (
+	"testing"
+
+	"github.com/cosmos/cosmos-sdk/codec"
+	"github.com/cosmos/cosmos-sdk/codec/types"
+	"github.com/cosmos/cosmos-sdk/testutil/testdata"
+	sdk "github.com/cosmos/cosmos-sdk/types"
+	"github.com/stretchr/testify/require"
+)
+
+func TestImportExportTableData(t *testing.T) {
+	interfaceRegistry := types.NewInterfaceRegistry()
+	cdc := codec.NewProtoCodec(interfaceRegistry)
+
+	table, err := NewAutoUInt64Table(AutoUInt64TablePrefix, AutoUInt64TableSeqPrefix, &testdata.TableModel{}, cdc)
+	require.NoError(t, err)
+
+	ctx := NewMockContext()
+	store := ctx.KVStore(sdk.NewKVStoreKey("test"))
+
+	tms := []*testdata.TableModel{
+		{
+			Id:       1,
+			Name:     "my test 1",
+			Number:   123,
+			Metadata: []byte("metadata 1"),
+		},
+		{
+			Id:       2,
+			Name:     "my test 2",
+			Number:   456,
+			Metadata: []byte("metadata 2"),
+		},
+	}
+
+	err = table.Import(store, tms, 2)
+	require.NoError(t, err)
+
+	for _, g := range tms {
+		var loaded testdata.TableModel
+		_, err := table.GetOne(store, g.Id, &loaded)
+		require.NoError(t, err)
+
+		require.Equal(t, g, &loaded)
+	}
+
+	var exported []*testdata.TableModel
+	seq, err := table.Export(store, &exported)
+	require.NoError(t, err)
+	require.Equal(t, seq, uint64(2))
+
+	for i, g := range exported {
+		require.Equal(t, g, tms[i])
+	}
+}

x/group/internal/orm/orm_scenario_test.go

@@ -1,6 +1,7 @@
 package orm
 
 import (
+	"bytes"
 	"encoding/binary"
 	"fmt"
 	"testing"
@@ -15,6 +16,9 @@ import (
 	"github.com/cosmos/cosmos-sdk/testutil/testdata"
 )
 
+// Testing ORM with arbitrary metadata length
+const metadataLen = 10
+
 func TestKeeperEndToEndWithAutoUInt64Table(t *testing.T) {
 	interfaceRegistry := types.NewInterfaceRegistry()
 	cdc := codec.NewProtoCodec(interfaceRegistry)
@@ -275,6 +279,144 @@ func TestGasCostsPrimaryKeyTable(t *testing.T) {
 	}
 }
 
+func TestExportImportStateAutoUInt64Table(t *testing.T) {
+	interfaceRegistry := types.NewInterfaceRegistry()
+	cdc := codec.NewProtoCodec(interfaceRegistry)
+
+	ctx := NewMockContext()
+	store := ctx.KVStore(sdk.NewKVStoreKey("test"))
+
+	k := NewTestKeeper(cdc)
+
+	testRecordsNum := 10
+	for i := 1; i <= testRecordsNum; i++ {
+		tm := testdata.TableModel{
+			Id:       uint64(i),
+			Name:     fmt.Sprintf("my test %d", i),
+			Metadata: bytes.Repeat([]byte{byte(i)}, metadataLen),
+		}
+
+		rowID, err := k.autoUInt64Table.Create(store, &tm)
+		require.NoError(t, err)
+		require.Equal(t, uint64(i), rowID)
+	}
+	var tms []*testdata.TableModel
+	seqVal, err := k.autoUInt64Table.Export(store, &tms)
+	require.NoError(t, err)
+
+	// when a new db seeded
+	ctx = NewMockContext()
+	store = ctx.KVStore(sdk.NewKVStoreKey("test"))
+
+	err = k.autoUInt64Table.Import(store, tms, seqVal)
+	require.NoError(t, err)
+
+	// then all data is set again
+	for i := 1; i <= testRecordsNum; i++ {
+		require.True(t, k.autoUInt64Table.Has(store, uint64(i)))
+		var loaded testdata.TableModel
+		rowID, err := k.autoUInt64Table.GetOne(store, uint64(i), &loaded)
+		require.NoError(t, err)
+
+		require.Equal(t, RowID(EncodeSequence(uint64(i))), rowID)
+		assert.Equal(t, fmt.Sprintf("my test %d", i), loaded.Name)
+		exp := bytes.Repeat([]byte{byte(i)}, metadataLen)
+		assert.Equal(t, exp, loaded.Metadata)
+
+		// and also the indexes
+		exists, err := k.autoUInt64TableModelByMetadataIndex.Has(store, exp)
+		require.NoError(t, err)
+		require.True(t, exists)
+
+		it, err := k.autoUInt64TableModelByMetadataIndex.Get(store, exp)
+		require.NoError(t, err)
+		var all []testdata.TableModel
+		ReadAll(it, &all)
+		require.Len(t, all, 1)
+		assert.Equal(t, loaded, all[0])
+	}
+	require.Equal(t, uint64(testRecordsNum), k.autoUInt64Table.Sequence().CurVal(store))
+}
+
+func TestExportImportStatePrimaryKeyTable(t *testing.T) {
+	interfaceRegistry := types.NewInterfaceRegistry()
+	cdc := codec.NewProtoCodec(interfaceRegistry)
+
+	ctx := NewMockContext()
+	store := ctx.KVStore(sdk.NewKVStoreKey("test"))
+
+	k := NewTestKeeper(cdc)
+
+	testRecordsNum := 10
+	testRecords := make([]testdata.TableModel, testRecordsNum)
+	for i := 1; i <= testRecordsNum; i++ {
+		tm := testdata.TableModel{
+			Id:       uint64(i),
+			Name:     fmt.Sprintf("my test %d", i),
+			Number:   uint64(i - 1),
+			Metadata: bytes.Repeat([]byte{byte(i)}, metadataLen),
+		}
+
+		err := k.primaryKeyTable.Create(store, &tm)
+		require.NoError(t, err)
+		testRecords[i-1] = tm
+	}
+	var tms []*testdata.TableModel
+	_, err := k.primaryKeyTable.Export(store, &tms)
+	require.NoError(t, err)
+
+	// when a new db seeded
+	ctx = NewMockContext()
+	store = ctx.KVStore(sdk.NewKVStoreKey("test"))
+
+	err = k.primaryKeyTable.Import(store, tms, 0)
+	require.NoError(t, err)
+
+	// then all data is set again
+	it, err := k.primaryKeyTable.PrefixScan(store, nil, nil)
+	require.NoError(t, err)
+	var loaded []testdata.TableModel
+	keys, err := ReadAll(it, &loaded)
+	require.NoError(t, err)
+	for i := range keys {
+		assert.Equal(t, PrimaryKey(&testRecords[i]), keys[i].Bytes())
+	}
+	assert.Equal(t, testRecords, loaded)
+
+	// and first index setup
+	for _, v := range testRecords {
+		it, err = k.primaryKeyTableModelByNameIndex.Get(store, v.Name)
+		require.NoError(t, err)
+		loaded = nil
+		keys, err = ReadAll(it, &loaded)
+		require.NoError(t, err)
+		assert.Equal(t, []RowID{PrimaryKey(&v)}, keys)
+		assert.Equal(t, []testdata.TableModel{v}, loaded)
+	}
+
+	// and second index setup
+	for _, v := range testRecords {
+		it, err = k.primaryKeyTableModelByNumberIndex.Get(store, v.Number)
+		require.NoError(t, err)
+		loaded = nil
+		keys, err = ReadAll(it, &loaded)
+		require.NoError(t, err)
+		assert.Equal(t, []RowID{PrimaryKey(&v)}, keys)
+		assert.Equal(t, []testdata.TableModel{v}, loaded)
+	}
+
+	// and uint64 index setup
+	for _, v := range testRecords {
+		it, err = k.primaryKeyTableModelByMetadataIndex.Get(store, v.Metadata)
+		require.NoError(t, err)
+		loaded = nil
+		keys, err = ReadAll(it, &loaded)
+		require.NoError(t, err)
+		assert.Equal(t, []RowID{PrimaryKey(&v)}, keys)
+		assert.Equal(t, []testdata.TableModel{v}, loaded)
+	}
+}
+
 func first(t *testing.T, it Iterator) ([]byte, testdata.TableModel) {
 	var loaded testdata.TableModel
 	key, err := First(it, &loaded)

x/group/internal/orm/primary_key.go

@@ -5,7 +5,10 @@ import (
 	sdk "github.com/cosmos/cosmos-sdk/types"
 )
 
-var _ Indexable = &PrimaryKeyTable{}
+var (
+	_ Indexable       = &PrimaryKeyTable{}
+	_ TableExportable = &PrimaryKeyTable{}
+)
 
 // PrimaryKeyTable provides simpler object style orm methods without passing database RowIDs.
 // Entries are persisted and loaded with a reference to their unique primary key.
@@ -144,3 +147,14 @@ func (a PrimaryKeyTable) PrefixScan(store sdk.KVStore, start, end []byte) (Itera
 func (a PrimaryKeyTable) ReversePrefixScan(store sdk.KVStore, start, end []byte) (Iterator, error) {
 	return a.table.ReversePrefixScan(store, start, end)
 }
+
+// Export stores all the values in the table in the passed ModelSlicePtr.
+func (a PrimaryKeyTable) Export(store sdk.KVStore, dest ModelSlicePtr) (uint64, error) {
+	return a.table.Export(store, dest)
+}
+
+// Import clears the table and initializes it from the given data interface{}.
+// data should be a slice of structs that implement PrimaryKeyed.
+func (a PrimaryKeyTable) Import(store sdk.KVStore, data interface{}, seqValue uint64) error {
+	return a.table.Import(store, data, seqValue)
+}

x/group/internal/orm/spec/01_table.md

@@ -15,6 +15,8 @@ The `table` struct does not:
 - 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.
 
+`table` provides methods for exporting (using a [`PrefixScan` `Iterator`](03_iterator_pagination.md#iterator)) and importing genesis data. For the import to be successful, objects have to be aware of their primary key by implementing the [`PrimaryKeyed`](#primarykeyed) interface.
+
 ## AutoUInt64Table
 
 `AutoUInt64Table` is a table type with an auto incrementing `uint64` ID.
@@ -27,6 +29,8 @@ It's based on the `Sequence` struct which is a persistent unique key generator b
 
 `PrimaryKeyTable` provides simpler object style orm methods where are persisted and loaded with a reference to their unique primary key.
 
+### PrimaryKeyed
+
 The model provided for creating a `PrimaryKeyTable` should implement the `PrimaryKeyed` interface:
 
 +++ https://github.com/cosmos/cosmos-sdk/blob/9f78f16ae75cc42fc5fe636bde18a453ba74831f/x/group/internal/orm/primary_key.go#L28-L41

x/group/internal/orm/table.go

@@ -12,7 +12,10 @@ import (
 	"github.com/cosmos/cosmos-sdk/x/group/errors"
 )
 
-var _ Indexable = &table{}
+var (
+	_ Indexable       = &table{}
+	_ TableExportable = &table{}
+)
 
 // table is the high level object to storage mapper functionality. Persistent
 // entities are stored by an unique identifier called `RowID`. The table struct
@@ -232,6 +235,53 @@ func (a table) ReversePrefixScan(store sdk.KVStore, start, end RowID) (Iterator,
 	}, nil
 }
 
+// Export stores all the values in the table in the passed ModelSlicePtr.
+func (a table) Export(store sdk.KVStore, dest ModelSlicePtr) (uint64, error) {
+	it, err := a.PrefixScan(store, nil, nil)
+	if err != nil {
+		return 0, sdkerrors.Wrap(err, "table Export failure when exporting table data")
+	}
+	_, err = ReadAll(it, dest)
+	if err != nil {
+		return 0, err
+	}
+	return 0, nil
+}
+
+// Import clears the table and initializes it from the given data interface{}.
+// data should be a slice of structs that implement PrimaryKeyed.
+func (a table) Import(store sdk.KVStore, data interface{}, _ uint64) error {
+	// Clear all data
+	pStore := prefix.NewStore(store, a.prefix[:])
+	it := pStore.Iterator(nil, nil)
+	defer it.Close()
+	for ; it.Valid(); it.Next() {
+		if err := a.Delete(store, it.Key()); err != nil {
+			return err
+		}
+	}
+
+	// Provided data must be a slice
+	modelSlice := reflect.ValueOf(data)
+	if modelSlice.Kind() != reflect.Slice {
+		return sdkerrors.Wrap(errors.ErrORMInvalidArgument, "data must be a slice")
+	}
+
+	// Import values from slice
+	for i := 0; i < modelSlice.Len(); i++ {
+		obj, ok := modelSlice.Index(i).Interface().(PrimaryKeyed)
+		if !ok {
+			return sdkerrors.Wrapf(errors.ErrORMInvalidArgument, "unsupported type :%s", reflect.TypeOf(data).Elem().Elem())
+		}
+		err := a.Create(store, PrimaryKey(obj), obj)
+		if err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
 // typeSafeIterator is initialized with a type safe RowGetter only.
 type typeSafeIterator struct {
 	store     sdk.KVStore