From c460ae7459b1648c0b0ea11cdbc933e976d22ddf Mon Sep 17 00:00:00 2001 From: Joakim Carlstein Date: Mon, 18 Dec 2023 10:04:06 +0100 Subject: [PATCH] docs: split the getting started guide into two separate pages in the "introduction" section --- .editorconfig | 2 +- docs/astro.config.mjs | 13 +++++- docs/src/content/docs/index.mdx | 24 ++++++----- .../quick-start.mdx} | 43 ++++++++----------- .../src/content/docs/intro/whats-emigrate.mdx | 17 ++++++++ 5 files changed, 60 insertions(+), 39 deletions(-) rename docs/src/content/docs/{getting-started.mdx => intro/quick-start.mdx} (60%) create mode 100644 docs/src/content/docs/intro/whats-emigrate.mdx diff --git a/.editorconfig b/.editorconfig index 4d5114b..07daa84 100644 --- a/.editorconfig +++ b/.editorconfig @@ -5,7 +5,7 @@ end_of_line = lf insert_final_newline = true trim_trailing_whitespace = true -[*.md] +[*.{md,mdx}] trim_trailing_whitespace = false [*.{ts,js,tsx,json,yml}] diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index ea22a06..c91251a 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -14,8 +14,17 @@ export default defineConfig({ }, sidebar: [ { - label: 'Getting Started', - link: '/getting-started/', + label: 'Introduction', + items: [ + { + label: "What's Emigrate?", + link: '/intro/whats-emigrate/', + }, + { + label: 'Quick Start', + link: '/intro/quick-start/', + }, + ], }, { label: 'Plugins', diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index fc43de1..7f16846 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -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.
Emigrate is modern, flexible, scalable, and easy to use. + tagline: Adapt any and all of your databases to new business needs.
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 - - Edit `src/content/docs/index.mdx` to see this page change. + + Emigrate is a database agnostic migration tool.
+ You are in full control over what your migrations do. - - Add Markdown or MDX files to `src/content/docs` to create new pages. + + Migrate many databases from one repository or many repositories to one database. There's no need to synchronize deployments. - - Edit your `sidebar` and other config in `astro.config.mjs`. + + 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. - - Learn more in [the Starlight Docs](https://starlight.astro.build/). + + Emigrate is designed to be flexible and customizable to suite any environment and setup using its [plugin system](/plugins/). diff --git a/docs/src/content/docs/getting-started.mdx b/docs/src/content/docs/intro/quick-start.mdx similarity index 60% rename from docs/src/content/docs/getting-started.mdx rename to docs/src/content/docs/intro/quick-start.mdx index 8f44c5d..8b17463 100644 --- a/docs/src/content/docs/getting-started.mdx +++ b/docs/src/content/docs/intro/quick-start.mdx @@ -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. ::: + + ### Install the Emigrate CLI @@ -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. ::: diff --git a/docs/src/content/docs/intro/whats-emigrate.mdx b/docs/src/content/docs/intro/whats-emigrate.mdx new file mode 100644 index 0000000..4697e1c --- /dev/null +++ b/docs/src/content/docs/intro/whats-emigrate.mdx @@ -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. +:::