diff --git a/.changeset/two-gorillas-mix.md b/.changeset/two-gorillas-mix.md
new file mode 100644
index 000000000..9f6ef4b6b
--- /dev/null
+++ b/.changeset/two-gorillas-mix.md
@@ -0,0 +1,5 @@
+---
+'@nhost/docs': minor
+---
+
+feat: added postgres upgrade docs
diff --git a/docs/guides/database/upgrade-major.mdx b/docs/guides/database/upgrade-major.mdx
new file mode 100644
index 000000000..867c84305
--- /dev/null
+++ b/docs/guides/database/upgrade-major.mdx
@@ -0,0 +1,37 @@
+---
+title: "Upgrade Major Version"
+description: Upgrade to Postgres 15.x or 16.y
+icon: circle-up
+---
+
+# Upgrade process
+
+<Info>
+This document only applies when changing Postgres major version (i.e. from 14 to 15/16 or from 15 to 16). It doesn'e apply when upgrading minor versions (i.e. from 14.5 to 14.11).
+</Info>
+
+While new cloud projects ship with Postgres 14 by default, versions 15 and 16 are also supported. To change your major version you can go to Settings -> Database, select the new major version and start the process:
+
+![dashboard settings](/images/guides/database/upgrade_01.png)
+
+<Warning>
+Keep in mind that the upgrade process requires downtime. Pay attention to all the information provided to you in the settings page.
+</Warning>
+
+After starting the process you can follow it on the same page:
+
+![logs](/images/guides/database/upgrade_02.png)
+
+Finally, you can confirm the upgrade by executing the SQL query `SELECT version();`
+
+![select version()](/images/guides/database/upgrade_03.png)
+
+## Projects with connected repos
+
+This process can only be triggered from the dashboard. If you have a project with a connected repository and want to upgrade postgres to either 15 or 16 you will have to follow the steps below:
+
+1. Upgrade the major version using the dashboard
+2. Run `nhost config pull` or edit the `nhost.toml` by hand.
+3. Push to git (this step should be a NOOP and can be skipped)
+
+If you attempt to change major versions via a deployment the deployment will fail. This is done on purpose to avoid unintended upgrades which can lead to downtime.
diff --git a/docs/images/guides/database/upgrade_01.png b/docs/images/guides/database/upgrade_01.png
new file mode 100644
index 000000000..bff8b99fb
Binary files /dev/null and b/docs/images/guides/database/upgrade_01.png differ
diff --git a/docs/images/guides/database/upgrade_02.png b/docs/images/guides/database/upgrade_02.png
new file mode 100644
index 000000000..d8b47a07f
Binary files /dev/null and b/docs/images/guides/database/upgrade_02.png differ
diff --git a/docs/images/guides/database/upgrade_03.png b/docs/images/guides/database/upgrade_03.png
new file mode 100644
index 000000000..cb3eff228
Binary files /dev/null and b/docs/images/guides/database/upgrade_03.png differ
diff --git a/docs/mint.json b/docs/mint.json
index 589e64301..147b0c691 100644
--- a/docs/mint.json
+++ b/docs/mint.json
@@ -117,7 +117,8 @@
         "guides/database/configuring-postgres",
         "guides/database/access",
         "guides/database/extensions",
-        "guides/database/performance"
+        "guides/database/performance",
+        "guides/database/upgrade-major"
       ]
     },
     {