From c4c28c0933352e74cf4deacc0375de27b4560447 Mon Sep 17 00:00:00 2001 From: Ariel Mashraki <7413593+a8m@users.noreply.github.com> Date: Sun, 22 Sep 2024 12:19:50 +0300 Subject: [PATCH] doc: add new plan commands to readme (#234) * Update README.md * doc: update readme with new plan commands --- README.md | 129 ++++++++++++++++++++++++++++++--- atlasaction/action.go | 2 +- schema/apply/action.yml | 2 +- schema/plan/action.yml | 2 +- schema/plan/approve/action.yml | 2 + schema/push/action.yml | 7 +- 6 files changed, 127 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index f6cba436..e7261aac 100644 --- a/README.md +++ b/README.md @@ -9,15 +9,19 @@ To learn more about the recommended way to build workflows, read our guide on ## Actions -| Action | Description | -|--------------------------------------------------------------------|---------------------------------------------------------| -| [ariga/setup-atlas](#arigasetup-atlas) | Setup the Atlas CLI and optionally login to Atlas Cloud | -| [ariga/atlas-action/migrate/push](#arigaatlas-actionmigratepush) | Push migrations to Atlas Cloud | -| [ariga/atlas-action/migrate/lint](#arigaatlas-actionmigratelint) | Lint migrations (required `atlas login` ) | -| [ariga/atlas-action/migrate/apply](#arigaatlas-actionmigrateapply) | Apply migrations to a database | -| [ariga/atlas-action/migrate/down](#arigaatlas-actionmigratedown) | Revert migrations to a database | -| [ariga/atlas-action/migrate/test](#arigaatlas-actionmigratetest) | Test migrations on a database | -| [ariga/atlas-action/schema/test](#arigaatlas-actionschematest) | Test schema on a database | +| Action | Description | +|-------------------------------------------------------------------------------|------------------------------------------------------------------| +| [ariga/setup-atlas](#arigasetup-atlas) | Setup the Atlas CLI and optionally login to Atlas Cloud | +| [ariga/atlas-action/migrate/push](#arigaatlas-actionmigratepush) | Push migrations to [Atlas Registry](https://atlasgo.io/registry) | +| [ariga/atlas-action/migrate/lint](#arigaatlas-actionmigratelint) | Lint migrations (required `atlas login` ) | +| [ariga/atlas-action/migrate/apply](#arigaatlas-actionmigrateapply) | Apply migrations to a database | +| [ariga/atlas-action/migrate/down](#arigaatlas-actionmigratedown) | Revert migrations to a database | +| [ariga/atlas-action/migrate/test](#arigaatlas-actionmigratetest) | Test migrations on a database | +| [ariga/atlas-action/schema/test](#arigaatlas-actionschematest) | Test schema on a database | +| [ariga/atlas-action/schema/push](#arigaatlas-actionschemapush) | Push a schema to [Atlas Registry](https://atlasgo.io/registry) | +| [ariga/atlas-action/schema/plan](#arigaatlas-actionschemaplan) | Plan a declarative migration for a schema transition | +| [ariga/atlas-action/schema/plan/approve](#arigaatlas-actionschemaplanapprove) | Approve a declarative migration plan | +| [ariga/atlas-action/schema/apply](#arigaatlas-actionschemaapply) | Apply a declarative migrations to a database | ## Examples @@ -294,7 +298,7 @@ All inputs are optional as they may be specified in the Atlas configuration file ### `ariga/atlas-action/migrate/test` -Test migrations on a database. +Run schema migration tests. Read more in [Atlas website](https://atlasgo.io/testing/migrate). #### Inputs @@ -316,7 +320,7 @@ All inputs are optional as they may be specified in the Atlas configuration file ### `ariga/atlas-action/schema/test` -Test schema on a database. +Run schema tests on the desired schema. Read more in [Atlas website](https://atlasgo.io/testing/schema). #### Inputs @@ -335,6 +339,109 @@ All inputs are optional as they may be specified in the Atlas configuration file For example: `'{"var1": "value1", "var2": "value2"}'`. * `working-directory` - The working directory to run from. Defaults to project root. +### `ariga/atlas-action/schema/apply` + +Apply a declarative migrations to a database. + +#### Inputs + +* `to` - The URL(s) of the desired schema state. +* `plan` - Optional plan file to use for applying the migrations. For example: `atlas:///plans/`. +* `dry-run` - Print SQL (and optional analysis) without executing it. Either `true` or `false`. Defaults to `false`. +* `auto-approve` - Automatically approve and apply changes. Either `true` or `false`. Defaults to `false`. +* `dev-url` - The URL of the dev-database to use for analysis. For example: `mysql://root:pass@localhost:3306/dev`. + Read more about [dev-databases](https://atlasgo.io/concepts/dev-database). +* `config` - The URL of the Atlas configuration file. By default, Atlas will look for a file + named `atlas.hcl` in the current directory. For example, `file://config/atlas.hcl`. + Learn more about [Atlas configuration files](https://atlasgo.io/atlas-schema/projects). +* `env` - The environment to use from the Atlas configuration file. For example, `dev`. +* `vars` - Stringify JSON object containing variables to be used inside the Atlas configuration file. + For example: `'{"var1": "value1", "var2": "value2"}'`. +* `working-directory` - The working directory to run from. Defaults to project root. + +#### Outputs + +* `error` - The error message if the action fails. + +### `ariga/atlas-action/schema/push` + +Push a schema to [Atlas Registry](https://atlasgo.io/registry) with an optional tag. + +#### Inputs + +* `schema-name` - The name (slug) of the schema repository in [Atlas Registry](https://atlasgo.io/registry). +* `tag` - The tag to apply to the pushed schema. By default, the current git commit hash is used. +* `latest` - Whether to implicitly push the `latest` tag. True by default. +* `dev-url` - The URL of the dev-database to use for analysis. For example: `mysql://root:pass@localhost:3306/dev`. + Read more about [dev-databases](https://atlasgo.io/concepts/dev-database). +* `config` - The URL of the Atlas configuration file. By default, Atlas will look for a file + named `atlas.hcl` in the current directory. For example, `file://config/atlas.hcl`. + Learn more about [Atlas configuration files](https://atlasgo.io/atlas-schema/projects). +* `env` - The environment to use from the Atlas configuration file. For example, `dev`. +* `vars` - Stringify JSON object containing variables to be used inside the Atlas configuration file. + For example: `'{"var1": "value1", "var2": "value2"}'`. +* `working-directory` - The working directory to run from. Defaults to project root. + +#### Outputs + +* `slug` - The slug of the schema repository in [Atlas Registry](https://atlasgo.io/registry). +* `link` - The URL of the schema in [Atlas Registry](https://atlasgo.io/registry). +* `url` - The URL of the pushed schema version in Atlas format. For example, `atlas://app`. + +### `ariga/atlas-action/schema/plan` + +Plan a declarative migration for a schema transition. + +#### Inputs + +* `schema-name` - The name (slug) of the schema repository in [Atlas Registry](https://atlasgo.io/registry). +* `from` - URL(s) of the current schema state to transition from. +* `to` - URL(s) of the desired schema state to transition to. +* `name` - Optional name for the plan. If not provided, a default plan is generated by Atlas. +* `dev-url` - The URL of the dev-database to use for analysis. For example: `mysql://root:pass@localhost:3306/dev`. + Read more about [dev-databases](https://atlasgo.io/concepts/dev-database). +* `config` - The URL of the Atlas configuration file. By default, Atlas will look for a file + named `atlas.hcl` in the current directory. For example, `file://config/atlas.hcl`. + Learn more about [Atlas configuration files](https://atlasgo.io/atlas-schema/projects). +* `env` - The environment to use from the Atlas configuration file. For example, `dev`. +* `vars` - Stringify JSON object containing variables to be used inside the Atlas configuration file. + For example: `'{"var1": "value1", "var2": "value2"}'`. +* `working-directory` - The working directory to run from. Defaults to project root. + +#### Outputs + +* `plan` - The URL of the generated plan in Atlas format. For example, `atlas://app/plans/123`. +* `link` - The URL of the plan in [Atlas Registry](https://atlasgo.io/registry). +* `status` - The status of the plan. For example, `PENDING` or `APPROVED`. + +### `ariga/atlas-action/schema/plan/approve` + +Approve a declarative migration plan. + +#### Inputs + +* `schema-name` - The name (slug) of the schema repository in [Atlas Registry](https://atlasgo.io/registry). +* `from` - URL(s) of the current schema state to transition from. +* `to` - URL(s) of the desired schema state to transition to. +* `plan` - Optional URL of the plan to be approved. For example, `atlas:///plans/`. By default, Atlas + searches in the registry for a plan corresponding to the given schema transition and approves it (typically, this plan + is created during the PR stage). If multiple plans are found, an error will be thrown. +* `dev-url` - The URL of the dev-database to use for analysis. For example: `mysql://root:pass@localhost:3306/dev`. + Read more about [dev-databases](https://atlasgo.io/concepts/dev-database). +* `config` - The URL of the Atlas configuration file. By default, Atlas will look for a file + named `atlas.hcl` in the current directory. For example, `file://config/atlas.hcl`. + Learn more about [Atlas configuration files](https://atlasgo.io/atlas-schema/projects). +* `env` - The environment to use from the Atlas configuration file. For example, `dev`. +* `vars` - Stringify JSON object containing variables to be used inside the Atlas configuration file. + For example: `'{"var1": "value1", "var2": "value2"}'`. +* `working-directory` - The working directory to run from. Defaults to project root. + +#### Outputs + +* `plan` - The URL of the generated plan in Atlas format. For example, `atlas://app/plans/123`. +* `link` - The URL of the plan in [Atlas Registry](https://atlasgo.io/registry). +* `status` - The status of the plan. For example, `PENDING` or `APPROVED`. + ### Legal The source code for this GitHub Action is released under the Apache 2.0 diff --git a/atlasaction/action.go b/atlasaction/action.go index c0e3f1e5..e9e2f13c 100644 --- a/atlasaction/action.go +++ b/atlasaction/action.go @@ -93,7 +93,7 @@ type AtlasExec interface { SchemaApplySlice(context.Context, *atlasexec.SchemaApplyParams) ([]*atlasexec.SchemaApply, error) } -// Context holds the context of the environment the action is running in. +// TriggerContext holds the context of the environment the action is running in. type TriggerContext struct { SCM SCM // SCM is the source control management system. Repo string // Repo is the repository name. e.g. "ariga/atlas-action". diff --git a/schema/apply/action.yml b/schema/apply/action.yml index 6e39287b..516e9fdf 100644 --- a/schema/apply/action.yml +++ b/schema/apply/action.yml @@ -31,7 +31,7 @@ inputs: URL(s) of the desired schema state. required: false plan: - description: The plan to apply. (ig. `atlas:///plans/`) + description: The plan to apply. For example, `atlas:///plans/`. required: false dry-run: description: Print SQL without executing it. Either "true" or "false". diff --git a/schema/plan/action.yml b/schema/plan/action.yml index cf09091a..46c76b8c 100644 --- a/schema/plan/action.yml +++ b/schema/plan/action.yml @@ -47,7 +47,7 @@ outputs: link: # id of the output description: Link to the schema plan on Atlas. status: - description: The status of the plan. (ig. `PENDING`, `APPROVED`) + description: The status of the plan. For example, `PENDING` or `APPROVED`. runs: using: node20 main: index.js diff --git a/schema/plan/approve/action.yml b/schema/plan/approve/action.yml index 352efec1..3870ea9b 100644 --- a/schema/plan/approve/action.yml +++ b/schema/plan/approve/action.yml @@ -29,6 +29,8 @@ inputs: plan: description: | The URL of the plan to be approved. For example, `atlas:///plans/`. + If not provided, Atlas will search the registry for a plan corresponding to the given schema transition and approve it + (typically, this plan is created during the PR stage). If multiple plans are found, an error will be thrown. required: false schema-name: description: The name (slug) of the project in Atlas Cloud. diff --git a/schema/push/action.yml b/schema/push/action.yml index b671a2ba..0ae4d60b 100644 --- a/schema/push/action.yml +++ b/schema/push/action.yml @@ -27,7 +27,9 @@ inputs: Read more about [dev-databases](https://atlasgo.io/concepts/dev-database). required: false schema-name: - description: The name (slug) of the project in Atlas Cloud. + description: | + The name (slug) of the schema repository in Atlas Registry. + Read more in Atlas website: https://atlasgo.io/registry. required: false description: description: The description of the schema changes. @@ -37,8 +39,7 @@ inputs: required: false tag: description: | - The tag to apply to the pushed migration directory. By default the - current git commit hash is used. + The tag to apply to the pushed schema. By default, the current git commit hash is used. required: false latest: description: |