From 64bf68f961b9b8603a1dad9ea383b4cda321d639 Mon Sep 17 00:00:00 2001
From: Aaron Craelius <aaronc@users.noreply.github.com>
Date: Wed, 3 Jul 2024 22:12:11 +0200
Subject: [PATCH] add READMEs, CHANGELOG.md

---
 indexer/postgres/CHANGELOG.md                 | 37 +++++++++++++++++
 indexer/postgres/README.md                    | 41 +++++++++++++++++++
 indexer/postgres/tests/README.md              |  3 ++
 indexer/postgres/{testing => tests}/go.mod    |  0
 indexer/postgres/{testing => tests}/go.sum    |  0
 .../{testing => tests}/init_schema_test.go    |  2 +-
 6 files changed, 82 insertions(+), 1 deletion(-)
 create mode 100644 indexer/postgres/CHANGELOG.md
 create mode 100644 indexer/postgres/README.md
 create mode 100644 indexer/postgres/tests/README.md
 rename indexer/postgres/{testing => tests}/go.mod (100%)
 rename indexer/postgres/{testing => tests}/go.sum (100%)
 rename indexer/postgres/{testing => tests}/init_schema_test.go (98%)

diff --git a/indexer/postgres/CHANGELOG.md b/indexer/postgres/CHANGELOG.md
new file mode 100644
index 000000000000..0c3c9d03857f
--- /dev/null
+++ b/indexer/postgres/CHANGELOG.md
@@ -0,0 +1,37 @@
+<!--
+Guiding Principles:
+
+Changelogs are for humans, not machines.
+There should be an entry for every single version.
+The same types of changes should be grouped.
+Versions and sections should be linkable.
+The latest version comes first.
+The release date of each version is displayed.
+Mention whether you follow Semantic Versioning.
+
+Usage:
+
+Change log entries are to be added to the Unreleased section under the
+appropriate stanza (see below). Each entry should ideally include a tag and
+the Github issue reference in the following format:
+
+* (<tag>) \#<issue-number> message
+
+The issue numbers will later be link-ified during the release process so you do
+not have to worry about including a link manually, but you can if you wish.
+
+Types of changes (Stanzas):
+
+"Features" for new features.
+"Improvements" for changes in existing functionality.
+"Deprecated" for soon-to-be removed features.
+"Bug Fixes" for any bug fixes.
+"Client Breaking" for breaking Protobuf, gRPC and REST routes used by end-users.
+"CLI Breaking" for breaking CLI commands.
+"API Breaking" for breaking exported APIs used by developers building on SDK.
+Ref: https://keepachangelog.com/en/1.0.0/
+-->
+
+# Changelog
+
+## [Unreleased]
diff --git a/indexer/postgres/README.md b/indexer/postgres/README.md
new file mode 100644
index 000000000000..a0c0fd1d9b5b
--- /dev/null
+++ b/indexer/postgres/README.md
@@ -0,0 +1,41 @@
+# PostgreSQL Indexer
+
+The PostgreSQL indexer can fully index current state for all modules that
+implement `cosmossdk.io/schema.HasModuleCodec`.
+
+## Table, Column and Enum Naming
+
+`ObjectType`s names are converted to table names prefixed with the module name and an underscore. i.e. the `ObjectType` `foo` in module `bar` will be stored in a table named `bar_foo`.
+
+Column names are identical to field names. All identifiers are quoted with double quotes so that they are case-sensitive and won't clash with any reserved names. 
+
+Like, table names, enum types are prefixed with the module name and an underscore.
+
+## Schema Type Mapping
+
+The mapping of `cosmossdk.io/schema` `Kind`s to PostgreSQL types is as follows:
+
+| Kind | PostgreSQL Type            | Notes                                                                                                                                                                           |
+|---------------------|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `StringKind`        | `TEXT`                     |                                                                                                                                                                                 |
+| `BoolKind`          | `BOOLEAN`                  |                                                                                                                                                                                 |
+| `BytesKind`         | `BYTEA`                    |                                                                                                                                                                                 |
+| `Int8Kind`          | `SMALLINT`                 |                                                                                                                                                                                 |
+| `Int16Kind`         | `SMALLINT`                 |                                                                                                                                                                                 |
+| `Int32Kind`         | `INTEGER`                  |                                                                                                                                                                                 |
+| `Int64Kind`         | `BIGINT`                   |                                                                                                                                                                                 |
+| `Uint8Kind`         | `SMALLINT`                 |                                                                                                                                                                                 |
+| `Uint16Kind`        | `INTEGER`                  |                                                                                                                                                                                 |
+| `Uint32Kind`        | `BIGINT`                   |                                                                                                                                                                                 |
+| `Uint64Kind`        | `NUMERIC`                  |                                                                                                                                                                                 |
+| `Float32Kind`       | `REAL`                     |                                                                                                                                                                                 |
+| `Float64Kind`       | `DOUBLE PRECISION`         |                                                                                                                                                                                 |
+| `IntegerStringKind` | `NUMERIC`                  |                                                                                                                                                                                 |
+| `DecimalStringKind` | `NUMERIC`                  |                                                                                                                                                                                 |
+| `JSONKind`          | `JSONB`                    |                                                                                                                                                                                 |
+| `Bech32AddressKind` | `TEXT`                     | addresses are converted to strings with the specified address prefix                                                                                                            |
+| `TimeKind`          | `BIGINT` and `TIMESTAMPTZ` | time types are stored as two columns, one with the `_nanos` suffix with full nano-seconds precision, and another as a `TIMESTAMPTZ` generated column with microsecond precision |
+| `DurationKind`      | `BIGINT`                   | durations are stored as a single column in nanoseconds                                                                                                                          |
+| `EnumKind` | `<module_name>_<enum_name>` | a custom enum type is created for each module prefixed with with module name it pertains to                                                                                     |
+
+
diff --git a/indexer/postgres/tests/README.md b/indexer/postgres/tests/README.md
new file mode 100644
index 000000000000..a57c86171104
--- /dev/null
+++ b/indexer/postgres/tests/README.md
@@ -0,0 +1,3 @@
+# PostgreSQL Indexer Tests
+
+The majority of tests for the PostgreSQL indexer are stored in this separate `tests` go module to keep the main indexer module free of dependencies on any particular PostgreSQL driver. This allows users to choose their own driver and integrate the indexer free of any dependency conflict concerns.
\ No newline at end of file
diff --git a/indexer/postgres/testing/go.mod b/indexer/postgres/tests/go.mod
similarity index 100%
rename from indexer/postgres/testing/go.mod
rename to indexer/postgres/tests/go.mod
diff --git a/indexer/postgres/testing/go.sum b/indexer/postgres/tests/go.sum
similarity index 100%
rename from indexer/postgres/testing/go.sum
rename to indexer/postgres/tests/go.sum
diff --git a/indexer/postgres/testing/init_schema_test.go b/indexer/postgres/tests/init_schema_test.go
similarity index 98%
rename from indexer/postgres/testing/init_schema_test.go
rename to indexer/postgres/tests/init_schema_test.go
index 95ff9c482de2..752b936f8151 100644
--- a/indexer/postgres/testing/init_schema_test.go
+++ b/indexer/postgres/tests/init_schema_test.go
@@ -1,4 +1,4 @@
-package testing
+package tests
 
 import (
 	"context"