doc: add schema diff policy (#1635)

doc/md/atlas-schema/projects.mdx

@@ -484,6 +484,8 @@ set or map item. See the example [below](#multi-environment-example).
   - `git.base` - A run analysis against the base Git branch.
   - `git.dir` - A path to the repository working directory.
 
+- `diff` - A block defines the schema diffing policy.
+
 ##### Multi Environment Example
 
 Atlas adopts the `for_each` meta-argument that [Terraform uses](https://www.terraform.io/language/meta-arguments/for_each)
@@ -594,5 +596,30 @@ env "ci" {
 }
 ```
 
+## Configure Diff Policy
+
+Project files may define `diff` blocks to configure how schema diffing runs in a specific environment or globally.
 
 
+```hcl
+diff {
+  skip {
+    // By default, none of the changes are skipped.
+    drop_schema = true
+    drop_table  = true
+  }
+  concurrent_index {
+    create = true
+    drop   = true
+  }
+}
+
+env "local" {
+  // Define a specific schema diffing policy for this environment.
+  diff {
+    skip {
+      drop_schema = true
+    }
+  }
+}
+```

doc/md/declarative/apply.mdx

@@ -56,6 +56,54 @@ Atlas with a connection string to a [_Dev-Database_](../concepts/dev.mdx).
 This database is used to normalize the schema prior to planning migrations and
 for simulating changes to ensure their applicability before execution.
 
+## Diff Policy
+
+Atlas allows configuring the schema diffing policy in [project configuration](../atlas-schema/projects.mdx) to fine-tune
+or modify suggested changes before applying them to the database:
+
+<Tabs>
+<TabItem label="Skip Destructive" value="skip">
+
+```hcl title="atlas.hcl"
+variable "destructive" {
+  type    = bool
+  default = false
+}
+
+env "local" {
+  diff {
+    skip {
+      drop_schema = !var.destructive
+      drop_table  = !var.destructive
+    }
+  }
+}
+```
+
+The usage is as follows:
+
+```go
+atlas schema apply --env "local" --var "destructive=true"
+```
+
+</TabItem>
+<TabItem label="Concurrent Indexes" value="concurrent_indexes">
+
+```hcl title="atlas.hcl"
+env "local" {
+  diff {
+    // By default, indexes are not created or dropped concurrently.
+    concurrent_index {
+      create = true
+      drop   = true
+    }
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
 ## Examples
 
 ### HCL schema

doc/md/declarative/diff.mdx

@@ -29,6 +29,55 @@ SQL schema, or a migration directory.
 * `--exclude` (optional, may be supplied multiple times) - filter out resources matching the given glob pattern.
 * `--format` (optional) - [Go template](https://pkg.go.dev/text/template) to use to format the output.
 
+
+## Diff Policy
+
+Atlas allows configuring the schema diffing policy in [project configuration](../atlas-schema/projects.mdx) to fine-tune
+or modify suggested changes before they are printed:
+
+<Tabs>
+<TabItem label="Skip Destructive" value="skip">
+
+```hcl title="atlas.hcl"
+variable "destructive" {
+  type    = bool
+  default = false
+}
+
+env "local" {
+  diff {
+    skip {
+      drop_schema = !var.destructive
+      drop_table  = !var.destructive
+    }
+  }
+}
+```
+
+The usage is as follows:
+
+```go
+atlas schema diff --env "local" --var "destructive=true"
+```
+
+</TabItem>
+<TabItem label="Concurrent Indexes" value="concurrent_indexes">
+
+```hcl title="atlas.hcl"
+env "local" {
+  diff {
+    // By default, indexes are not created or dropped concurrently.
+    concurrent_index {
+      create = true
+      drop   = true
+    }
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
 ## Examples
 
 ### Compare databases
@@ -79,7 +128,6 @@ atlas schema diff \
 </TabItem>
 </Tabs>
 
-
 ### Compare database schemas
 
 <Tabs

doc/md/versioned/diff.mdx

@@ -774,7 +774,59 @@ CREATE TABLE "market"."users" ("name" integer NOT NULL);
 As you can see, Atlas generates statements for creating the `auth` and `market` schemas,
 and added them as qualifiers in the created tables.
 
-### Indented SQL
+
+## Diff Policy
+
+Atlas allows configuring the schema diffing policy in [project configuration](../atlas-schema/projects.mdx) to fine-tune
+or modify suggested changes before they are written to the migration directory:
+
+<Tabs>
+<TabItem label="Skip Destructive" value="skip">
+
+```hcl title="atlas.hcl"
+variable "destructive" {
+  type    = bool
+  default = false
+}
+
+env "local" {
+  migration {
+    dir = "file://migrations"
+  }
+  diff {
+    skip {
+      drop_schema = !var.destructive
+      drop_table  = !var.destructive
+    }
+  }
+}
+```
+
+The usage is as follows:
+
+```go
+atlas migrate diff --env "local" --var "destructive=true"
+```
+
+</TabItem>
+<TabItem label="Concurrent Indexes" value="concurrent_indexes">
+
+```hcl title="atlas.hcl"
+env "local" {
+  diff {
+    // By default, indexes are not created or dropped concurrently.
+    concurrent_index {
+      create = true
+      drop   = true
+    }
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+## Indented SQL
 
 The `migrate diff` command generates a list of SQL statements without indentation by default. If you would like to
 generate the SQL statements with indentation, use the `--format` flag. For example:
@@ -788,6 +840,6 @@ atlas migrate diff create_users \
   --format '{{ sql . "  " }}'
 ```
 
-### Reference
+## Reference
 
 [CLI Command Reference](/cli-reference#atlas-migrate-diff)