From 9d2758368cf6ecb0816f5496e492c50eaf4c610f Mon Sep 17 00:00:00 2001
From: Timothy Messier <tim.messier@gmail.com>
Date: Fri, 24 Mar 2023 19:17:00 +0000
Subject: [PATCH] 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.
---
 .github/workflows/schema-diff.yml |  3 +++
 scripts/schema-diff.sh            | 34 +++++++++++++++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/.github/workflows/schema-diff.yml b/.github/workflows/schema-diff.yml
index 08aa5a33b..e7cf136b4 100644
--- a/.github/workflows/schema-diff.yml
+++ b/.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)
 
diff --git a/scripts/schema-diff.sh b/scripts/schema-diff.sh
index 70290a3c0..c8291053d 100755
--- a/scripts/schema-diff.sh
+++ b/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 "$@"