golang/ent
1
0
Fork 0
mirror of https://github.com/ent/ent.git synced 2026-03-05 19:35:23 +03:00
Code Issues Packages Projects Releases Wiki Activity

doc: upadte migrate diff command (#3329)

Browse Source 
* doc: upadte migrate diff command

* Update doc/md/components/_installation_instructions.mdx

Co-authored-by: Hila Kashai <73284641+hilakashai@users.noreply.github.com>

* Update doc/md/getting-started.mdx

Co-authored-by: Hila Kashai <73284641+hilakashai@users.noreply.github.com>

* Update doc/md/getting-started.mdx

Co-authored-by: Hila Kashai <73284641+hilakashai@users.noreply.github.com>

* Update doc/md/getting-started.mdx

Co-authored-by: Hila Kashai <73284641+hilakashai@users.noreply.github.com>

* Update doc/md/getting-started.mdx

Co-authored-by: Hila Kashai <73284641+hilakashai@users.noreply.github.com>

* Update doc/md/getting-started.mdx

Co-authored-by: Hila Kashai <73284641+hilakashai@users.noreply.github.com>

* Update doc/md/getting-started.mdx

Co-authored-by: Hila Kashai <73284641+hilakashai@users.noreply.github.com>

* Update doc/md/getting-started.mdx

Co-authored-by: Hila Kashai <73284641+hilakashai@users.noreply.github.com>

* Update doc/md/getting-started.mdx

Co-authored-by: Hila Kashai <73284641+hilakashai@users.noreply.github.com>

* Update doc/md/getting-started.mdx

Co-authored-by: Hila Kashai <73284641+hilakashai@users.noreply.github.com>

* Update doc/md/versioned-migrations.mdx

Co-authored-by: Rotem Tamir <rotemtamir@gmail.com>

* Update doc/md/versioned-migrations.mdx

Co-authored-by: Rotem Tamir <rotemtamir@gmail.com>

---------

Co-authored-by: Hila Kashai <73284641+hilakashai@users.noreply.github.com>
Co-authored-by: Rotem Tamir <rotemtamir@gmail.com>
This commit is contained in:
Ariel Mashraki
2023-02-19 16:20:59 +02:00
committed by GitHub
parent e671138bb8
commit 639e1093a0
8 changed files with 353 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
doc/md/components/_atlas_migrate_apply.mdx Normal file
View File

@@ -0,0 +1,48 @@
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs
defaultValue="mysql"
values={[
{label: 'MySQL', value: 'mysql'},
{label: 'MariaDB', value: 'maria'},
{label: 'PostgreSQL', value: 'postgres'},
{label: 'SQLite', value: 'sqlite'},
]}>
<TabItem value="mysql">
```shell
atlas migrate apply \
--dir "file://ent/migrate/migrations" \
--url "mysql://root:pass@localhost:3306/example"
```
</TabItem>
<TabItem value="maria">
```shell
atlas migrate apply \
--dir "file://ent/migrate/migrations" \
--url "maria://root:pass@localhost:3306/example"
```
</TabItem>
<TabItem value="postgres">
```shell
atlas migrate apply \
--dir "file://ent/migrate/migrations" \
--url "postgres://postgres:pass@localhost:5432/database?search_path=public&sslmode=disable"
```
</TabItem>
<TabItem value="sqlite">
```shell
atlas migrate apply \
--dir "file://ent/migrate/migrations" \
--url "sqlite://file.db?_fk=1"
```
</TabItem>
</Tabs>

52
doc/md/components/_atlas_migrate_diff.mdx Normal file
View File

@@ -0,0 +1,52 @@
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs
defaultValue="mysql"
values={[
{label: 'MySQL', value: 'mysql'},
{label: 'MariaDB', value: 'maria'},
{label: 'PostgreSQL', value: 'postgres'},
{label: 'SQLite', value: 'sqlite'},
]}>
<TabItem value="mysql">
```shell
atlas migrate diff migration_name \
--dir "file://ent/migrate/migrations" \
--to "ent://ent/schema" \
--dev-url "docker://mysql/8/ent"
```
</TabItem>
<TabItem value="maria">
```shell
atlas migrate diff migration_name \
--dir "file://ent/migrate/migrations" \
--to "ent://ent/schema" \
--dev-url "docker://mariadb/latest/test"
```
</TabItem>
<TabItem value="postgres">
```shell
atlas migrate diff migration_name \
--dir "file://ent/migrate/migrations" \
--to "ent://ent/schema" \
--dev-url "docker://postgres/15/test?search_path=public"
```
</TabItem>
<TabItem value="sqlite">
```shell
atlas migrate diff migration_name \
--dir "file://ent/migrate/migrations" \
--to "ent://ent/schema" \
--dev-url "sqlite://file?mode=memory&_fk=1"
```
</TabItem>
</Tabs>

61
doc/md/components/_installation_instructions.mdx Normal file
View File

@@ -0,0 +1,61 @@
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
To install the latest release of Atlas, simply run one of the following commands in your terminal, or check out the
[Atlas website](https://atlasgo.io/getting-started#installation):
<Tabs
defaultValue="apple-intel-plain+linux"
values={[
{label: 'macOS + Linux', value: 'apple-intel-plain+linux'},
{label: 'Homebrew', value: 'apple-intel-brew'},
{label: 'Go', value: 'go'},
{label: 'Docker', value: 'docker'},
{label: 'Windows', value: 'windows'},
]}>
<TabItem value="apple-intel-plain+linux">
```shell
curl -sSf https://atlasgo.sh | sh
```
</TabItem>
<TabItem value="apple-intel-brew">
```shell
brew install ariga/tap/atlas
```
</TabItem>
<TabItem value="go">
```shell
go install ariga.io/atlas/cmd/atlas@master
```
</TabItem>
<TabItem value="docker">
```shell
docker pull arigaio/atlas
docker run --rm arigaio/atlas --help
```
If the container needs access to the host network or a local directory, use the `--net=host` flag and mount the desired
directory:
```shell
docker run --rm --net=host \
-v $(pwd)/migrations:/migrations \
arigaio/atlas migrate apply
--url "mysql://root:pass@:3306/test"
```
</TabItem>
<TabItem value="windows">
Download the [latest release](https://release.ariga.io/atlas/atlas-windows-amd64-latest.exe) and
move the atlas binary to a file location on your system PATH.
</TabItem>
</Tabs>

40
doc/md/getting-started.mdx
View File

@@ -6,6 +6,8 @@ sidebar_label: Quick Introduction
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import AtlasMigrateDiff from './components/_atlas_migrate_diff.mdx';
import AtlasMigrateApply from './components/_atlas_migrate_apply.mdx';
**ent** is a simple, yet powerful entity framework for Go, that makes it easy to build
and maintain applications with large data-models and sticks with the following principles:
@@ -649,6 +651,44 @@ Now when we have a graph with data, we can run a few queries on it:
}
```
## Schema Migration
Ent provides two approaches for running schema migrations: [Automatic Migrations](/docs/migrate) and
[Versioned migrations](/docs/versioned-migrations). Here is a brief overview of each approach:
### Automatic Migrations
With Automatic Migrations, users can use the following API to keep the database schema aligned with the schema objects
defined in the generated SQL schema `ent/migrate/schema.go`:
```go
if err := client.Schema.Create(ctx); err != nil {
log.Fatalf("failed creating schema resources: %v", err)
}
```
This approach is mostly useful for prototyping, development, or testing. Therefore, it is recommended to use the
_Versioned Migration_ approach for mission-critical production environments. By using versioned migrations, users know
beforehand what changes are being applied to their database, and can easily tune them depending on their needs.
Read more about this approach in the [Automatic Migration](/docs/migrate) documentation.
### Versioned Migrations
Unlike _Automatic Migrations_, the _Version Migrations_ approach uses Atlas to automatically generate a set of migration
files containing the necessary SQL statements to migrate the database. These files can be edited to meet specific needs
and applied using existing migration tools like Atlas, golang-migrate, Flyway, and Liquibase. The API for this approach
involves two primary steps.
#### Generating migrations
<AtlasMigrateDiff/>
#### Applying migrations
<AtlasMigrateApply/>
Read more about this approach in the [Versioned Migrations](/docs/versioned-migrations) documentation.
## Full Example
The full example exists in [GitHub](https://github.com/ent/ent/tree/master/examples/start).

196
doc/md/versioned-migrations.mdx
View File

@@ -5,13 +5,141 @@ title: Versioned Migrations
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import InstallationInstructions from './components/_installation_instructions.mdx';
import AtlasMigrateDiff from './components/_atlas_migrate_diff.mdx';
import AtlasMigrateApply from './components/_atlas_migrate_apply.mdx';
## Quick Guide
Here are a few quick steps that explain how to auto-generate and execute migration files against a database. For
a more in-depth explanation, continue reading the [next section](#in-depth-guide).
### Generating migrations
<InstallationInstructions />
Then, run the following command to automatically generate migration files for your Ent schema:
<AtlasMigrateDiff/>
:::info The role of the [dev database](https://atlasgo.io/concepts/dev-database)
Atlas loads the **current state** by executing the SQL files stored in the migration directory onto the provided
[dev database](https://atlasgo.io/concepts/dev-database). It then compares this state against the **desired state**
defined by the `ent/schema` package and writes a migration plan for moving from the current state to the desired state.
:::
### Applying migrations
<AtlasMigrateApply/>
To apply the pending migration files onto the database, run the following command:
<Tabs
defaultValue="mysql"
values={[
{label: 'MySQL', value: 'mysql'},
{label: 'MariaDB', value: 'maria'},
{label: 'PostgreSQL', value: 'postgres'},
{label: 'SQLite', value: 'sqlite'},
]}>
<TabItem value="mysql">
```shell
atlas migrate apply \
--dir "file://ent/migrate/migrations" \
--url "mysql://root:pass@localhost:3306/example"
```
</TabItem>
<TabItem value="maria">
```shell
atlas migrate apply \
--dir "file://ent/migrate/migrations" \
--url "maria://root:pass@localhost:3306/example"
```
</TabItem>
<TabItem value="postgres">
```shell
atlas migrate apply \
--dir "file://ent/migrate/migrations" \
--url "postgres://postgres:pass@localhost:5432/database?search_path=public&sslmode=disable"
```
</TabItem>
<TabItem value="sqlite">
```shell
atlas migrate apply \
--dir "file://ent/migrate/migrations" \
--url "sqlite://file.db?_fk=1"
```
</TabItem>
</Tabs>
For more information head over to the [Atlas documentation](https://atlasgo.io/versioned/apply).
### Migration status
Use the following command to get detailed information about the migration status of the connected database:
<Tabs
defaultValue="mysql"
values={[
{label: 'MySQL', value: 'mysql'},
{label: 'MariaDB', value: 'maria'},
{label: 'PostgreSQL', value: 'postgres'},
{label: 'SQLite', value: 'sqlite'},
]}>
<TabItem value="mysql">
```shell
atlas migrate status \
--dir "file://ent/migrate/migrations" \
--url "mysql://root:pass@localhost:3306/example"
```
</TabItem>
<TabItem value="maria">
```shell
atlas migrate status \
--dir "file://ent/migrate/migrations" \
--url "maria://root:pass@localhost:3306/example"
```
</TabItem>
<TabItem value="postgres">
```shell
atlas migrate status \
--dir "file://ent/migrate/migrations" \
--url "postgres://postgres:pass@localhost:5432/database?search_path=public&sslmode=disable"
```
</TabItem>
<TabItem value="sqlite">
```shell
atlas migrate status \
--dir "file://ent/migrate/migrations" \
--url "sqlite://file.db?_fk=1"
```
</TabItem>
</Tabs>
## In Depth Guide
If you are using the [Atlas](https://github.com/ariga/atlas) migration engine, you are able to use the versioned
migration workflow. Instead of applying the computed changes directly to the database, Atlas generates a set
of migration files containing the necessary SQL statements to migrate the database. These files can then be edited to
your needs and be applied by many existing migration tools, such as golang-migrate, Flyway, and Liquibase.
## Generating Versioned Migration Files
### Generating Versioned Migration Files
As mentioned above, versioned migrations only work if the new [Atlas](https://atlasgo.io) based migration engine is
used. Migration files are generated by computing the difference between two **states**. We call the state reflected by
@@ -468,68 +596,10 @@ Let's run `atlas migrate lint` with the necessary parameters to run migration li
#### Install Atlas:
To install the latest release of Atlas, simply run one of the following in your terminal, or check out the
[Atlas website](https://atlasgo.io/getting-started#installation):
<Tabs
defaultValue="apple-intel-plain+linux"
values={[
{label: 'macOS + Linux', value: 'apple-intel-plain+linux'},
{label: 'Homebrew', value: 'apple-intel-brew'},
{label: 'Go', value: 'go'},
{label: 'Docker', value: 'docker'},
{label: 'Windows', value: 'windows'},
]}>
<TabItem value="apple-intel-plain+linux">
```shell
curl -sSf https://atlasgo.sh | sh
```
</TabItem>
<TabItem value="apple-intel-brew">
```shell
brew install ariga/tap/atlas
```
</TabItem>
<TabItem value="go">
```shell
go install ariga.io/atlas/cmd/atlas@master
```
</TabItem>
<TabItem value="docker">
```shell
docker pull arigaio/atlas
docker run --rm arigaio/atlas --help
```
If the container needs access to the host network or a local directory, use the `--net=host` flag and mount the desired
directory:
```shell
docker run --rm --net=host \
-v $(pwd)/migrations:/migrations \
arigaio/atlas migrate apply
--url "mysql://root:pass@:3306/test"
```
</TabItem>
<TabItem value="windows">
Download the [latest release](https://release.ariga.io/atlas/atlas-windows-amd64-latest.exe) and
move the atlas binary to a file location on your system PATH.
</TabItem>
</Tabs>
<InstallationInstructions />
#### Run the `atlas migrate lint` command:
<Tabs
defaultValue="mysql"
values={[
@@ -593,7 +663,7 @@ An output of such a run might look as follows:
```
### A Word on Global Unique IDs
#### A Word on Global Unique IDs
**This section only applies to MySQL users using the [global unique id](migrate.md/#universal-ids) feature.**
@@ -649,7 +719,7 @@ values. Since MySQL 8 the counter is no longer only stored in memory, meaning su
longer needed after the first one.
:::
## Apply Migrations
### Apply Migration Files
Ent recommends to use the Atlas CLI to apply the generated migration files onto the database. If you want to use any
other migration management tool, Ent has support for generating migrations for several of them out of the box.
@@ -660,7 +730,7 @@ atlas migrate apply \
--url mysql://root:pass@localhost:3306/ent
```
For more information head over the the [Atlas documentation](https://atlasgo.io/versioned/apply).
For more information head over to the [Atlas documentation](https://atlasgo.io/versioned/apply).
:::info

9
examples/start/README.md
View File

@@ -7,3 +7,12 @@ The example from the getting-started page in https://entgo.io.
```console
go generate ./...
```
### Generate Migration Files
```console
atlas migrate diff migration_name \
--dir "file://ent/migrate/migrations" \
--to "ent://ent/schema" \
--dev-url "sqlite://file?mode=memory&_fk=1"
```

8
examples/start/ent/migrate/migrations/20230219130733_initial.sql Normal file
View File

@@ -0,0 +1,8 @@
-- create "cars" table
CREATE TABLE `cars` (`id` integer NOT NULL PRIMARY KEY AUTOINCREMENT, `model` text NOT NULL, `registered_at` datetime NOT NULL, `user_cars` integer NULL, CONSTRAINT `cars_users_cars` FOREIGN KEY (`user_cars`) REFERENCES `users` (`id`) ON DELETE SET NULL);
-- create "groups" table
CREATE TABLE `groups` (`id` integer NOT NULL PRIMARY KEY AUTOINCREMENT, `name` text NOT NULL);
-- create "users" table
CREATE TABLE `users` (`id` integer NOT NULL PRIMARY KEY AUTOINCREMENT, `age` integer NOT NULL, `name` text NOT NULL DEFAULT 'unknown');
-- create "group_users" table
CREATE TABLE `group_users` (`group_id` integer NOT NULL, `user_id` integer NOT NULL, PRIMARY KEY (`group_id`, `user_id`), CONSTRAINT `group_users_group_id` FOREIGN KEY (`group_id`) REFERENCES `groups` (`id`) ON DELETE CASCADE, CONSTRAINT `group_users_user_id` FOREIGN KEY (`user_id`) REFERENCES `users` (`id`) ON DELETE CASCADE);

2
examples/start/ent/migrate/migrations/atlas.sum Normal file
View File

@@ -0,0 +1,2 @@
h1:4iQfXr2Q63Rz4pEP+SpFphafB7v1gGsWGrLu0p+euDc=
20230219130733_initial.sql h1:3BEmiXtBTmQSDSmfQ4kMr+Y1nUsRRSlZCRknB0PC/MQ=