diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index 063a49e..679de7d 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -105,13 +105,17 @@ export default defineConfig({
label: 'Using TypeScript',
link: '/guides/typescript/',
},
+ {
+ label: 'Baseline',
+ link: '/guides/baseline/',
+ },
],
},
{
label: 'Plugins',
items: [
{
- label: 'Introduction',
+ label: 'Plugins Introduction',
link: '/plugins/',
},
{
@@ -119,7 +123,7 @@ export default defineConfig({
collapsed: true,
items: [
{
- label: 'Introduction',
+ label: 'Storage Plugins',
link: '/plugins/storage/',
},
{
@@ -141,7 +145,7 @@ export default defineConfig({
collapsed: true,
items: [
{
- label: 'Introduction',
+ label: 'Loader Plugins',
link: '/plugins/loaders/',
},
{
@@ -163,7 +167,7 @@ export default defineConfig({
collapsed: true,
items: [
{
- label: 'Introduction',
+ label: 'Reporters',
link: '/plugins/reporters/',
},
{
@@ -181,7 +185,7 @@ export default defineConfig({
collapsed: true,
items: [
{
- label: 'Introduction',
+ label: 'Generator Plugins',
link: '/plugins/generators/',
},
{
diff --git a/docs/src/content/docs/commands/up.mdx b/docs/src/content/docs/commands/up.mdx
index 1b6eedc..b3afb2a 100644
--- a/docs/src/content/docs/commands/up.mdx
+++ b/docs/src/content/docs/commands/up.mdx
@@ -151,3 +151,7 @@ Force enable/disable colored output, option is passed to the reporter which shou
Mark the migrations as executed and successful without actually running them,
which is useful if you want to mark migrations as successful after running them manually
+
+:::tip
+See the Baseline guide for example usage of the `--no-execution` option
+:::
diff --git a/docs/src/content/docs/guides/baseline.mdx b/docs/src/content/docs/guides/baseline.mdx
new file mode 100644
index 0000000..2e2df5e
--- /dev/null
+++ b/docs/src/content/docs/guides/baseline.mdx
@@ -0,0 +1,255 @@
+---
+title: Baseline
+description: A guide on how to baseline an existing database at a specific version
+---
+
+import { Tabs, TabItem, LinkCard } from '@astrojs/starlight/components';
+import Link from '@components/Link.astro';
+
+A common scenario is to have an existing database that you want to start managing with Emigrate. This is called baselining.
+
+## Baselining an existing database schema
+
+Let's assume you have a PostgreSQL database with the following schema:
+
+```sql
+CREATE TABLE public.users (
+ id SERIAL PRIMARY KEY,
+ name VARCHAR(255) NOT NULL,
+ email VARCHAR(255) NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE public.posts (
+ id SERIAL PRIMARY KEY,
+ user_id INTEGER NOT NULL REFERENCES public.users(id),
+ title VARCHAR(255) NOT NULL,
+ body TEXT NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+```
+
+
+
+
+
+### Create a baseline migration
+
+You can baseline this database by first creating a baseline migration (here we name it "baseline"):
+
+
+
+ ```bash
+ npx emigrate new --plugin postgres baseline
+ ```
+
+
+ ```bash
+ pnpm emigrate new --plugin postgres baseline
+ ```
+
+
+ ```bash
+ yarn emigrate new --plugin postgres baseline
+ ```
+
+
+ ```bash
+ bunx --bun emigrate new --plugin postgres baseline
+ ```
+
+
+ ```json title="package.json" {3,6}
+ {
+ "scripts": {
+ "emigrate": "emigrate"
+ },
+ "dependencies": {
+ "@emigrate/cli": "*"
+ }
+ }
+ ```
+
+ ```bash
+ deno task emigrate new --plugin postgres baseline
+ ```
+
+
+
+Which will generate an empty migration file in your migration directory:
+
+```sql title="migrations/20240118123456789_baseline.sql"
+-- Migration: baseline
+
+```
+
+You can then add the SQL statements for your database schema to this migration file:
+
+```sql title="migrations/20240118123456789_baseline.sql"
+-- Migration: baseline
+CREATE TABLE public.users (
+ id SERIAL PRIMARY KEY,
+ name VARCHAR(255) NOT NULL,
+ email VARCHAR(255) NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE public.posts (
+ id SERIAL PRIMARY KEY,
+ user_id INTEGER NOT NULL REFERENCES public.users(id),
+ title VARCHAR(255) NOT NULL,
+ body TEXT NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+```
+
+### Log the baseline migration
+
+For new environments this baseline migration will automatically be run when you run `emigrate up`.
+For any existing environments you will need to run `emigrate up` with the `--no-execution` flag to prevent the migration from being executed and only log the migration:
+
+
+
+ ```bash
+ npx emigrate up --no-execution
+ ```
+
+
+ ```bash
+ pnpm emigrate up --no-execution
+ ```
+
+
+ ```bash
+ yarn emigrate up --no-execution
+ ```
+
+
+ ```bash
+ bunx --bun emigrate up --no-execution
+ ```
+
+
+ ```json title="package.json" {3,6}
+ {
+ "scripts": {
+ "emigrate": "emigrate"
+ },
+ "dependencies": {
+ "@emigrate/cli": "*"
+ }
+ }
+ ```
+
+ ```bash
+ deno task emigrate up --no-execution
+ ```
+
+
+
+In case you have already added more migration files to your migration directory you can limit the "up" command to just log the baseline migration by specifying the `--to` option:
+
+
+
+ ```bash
+ npx emigrate up --no-execution --to 20240118123456789_baseline.sql
+ ```
+
+
+ ```bash
+ pnpm emigrate up --no-execution --to 20240118123456789_baseline.sql
+ ```
+
+
+ ```bash
+ yarn emigrate up --no-execution --to 20240118123456789_baseline.sql
+ ```
+
+
+ ```bash
+ bunx --bun emigrate up --no-execution --to 20240118123456789_baseline.sql
+ ```
+
+
+ ```json title="package.json" {3,6}
+ {
+ "scripts": {
+ "emigrate": "emigrate"
+ },
+ "dependencies": {
+ "@emigrate/cli": "*"
+ }
+ }
+ ```
+
+ ```bash
+ deno task emigrate up --no-execution --to 20240118123456789_baseline.sql
+ ```
+
+
+
+### Verify the baseline migration status
+
+You can verify the status of the baseline migration by running the `emigrate list` command:
+
+
+
+ ```bash
+ npx emigrate list
+ ```
+
+
+ ```bash
+ pnpm emigrate list
+ ```
+
+
+ ```bash
+ yarn emigrate list
+ ```
+
+
+ ```bash
+ bunx --bun emigrate list
+ ```
+
+
+ ```json title="package.json" {3,6}
+ {
+ "scripts": {
+ "emigrate": "emigrate"
+ },
+ "dependencies": {
+ "@emigrate/cli": "*"
+ }
+ }
+ ```
+
+ ```bash
+ deno task emigrate list
+ ```
+
+
+
+Which should output something like this:
+
+```txt title="emigrate list"
+Emigrate list v0.14.1 /your/project/path
+
+ ✔ migrations/20240118123456789_baseline.sql (done)
+
+ 1 done (1 total)
+```
+
+### Happy migrating!
+
+You can now start adding new migrations to your migration directory and run `emigrate up` to apply them to your database.
+Which should be part of your CD pipeline to ensure that your database schema is always up to date in each environment.
diff --git a/docs/src/content/docs/intro/quick-start.mdx b/docs/src/content/docs/intro/quick-start.mdx
index 905e078..82a962e 100644
--- a/docs/src/content/docs/intro/quick-start.mdx
+++ b/docs/src/content/docs/intro/quick-start.mdx
@@ -95,6 +95,12 @@ Install the plugin you want to use, for example the
+
Create a new migration file in your project using:
@@ -133,7 +139,7 @@ Create a new migration file in your project using:
-```txt title="Output"
+```txt title="emigrate new"
Emigrate new v0.10.0 /your/project/path
✔ migrations/20231215125421364_create_users_table.sql (done) 3ms
@@ -209,7 +215,7 @@ To show both pending and already applied migrations (or previously failed), use
-```txt title="Example output"
+```txt title="emigrate list"
Emigrate list v0.10.0 /your/project/path
✔ migrations/20231211090830577_another_table.sql (done)