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

@@ -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
 			}

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)
 

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() }

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)
 

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
 			}