From 04a6c310ee78ac43683dc8bfb3b590ba2622ab90 Mon Sep 17 00:00:00 2001
From: Timothy Messier <tim.messier@gmail.com>
Date: Fri, 24 Mar 2023 18:33:57 +0000
Subject: [PATCH 1/2] fix(schema-diff): Include foreign key constraints in diff

With the change to report changes to constraints instead of all of the
post-data section, foreign key constraints where no longer captured in
the diff. This now extracts the foreign key constraints and generates a
diff of them between versions.

Blame: b6d58d0c42ea197f040c54e468ec284ec0023054
---
 .github/workflows/schema-diff.yml |  3 +++
 scripts/schema-diff.sh            | 11 ++++++++---
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/schema-diff.yml b/.github/workflows/schema-diff.yml
index 32cee482e..08aa5a33b 100644
--- a/.github/workflows/schema-diff.yml
+++ b/.github/workflows/schema-diff.yml
@@ -76,6 +76,9 @@ jobs:
 
           #### Constraints
           $(getdiff .schema-diff/constraints.diff)
+
+          #### Foreign Key Constraints
+          $(getdiff .schema-diff/fk_constraints.diff)
           EOF
 
           # Parse it through jq to build a valid json object.
diff --git a/scripts/schema-diff.sh b/scripts/schema-diff.sh
index 2c695ab43..70290a3c0 100755
--- a/scripts/schema-diff.sh
+++ b/scripts/schema-diff.sh
@@ -2,7 +2,6 @@
 # Copyright (c) HashiCorp, Inc.
 # SPDX-License-Identifier: MPL-2.0
 
-
 die() {
     echo "$@"
     exit 255
@@ -43,7 +42,8 @@ extract() {
         "${tmp_dir}/views_${suffix}" \
         "${tmp_dir}/triggers_${suffix}" \
         "${tmp_dir}/indexes_${suffix}" \
-        "${tmp_dir}/constraints_${suffix}"
+        "${tmp_dir}/constraints_${suffix}" \
+        "${tmp_dir}/fk_constraints_${suffix}"
 
     echo "extracting function definitions from ${dump}"
     while read -r f; do
@@ -79,6 +79,11 @@ extract() {
         cName="${c#* }"
         pg_restore --section=post-data -O -f - "${dump}" | grep ${cName} | tr '[:upper:]' '[:lower:]' > "${tmp_dir}/constraints_${suffix}/${cName}.sql"
     done < <(pg_restore -l "${dump}" -f - | awk '$4 == "CONSTRAINT" {for(i=6;i<NF;i++) printf $i" "; print ""}')
+
+    while read -r c; do
+        cName="${c#* }"
+        pg_restore --section=post-data -O -f - "${dump}" | grep ${cName} | tr '[:upper:]' '[:lower:]' > "${tmp_dir}/fk_constraints_${suffix}/${cName}.sql"
+    done < <(pg_restore -l "${dump}" -f - | awk '$4 == "FK" && $5 == "CONSTRAINT" {for(i=7;i<NF;i++) printf $i" "; print ""}')
 }
 
 dump() {
@@ -125,6 +130,6 @@ else
     git checkout "${new_branch}"
 fi
 
-for t in "funcs" "tables" "views" "triggers" "indexes" "constraints"; do
+for t in "funcs" "tables" "views" "triggers" "indexes" "constraints" "fk_constraints"; do
     git diff --no-index "${tmp_dir}/${t}_${base_commit}" "${tmp_dir}/${t}_${new_commit}" | tee "${tmp_dir}/${t}.diff"
 done

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 2/2] 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 "$@"