Merge pull request #1784 from neondatabase/bgrenon-schema-diff-cli

schema-diff command added to docs

.gitignore

@@ -85,3 +85,4 @@ public/md
 
 content/docs/guides/time_travel_tutorial_before-1.png
 yarn.lock
+package-lock.json

content/docs/guides/schema-diff-tutorial.md

@@ -235,7 +235,11 @@ CREATE TABLE address (
 
 ## Step 4: View the schema differences
 
-Now that you have some differences between your branches, from the Neon Console go to the **Branches** page.
+Now that you have some differences between your branches, you can view the schema differences.
+
+<Tabs labels={["Console", "CLI"]}>
+
+<TabItem>
 
 1. Click on `dev/jordan` to open the detailed view, then under **Compare to Parent** click **Open schema diff**.
 
@@ -248,3 +252,45 @@ Now that you have some differences between your branches, from the Neon Console
 You will see the schema differences between `dev/jordan` and its parent `main`, including the new address table that we added to the `dev/jordan` branch.
 
 You can also launch Schema Diff from the **Restore** page, usually as part of verifying schemas before you restore a branch to its own or another branch's history. See [Branch restore](/docs/guides/branch-restore) for more info.
+
+</TabItem>
+
+<TabItem>
+
+Compare the schema of `dev/jordan` to its parent branch using the `schema-diff` command.
+
+```bash
+neonctl branches schema-diff main dev/jordan --database people
+```
+
+The result shows a comparison between the `dev/jordan` branch and its parent branch for the database `people`. The output indicates that the `address` table and its related sequences and constraints have been added in the `dev/jordan` branch but are not present in its parent branch `main`.
+
+```diff
+--- Database: people	(Branch: br-falling-dust-a5bakdqt) // [!code --]
++++ Database: people	(Branch: br-morning-heart-a5ltt10i) // [!code ++]
+@@ -20,8 +20,46 @@
+ 
+ SET default_table_access_method = heap;
+ 
+ --
++-- Name: address; Type: TABLE; Schema: public; Owner: neondb_owner // [!code ++]
++-- // [!code ++]
++ // [!code ++]
++CREATE TABLE public.address ( // [!code ++]
++    id integer NOT NULL, // [!code ++]
++    person_id integer NOT NULL, // [!code ++]
++    street text NOT NULL, // [!code ++]
++    city text NOT NULL, // [!code ++]
++    state text NOT NULL, // [!code ++]
++    zip_code text NOT NULL // [!code ++]
++); // [!code ++]
++ // [!code ++]
++ // [!code ++]
++ALTER TABLE public.address OWNER TO neondb_owner; // [!code ++]
++ // [!code ++]
++... // [!code ++]
+```
+
+</TabItem>
+
+</Tabs>

content/docs/guides/schema-diff.md

@@ -13,6 +13,8 @@ Schema Diff is available in the Neon Console for use in two ways:
 - Compare a branch's schema to its parent
 - Compare selected branches during a branch restore operation
 
+You can also use the `branches schema-diff` command in the Neon CLI to effect a variety of comparisons.
+
 ### Compare to parent
 
 In the detailed view for any child branch, you can check the schema differences between the selected branch and its parent. Use this view to verify the state of these schemas before you [Reset from parent](/docs/guides/reset-from-parent).
@@ -21,11 +23,16 @@ In the detailed view for any child branch, you can check the schema differences
 
 Built into the Time Travel assist editor, you can use Schema Diff to help when restoring branches, letting you compare states of your branch against its own or another branch's history before you complete a [branch restore](/docs/guides/branch-restore) operation.
 
+### Comparisons using the CLI
+
+You can use the Neon CLI to compare a branch to any point in its own or any other branch's history. The `branches schema-diff` command offers full flexibility for any type of schema comparison: between a branch and its parent, a branch and its earlier state, or a branch to the head or prior state of another branch.
+
 ### Practical Applications
 
 - **Pre-Migration Reviews**: Before migrating schemas from a development branch into main, use Schema Diff to ensure only intended schema changes are applied.
 - **Audit Changes**: Historically compare schema changes to understand the evolution of your database structure.
 - **Consistency Checks**: Ensure environment consistency by comparing schemas across development, staging, and production branches.
+- **Automation**: Integrate schema-diff into CI/CD pipelines to automatically compare schemas during deployments.
 
 ## How to Use Schema Diff
 
@@ -47,10 +54,44 @@ The two-pane view shows the schema for both your target and your selected branch
 
 ![schema diff results](/docs/guides/schema_diff_result.png)
 
+### Using the Neon CLI
+
+You can use the Neon CLI to:
+
+- Compare the latest schemas of any two branches
+- Compare against a specific point in its own or another branch’s history
+
+Use the `schema-diff` subcommand from the `branches` command:
+
+```bash
+neonctl branches schema-diff [base-branch] [compare-source[@(timestamp|lsn)]]
+```
+
+The operation will compare a selected branch (`[compare-source]`) against the latest (head) of your base branch (`[base-branch]`). For example, if you want to compare recent changes you made to your development branch `dev/alex` against your production branch `main`, identify `main` as your base branch and `dev/alex` as your compare-source.
+
+```bash
+neonctl branches schema-diff main dev/alex
+```
+
+You have a few options here:
+
+- Append a timestamp or LSN to compare to a specific point in `dev/alex` branch's history.
+- If you are regularly comparing development branches against `main`, include `main` in your `set-context` file. You can then leave out the [base-branch] from the command.
+- Use aliases to shorten the command.
+- Include `--database` to reduce the diff to a single database. If you don't specify a database, the diff will include all databases on the branch.
+
+Here is the same command using aliases, with `main` included in `set-context`, pointing to an LSN from `dev/alex` branch's history, and limiting the diff to the database `people`:
+
+```bash
+neon branch sd dev/alex@0/123456 --db people
+```
+
+To find out what other comparisons you can make, see [Neon CLI commands — branches](/docs/reference/cli-branches#schema-diff) for full documentation of the command.
+
 ### Understanding the Output
 
-- **Green Highlight**: Indicates additions or new elements in the schema.
-- **Red Highlight**: Marks deletions or removed elements from the schema.
+- **+ Green Highlight**: Indicates additions or new elements in the schema.
+- **- Red Highlight**: Marks deletions or removed elements from the schema.
 
 ## Tutorial
 

content/docs/reference/cli-branches.md

@@ -27,6 +27,7 @@ neonctl branches <subcommand> [options]
 | [reset](#reset)   | Reset data to parent
 | [restore](#restore) | Restore a branch to a selected point in time
 | [rename](#rename)   | Rename a branch |
+| [schema-diff](#schema-diff) | Compare schemas |
 | [set-primary](#set-primary)   | Set a primary branch |
 | [add-compute](#add-compute)   | Add replica to a branch |
 | [delete](#delete)  | Delete a branch |
@@ -443,6 +444,96 @@ neonctl branches rename mybranch teambranch
 └───────────────────────┴────────────┴──────────────────────┴──────────────────────┘
 ```
 
+## schema-diff
+
+This command:
+
+- Compares the latest schemas of any two branches
+- Compares against a specific point in its own or another branch’s history
+
+#### Usage
+
+```
+neonctl branches schema-diff [base-branch] [compare-source[@(timestamp|lsn)]]
+```
+
+`[base-branch]` specifies the branch you want to compare against. For example, if you want to compare a development branch against the production branch `main`, select `main` as your base.
+
+This setting is **optional**. If you leave it out, the operation uses either of the following as the base:
+
+- The branch identified in the `set-context` file
+- If no context is configured, it uses your project's primary branch
+
+`[compare-source]` specifies the branch or state to compare against. Options are:
+
+- `^self` &#8212; compares the selected branch to an earlier point in its own history. You must specify a timestamp or LSN.
+- `^parent` &#8212; compares the selected branch to the head of its parent branch. You can append `@timestamp` or `@lsn` to compare to an earlier point in the parent's history.
+- `<compare-branch-id|name>` &#8212; compares the selected branch to the head of another specified branch. Append `@timestamp` or `@lsn` to compare to an earlier point in the specified branch's history.
+
+#### Examples
+
+Examples of different kinds of schema diff operations you can do:
+
+- [Compare to another branch's head](#compare-to-another-branchs-head)
+- [Compare to an earlier point in a branch's history](#comparing-a-branch-to-an-earlier-point-in-its-history)
+- [Compare a branch to its parent](#comparing-a-branch-to-its-parent)
+- [Compare to an earlier point in another branch's history](#comparing-a-branch-to-an-earlier-point-in-another-branchs-history)
+
+#### Compare to another branch's head
+
+This command compares the schema of the `main` branch to the head of the branch `dev/alex`.
+
+```
+neonctl branches schema-diff main dev/alex
+```
+
+The output indicates that in the table `public.playing_with_neon`, a new column `description character varying(255)` has been added in the `dev/alex` branch that is not present in the `main` branch.
+
+```diff
+--- Database: neondb	(Branch: br-wandering-firefly-a50un462) // [!code --]
++++ Database: neondb	(Branch: br-fancy-sky-a5cydw8p) // [!code ++]
+@@ -26,9 +26,10 @@
+ 
+ CREATE TABLE public.playing_with_neon (
+     id integer NOT NULL,
+     name text NOT NULL,
+-    value real [!code --]
++    value real, // [!code ++]
++    description character varying(255) // [!code ++]
+ );
+ 
+ 
+ ALTER TABLE public.playing_with_neon OWNER TO neondb_owner;
+```
+
+
+ ALTER TABLE public.playing_with_neon OWNER TO neondb_owner;
+```
+
+#### Comparing a branch to an earlier point in its history
+
+This command compares the schema of `dev-alex` to a previous state in its history at LSN 0/123456.
+
+```
+neonctl branches schema-diff dev-alex ^self@0/123456
+```
+
+#### Comparing a branch to its parent
+
+This command compares the schema of `dev/alex` to the head of its parent branch.
+
+```
+neonctl branches schema-diff dev/alex ^parent
+```
+
+#### Comparing a branch to an earlier point in another branch's history
+
+This command compares the schema of the `main` branch to the state of the `dev/jordan` branch at timestamp 2024-06-01T00:00:00.000Z
+
+```bash
+neonctl branches schema-diff main dev/jordan@2024-06-01T00:00:00.000Z
+```
+
 ## set-primary
 
 This subcommand allows you to set a branch as the primary branch in your Neon project.

content/docs/reference/neon-cli.md

@@ -134,7 +134,7 @@ Options:
 | [me](/docs/reference/cli-me)                                         |                                        | Show current user         |
 | [projects](/docs/reference/cli-projects)                             | `list`, `create`, `update`, `delete`, `get` | Manage projects           |
 | [ip-allow](/docs/reference/cli-ip-allow)                             | `list`, `add`, `remove`, `reset`       | Manage IP Allow           |
-| [branches](/docs/reference/cli-branches)                             | `list`, `create`, `reset`, `restore`, `rename`, `add-compute`, `set-primary`, `delete`, `get` | Manage branches           |
+| [branches](/docs/reference/cli-branches)                             | `list`, `create`, `reset`, `restore`, `rename`, `schema-diff`, `set-primary`, `add-compute`, `delete`, `get` | Manage branches           |
 | [databases](/docs/reference/cli-databases)                           | `list`, `create`, `delete`             | Manage databases          |
 | [roles](/docs/reference/cli-roles)                                   | `list`, `create`,  `delete`            | Manage roles              |
 | [operations](/docs/reference/cli-operations)                         | `list`                                 | Manage operations         |