Update docs for new versionSchema field (#887)

Update documentation for the new `versionSchema` field and add an
example migration.

--- 

This PR is part of a stack:
* #884
* #886 
* #887 (this PR)

Author: andrew-farries

docs/operations/README.md

@@ -5,14 +5,17 @@
 YAML migration:
 
 ```yaml
+version_schema: <version schema name>
 operations: [...]
 ```
 
 JSON migration:
 
 ```json
 {
+  "version_schema": "<version schema name>",
   "operations": [...]
 }
 ```
 
+The `version_schema` field is optional and specifies the name of the schema that will be created for the migration. If not specified, the name of the migration file (minus any `.yaml` or `.json` suffix) will be used as the schema name.

docs/operations/create_table.mdx

@@ -231,3 +231,7 @@ Create a table with table level foreign key constraints:
 Create a table with an exclusion:
 
 <ExampleSnippet example="52_create_table_with_exclusion_constraint.yaml" languange="yaml" />
+
+### Create a table and set the version_schema field for the migration
+
+<ExampleSnippet example="56_with_version_schema.yaml" languange="yaml" />

examples/.ledger

@@ -53,3 +53,4 @@
 53_add_column_with_volatile_default.yaml
 54_create_index_with_opclass.yaml
 55_add_primary_key_constraint_to_table.yaml
+56_with_version_schema.yaml

examples/56_with_version_schema.yaml

@@ -0,0 +1,11 @@
+version_schema: with_version_schema
+operations:
+  - create_table:
+      name: products
+      columns:
+        - name: id
+          type: serial
+          pk: true
+        - name: name
+          type: varchar(255)
+          unique: true

pkg/migrations/types.go

@@ -1162,6 +1162,10 @@
           "description": "Name of the migration",
           "type": "string"
         },
+        "version_schema": {
+          "description": "Name of the version schema to use for this migration",
+          "type": "string"
+        },
         "operations": {
           "$ref": "#/$defs/PgRollOperations"
         }