doc(schema-diff): Add documentation on schema-diff script

This also will include a link to this documentation when leaving a
comment on a pull request.

Author: tmessi

.github/workflows/schema-diff.yml

@@ -59,6 +59,9 @@ jobs:
           cat << EOF > github-comment.txt
           $gh_comment_prefix \`${GITHUB_BASE_REF}\` and \`${GITHUB_HEAD_REF}\` @ ${{ github.event.pull_request.head.sha }}
 
+          To understand how these diffs are generated and some limitations see the
+          [documentation](https://github.com/hashicorp/boundary/blob/main/scripts/schema-diff.sh) of the script.
+
           #### Functions
           $(getdiff .schema-diff/funcs.diff)
 

scripts/schema-diff.sh

@@ -1,6 +1,40 @@
 #!/usr/bin/env bash
 # Copyright (c) HashiCorp, Inc.
 # SPDX-License-Identifier: MPL-2.0
+#
+# This script can aid in comparing the database schema between two commits.
+# It will:
+#
+#  1. Create a docker postgres database.
+#  2. Apply the schema migrations for the current commit.
+#  3. Create a dump of the database using pg_dump
+#  4. Destroy the database container
+#  5. Extract the definitions of specific database objects from the dump.
+#     These are extracted to place each definition into a separeate .sql file,
+#     which aids in the performing a diff that can detect renames.
+#  6. Switch to the provided base branch (defaults to main)
+#  7. Repeate the dump and extract process.
+#  8. Create diffs for each kind of database object using `git diff` to compare
+#     directories which helps with detecting renames.
+#
+# The dumps and extracted .sql files are left in place so they can be examined
+# and compared using other tools. For example an alternate diff tool like delta
+# could be used to view the diff to the functions:
+#
+#   delta .schema-diff/funcs_$(git rev-parse main) .schema-diff/funcs_$(git rev-parse HEAD)
+#
+# These files get removed if the script is run again, or can be manually removed with:
+#
+#   rm -r .schema-diff
+#
+# Limitations:
+#
+# Since this script is extracting specifc parts of the schema from
+# a database dump, there may be some differences that are not extracted and therefore
+# not reported. Some notable limitations follow:
+#
+# - domain definitions: These are not easily extracted from a pg_dump. Therefore
+#   changes to domain types or new domain definitions will not be present in the diff.
 
 die() {
     echo "$@"