From 41a361ed8d9755b62972140fc3ddb7a9826e3529 Mon Sep 17 00:00:00 2001 From: "M. J. Fromberger" Date: Tue, 24 Aug 2021 14:18:27 -0700 Subject: [PATCH] psql: add documentation and simplify constructor API (#6856) Add documentation comments to the psql event sink package, and simplify the constructor function so that it does not return the SQL database handle. The handle is needed for testing, so expose that via a separate method on the concrete type. Update the tests and existing usage for the change. This change does not affect the behaviour of the sink, so there are no functional changes, only syntactic updates. --- cmd/tendermint/commands/reindex_event.go | 4 +-- state/indexer/indexer_service_test.go | 13 ++++----- state/indexer/sink/psql/psql.go | 34 +++++++++++++++++------- state/indexer/sink/psql/psql_test.go | 13 +++------ state/indexer/sink/sink.go | 2 +- 5 files changed, 36 insertions(+), 30 deletions(-) diff --git a/cmd/tendermint/commands/reindex_event.go b/cmd/tendermint/commands/reindex_event.go index ddc585c1f..1dbce2f74 100644 --- a/cmd/tendermint/commands/reindex_event.go +++ b/cmd/tendermint/commands/reindex_event.go @@ -31,7 +31,7 @@ var ReIndexEventCmd = &cobra.Command{ Long: ` reindex-event is an offline tooling to re-index block and tx events to the eventsinks, you can run this command when the event store backend dropped/disconnected or you want to replace the backend. - The default start-height is 0, meaning the tooling will start reindex from the base block height(inclusive); and the + The default start-height is 0, meaning the tooling will start reindex from the base block height(inclusive); and the default end-height is 0, meaning the tooling will reindex until the latest block height(inclusive). User can omits either or both arguments. `, @@ -106,7 +106,7 @@ func loadEventSinks(cfg *tmcfg.Config) ([]indexer.EventSink, error) { if conn == "" { return nil, errors.New("the psql connection settings cannot be empty") } - es, _, err := psql.NewEventSink(conn, chainID) + es, err := psql.NewEventSink(conn, chainID) if err != nil { return nil, err } diff --git a/state/indexer/indexer_service_test.go b/state/indexer/indexer_service_test.go index 68a00afb5..457ed065a 100644 --- a/state/indexer/indexer_service_test.go +++ b/state/indexer/indexer_service_test.go @@ -164,19 +164,16 @@ func setupDB(t *testing.T) (*dockertest.Pool, error) { conn := fmt.Sprintf(dsn, user, password, resource.GetPort(port+"/tcp"), dbName) - if err = pool.Retry(func() error { - var err error - - pSink, psqldb, err = psql.NewEventSink(conn, "test-chainID") - + assert.NoError(t, pool.Retry(func() error { + sink, err := psql.NewEventSink(conn, "test-chainID") if err != nil { return err } + pSink = sink + psqldb = sink.DB() return psqldb.Ping() - }); err != nil { - assert.Error(t, err) - } + })) resetDB(t) diff --git a/state/indexer/sink/psql/psql.go b/state/indexer/sink/psql/psql.go index efb539e0b..8bd378f4a 100644 --- a/state/indexer/sink/psql/psql.go +++ b/state/indexer/sink/psql/psql.go @@ -1,3 +1,4 @@ +// Package psql implements an event sink backed by a PostgreSQL database. package psql import ( @@ -24,28 +25,38 @@ const ( DriverName = "postgres" ) -// EventSink is an indexer backend providing the tx/block index services. +// EventSink is an indexer backend providing the tx/block index services. This +// implementation stores records in a PostgreSQL database using the schema +// defined in state/indexer/sink/psql/schema.sql. type EventSink struct { store *sql.DB chainID string } -func NewEventSink(connStr string, chainID string) (indexer.EventSink, *sql.DB, error) { +// NewEventSink constructs an event sink associated with the PostgreSQL +// database specified by connStr. Events written to the sink are attributed to +// the specified chainID. +func NewEventSink(connStr, chainID string) (*EventSink, error) { db, err := sql.Open(DriverName, connStr) if err != nil { - return nil, nil, err + return nil, err } return &EventSink{ store: db, chainID: chainID, - }, db, nil + }, nil } -func (es *EventSink) Type() indexer.EventSinkType { - return indexer.PSQL -} +// DB returns the underlying Postgres connection used by the sink. +// This is exported to support testing. +func (es *EventSink) DB() *sql.DB { return es.store } + +// Type returns the structure type for this sink, which is Postgres. +func (es *EventSink) Type() indexer.EventSinkType { return indexer.PSQL } +// IndexBlockEvents indexes the specified block header, part of the +// indexer.EventSink interface. func (es *EventSink) IndexBlockEvents(h types.EventDataNewBlockHeader) error { sqlStmt := sq. Insert(TableEventBlock). @@ -156,18 +167,22 @@ func (es *EventSink) IndexTxEvents(txr []*abci.TxResult) error { return err } +// SearchBlockEvents is not implemented by this sink, and reports an error for all queries. func (es *EventSink) SearchBlockEvents(ctx context.Context, q *query.Query) ([]int64, error) { return nil, errors.New("block search is not supported via the postgres event sink") } +// SearchTxEvents is not implemented by this sink, and reports an error for all queries. func (es *EventSink) SearchTxEvents(ctx context.Context, q *query.Query) ([]*abci.TxResult, error) { return nil, errors.New("tx search is not supported via the postgres event sink") } +// GetTxByHash is not implemented by this sink, and reports an error for all queries. func (es *EventSink) GetTxByHash(hash []byte) (*abci.TxResult, error) { return nil, errors.New("getTxByHash is not supported via the postgres event sink") } +// HasBlock is not implemented by this sink, and reports an error for all queries. func (es *EventSink) HasBlock(h int64) (bool, error) { return false, errors.New("hasBlock is not supported via the postgres event sink") } @@ -206,6 +221,5 @@ func indexBlockEvents( return sqlStmt, nil } -func (es *EventSink) Stop() error { - return es.store.Close() -} +// Stop closes the underlying PostgreSQL database. +func (es *EventSink) Stop() error { return es.store.Close() } diff --git a/state/indexer/sink/psql/psql_test.go b/state/indexer/sink/psql/psql_test.go index 0df773a53..35ad7eea3 100644 --- a/state/indexer/sink/psql/psql_test.go +++ b/state/indexer/sink/psql/psql_test.go @@ -341,19 +341,14 @@ func setupDB(t *testing.T) (*dockertest.Pool, error) { conn := fmt.Sprintf(dsn, user, password, resource.GetPort(port+"/tcp"), dbName) - if err = pool.Retry(func() error { - var err error - - _, db, err = NewEventSink(conn, chainID) - + require.NoError(t, pool.Retry(func() error { + sink, err := NewEventSink(conn, chainID) if err != nil { return err } - + db = sink.DB() // set global for test use return db.Ping() - }); err != nil { - require.NoError(t, err) - } + })) resetDB(t) diff --git a/state/indexer/sink/sink.go b/state/indexer/sink/sink.go index 1e50721c6..f9dfa54df 100644 --- a/state/indexer/sink/sink.go +++ b/state/indexer/sink/sink.go @@ -51,7 +51,7 @@ func EventSinksFromConfig(cfg *config.Config, dbProvider config.DBProvider, chai return nil, errors.New("the psql connection settings cannot be empty") } - es, _, err := psql.NewEventSink(conn, chainID) + es, err := psql.NewEventSink(conn, chainID) if err != nil { return nil, err }