aboviq/emigrate
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

docs: split the getting started guide into two separate pages in the "introduction" section

Browse source
This commit is contained in:
Joakim Carlstein 2023-12-18 10:04:06 +01:00 • committed by Joakim Carlstein
parent 99d189aeb9
commit c460ae7459
5 changed files with 60 additions and 39 deletions
Download patch file Download diff file Expand all files Collapse all files

24
docs/src/content/docs/index.mdx
View file

@ -3,12 +3,12 @@ title: Effortless database changes with Emigrate
description: Adapt any and all of your databases to your needs at any scale. Modern, flexible, and easy to use.
template: splash
hero:
tagline: Adapt any and all of your databases to new business needs.<br>Emigrate is modern, flexible, scalable, and easy to use.
tagline: Adapt any and all of your databases to new business needs.<br>Emigrate is a modern migration tool that's flexible, scalable, and easy to use.
image:
file: ../../assets/houston.webp
actions:
- text: Quick Start
link: /getting-started/
link: /intro/quick-start/
icon: right-arrow
variant: primary
- text: View on GitHub
@ -18,19 +18,21 @@ hero:
import { Card, CardGrid } from '@astrojs/starlight/components';
## Next steps
## Key features
<CardGrid stagger>
<Card title="Update content" icon="pencil">
Edit `src/content/docs/index.mdx` to see this page change.
<Card title="Migrate any database" icon="bars">
Emigrate is a database agnostic migration tool.<br />
You are in full control over what your migrations do.
</Card>
<Card title="Add new content" icon="add-document">
Add Markdown or MDX files to `src/content/docs` to create new pages.
<Card title="Supports any architecture" icon="random">
Migrate many databases from one repository or many repositories to one database. There's no need to synchronize deployments.
</Card>
<Card title="Configure your site" icon="setting">
Edit your `sidebar` and other config in `astro.config.mjs`.
<Card title="SQL, JavaScript, TypeScript, etc." icon="document">
Write your migration files using the [language of your choice](/plugins/loaders/).
And mix and match them as you need. E.g. `SQL` for database schema changes, and `JavaScript` for data transformation.
</Card>
<Card title="Read the docs" icon="open-book">
Learn more in [the Starlight Docs](https://starlight.astro.build/).
<Card title="Customize to your setup" icon="puzzle">
Emigrate is designed to be flexible and customizable to suite any environment and setup using its [plugin system](/plugins/).
</Card>
</CardGrid>

43
docs/src/content/docs/getting-started.mdx → docs/src/content/docs/intro/quick-start.mdx
View file

@ -1,29 +1,21 @@
---
title: Getting Started
description: How to getting started with Emigrate, the database migration tool
title: Quick Start
description: Get going with Emigrate quickly
---
import { Tabs, TabItem } from '@astrojs/starlight/components';
Emigrate is written in [TypeScript](https://www.typescriptlang.org) and is a database migration tool for any database.
* It's the successor of [klei-migrate](https://github.com/klei/migrate) and is designed to be compatible with [Immigration](https://github.com/blakeembrey/node-immigration) and many of its storage plugins, as well as [Migrate](https://github.com/tj/node-migrate).
* It supports migration files written using [CommonJS or ES Modules out of the box](/loaders/default/), with any of the following extensions: `.js`, `.cjs` or `.mjs`, and supports [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function), [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) or using the [NodeJS Callback Pattern](https://nodejs.org/en/learn/asynchronous-work/javascript-asynchronous-programming-and-callbacks#handling-errors-in-callbacks).
* Other languages can be used by using a [Loader Plugin](/loaders/).
* The migration history can be stored anywhere using a [Storage Plugin](/storage/).
* The output can be customized using [Reporters](/reporters/).
:::tip[Did you know?]
Thanks to [the plugin system](/plugins/) you can even write migrations in plain SQL! So no need for Java-based tools like Liquibase or Flyway.
:::
## Quick Start
import { Tabs, TabItem, LinkCard } from '@astrojs/starlight/components';
:::note
The following guide will be even simpler soon with the release of a initialization command.
But for now, this is the way to go.
:::
<LinkCard
href="/intro/whats-emigrate/"
title="What's Emigrate?"
description="Learn more about Emigrate and what it can do for you."
/>
### Install the Emigrate CLI
<Tabs>
@ -46,10 +38,7 @@ But for now, this is the way to go.
### Pick a storage plugin
Emigrate uses a [storage plugin](/plugins/storage/) to store the migration history. You can use one of the following plugins:
- [MySQL](/plugins/storage/mysql)
- [File System](/plugins/storage/file-system)
Emigrate uses a [storage plugin](/plugins/storage/) to store the migration history.
Install the plugin you want to use, for example:
@ -80,7 +69,7 @@ npx emigrate new --plugin mysql create users table
```
```txt title="Output"
Emigrate new v0.9.0 /your/project/path
Emigrate new v0.10.0 /your/project/path
✔ migrations/20231215125421364_create_users_table.sql (done) 3ms
@ -112,6 +101,10 @@ CREATE TABLE users (
);
```
:::note
There's no magic about the first line comment as when using Liquibase, it's just a comment and can be erased.
:::
### Show migration status
To show both pending and already applied migrations (or previously failed), use the `list` command:
@ -121,7 +114,7 @@ npx emigrate list --storage mysql
```
```txt title="Example output"
Emigrate list v0.9.0 /your/project/path
Emigrate list v0.10.0 /your/project/path
✔ migrations/20231211090830577_another_table.sql (done)
› migrations/20231215125421364_create_users_table.sql (pending)
@ -148,6 +141,6 @@ Be sure to configure the connection correctly and use the `--dry` flag to test y
:::
:::tip[Did you know?]
In the example above the `@emigrate/mysql` plugin is used twice, once for the `--storage` option as a [Storage Plugin](/storage/)
and once for the `--plugin` option as a [Loader Plugin](/loaders/) to be able to read `.sql` files.
In the example above the `@emigrate/mysql` plugin is used twice, once for the `--storage` option as a [Storage Plugin](/plugins/storage/)
and once for the `--plugin` option as a [Loader Plugin](/plugins/loaders/) to be able to read `.sql` files.
:::

17
docs/src/content/docs/intro/whats-emigrate.mdx Normal file
View file

@ -0,0 +1,17 @@
---
title: What's Emigrate?
description: An introduction to Emigrate, the modern database agnostic migration tool.
---
Emigrate is written in [TypeScript](https://www.typescriptlang.org) and is a migration tool for any database or data.
* It's database agnostic - you can use it with any database, or even with non-database data.
* It's the successor of [klei-migrate](https://github.com/klei/migrate) and is designed to be compatible with [Immigration](https://github.com/blakeembrey/node-immigration) and many of its storage plugins, as well as [Migrate](https://github.com/tj/node-migrate).
* It supports migration files written using [CommonJS or ES Modules out of the box](/plugins/loaders/default/), with any of the following extensions: `.js`, `.cjs` or `.mjs`, and supports [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function), [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) or using the [NodeJS Callback Pattern](https://nodejs.org/en/learn/asynchronous-work/javascript-asynchronous-programming-and-callbacks#handling-errors-in-callbacks).
* Other languages can be used by using a [Loader Plugin](/plugins/loaders/).
* The migration history can be stored anywhere using a [Storage Plugin](/plugins/storage/).
* The output can be customized using [Reporters](/plugins/reporters/).
:::tip[Did you know?]
Thanks to [the plugin system](/plugins/) you can even write migrations in plain SQL! So no need for Java-based tools like Liquibase or Flyway.
:::