diff --git a/doc/md/guides/evaluation/01-intro.md b/doc/md/guides/evaluation/01-intro.md index ef508dfab1d..fc788a2a338 100644 --- a/doc/md/guides/evaluation/01-intro.md +++ b/doc/md/guides/evaluation/01-intro.md @@ -20,9 +20,9 @@ This guide is divided into the following sections: 1. **Installation** - How to install Atlas and verify that it is able to understand your database. 2. **Setting Up** - Setting up your project's structure for local work. 3. **Developer Workflow** - Review working with Atlas from the end-user perspective. -4. **Setting Up CI Pipelines** - How to integrate Atlas into your CI/CD pipelines. -5. **Security Checklist** - Things you should consider for when designing deployment pipelines. -6. **Migrating Existing Projects** - How to migrate existing projects to Atlas. +4. **Migrating Existing Projects** - How to migrate existing projects to Atlas. +5. **Setting Up CI Pipelines** - How to integrate Atlas into your CI/CD pipelines. +6. **Security Checklist** - Things you should consider for when designing deployment pipelines. ### Need help? diff --git a/doc/md/guides/evaluation/08-versioned-migrations-flows.mdx b/doc/md/guides/evaluation/08-versioned-migrations-flows.mdx index b783d6c21ed..586b88b1e08 100644 --- a/doc/md/guides/evaluation/08-versioned-migrations-flows.mdx +++ b/doc/md/guides/evaluation/08-versioned-migrations-flows.mdx @@ -1,4 +1,183 @@ --- -id: dev-flow-versioned -title: Dev Flows for Versioned Migrations ---- \ No newline at end of file +id: local-dev +title: Local Development +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +With our setup complete, let's now turn to focusing on what it's like to work with Atlas in a local development environment. + +This section assumes that you have been following along with the previous sections and have already set +up your project configuration file and schema. + +# Local Flows to Evaluate + +This section will guide you through the following local development flows: + +* Applying migrations locally + +* Planning migrations + +* Editing automatically generated migrations + +* Creating manual migrations + +* Undoing local changes + +## Applying migrations locally + +During development, developers often need to provision a local database with the latest schema. + +For the purpose of this guide we will assume that you have created a local database using docker and have stored +the connection URL to it in an environment variable named `$LOCAL_DB_URL`. + +To apply the latest migrations to your local database, run the following command: + +```shell +atlas migrate apply --env local --url "$LOCAL_DB_URL" +``` + +## Planning migrations + +As applications evolve, so do their database schemas. This section will guide you through the process of planning +a new migration. + +#### Step 1: Modify the desired schema + +Atlas automatically plans migrations by comparing the desired schema with the _current_ schema of the database +(as represented by replaying all existing migrations from start to end). To plan a new migration, you will need to +modify the desired schema. + +For example, suppose you want to add a new column to a table, you would first modify your desired schema to include +this column. Depending on how you defined your desired state in the [Schema-as-Code](/guides/evaluation/schema-as-code) step, here are some examples of +how you might modify your schema: + + + + +```diff title="schema.hcl" +table "users" { + // redacted ++ column "email" { ++ type = text ++ } +} +``` + + + +```diff title="schema.sql" +CREATE TABLE users ( + -- redacted ++ email TEXT +); +``` + + + + +```diff title="models.py" +class User(models.Model): + # redacted ++ email = models.TextField() +``` + + + + +#### Step 2: Plan the migration + +To plan the migration, run the following command: + +```shell +atlas migrate diff --env local +``` + +This command will calculate the difference between the desired schema and the current schema of the database +and output the migration that would be applied to bring the database schema up to date. For instance: + +```sql title="20240604131146_add_email_column.sql" +ALTER TABLE users ADD COLUMN email TEXT; +``` + +#### Step 3: Verify the migration + +Atlas provides a `migrate lint` command that can be used to verify that the migration is valid and will not cause +any issues when applied. To lint the migration, run the following command: + +```shell +atlas migrate lint --env local --latest 1 +``` + +This command will lint the latest migration in the `migrations/` directory. If you have multiple migrations, you can +specify the number of migrations to lint by changing the `--latest` flag. + +## Editing Automatically Generated Migrations + +In some cases, you may need to edit a migration that was automatically generated by Atlas. For example, you may need +want to set the transaction mode on a file level using a custom directive: + +```sql +//highlight-next-line +-- atlas:txmode none + +CREATE INDEX CONCURRENTLY name_idx ON users (name); +``` + +After manually editing a generated migration file, you must re-calculate the checksum of the migration directory +using the `migrate hash` command: + +```shell +atlas migrate hash --env local +``` + +## Created Manual Migrations + +In some cases, you may need to create a migration manually. One common example is when you need to backfill data +in a table. To create a manual migration, run the following command: + +```shell +atlas migrate new --env local my_new_migration +``` + +This command will create a new migration file in the `migrations/` directory with the name `_my_new_migration.sql`. + +Next, edit the contents of the generated migration file to include what you want and re-calculate the checksum of the +migration directory using the `migrate hash` command: + +```shell +atlas migrate hash --env local +``` + +As a convenience, you can use the `--edit` flag to open the newly created migration file in your default editor: + +```shell +atlas migrate new --env local my_new_migration --edit +``` + +Upon saving the file, Atlas will automatically re-calculate the checksum of the migration directory for you. + +## Undoing Local Changes + +If you are not content with a migration you have planned and applied locally or if you want to revert a migration +you have applied, *before deleting the latest migration file*, you can use the `migrate down` command: + +```shell +atlas migrate down --env local --url "$LOCAL_DB_URL" +``` + +This will undo the statements in the latest migration file. If you would like to remove the migration file as well, +you can use the `migrate rm` command: + +```shell +atlas migrate rm --env local +``` \ No newline at end of file diff --git a/doc/website/sidebars.js b/doc/website/sidebars.js index 5c19bfb809e..ccd24420625 100644 --- a/doc/website/sidebars.js +++ b/doc/website/sidebars.js @@ -586,5 +586,16 @@ module.exports = { } ] }, + { + type: 'category', + label: 'Developer Flows', + collapsed: false, + items: [ + { + type: 'doc', + id: 'guides/evaluation/local-dev' + } + ] + } ] };