Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat!: database migrations #333

Merged
merged 30 commits into from
Oct 25, 2024
Merged
Changes from 1 commit
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
fb6be5e
feat: include database migrations in build
RihanArfan Oct 21, 2024
326020d
feat: apply migrations in pages ci
RihanArfan Oct 23, 2024
0f0cfa1
Merge branch 'nuxt-hub:main' into feat/migrations
RihanArfan Oct 23, 2024
3c59920
fix: remove calling hooks in non-runtime
RihanArfan Oct 23, 2024
8f22d22
feat: apply migrations in pages ci
RihanArfan Oct 23, 2024
37c1125
refactor: enable usage during dev
RihanArfan Oct 23, 2024
2bfcaae
feat: migrations hook
RihanArfan Oct 23, 2024
ed22ddd
refactor: improve code consistency
RihanArfan Oct 24, 2024
350476a
feat(playground): apply migrations via nuxt hub
RihanArfan Oct 24, 2024
101935b
fix: correctly resolve imports in runtime
RihanArfan Oct 24, 2024
2f7215b
feat: local migrations
RihanArfan Oct 24, 2024
04e78b5
refactor: separate usage of @nuxt/kit & disable migrations during dev…
RihanArfan Oct 24, 2024
9d62b1a
feat: local development migrations
RihanArfan Oct 24, 2024
deec85c
refactor: consistent naming
RihanArfan Oct 24, 2024
537f577
feat: support remote migrations during dev --remote
RihanArfan Oct 24, 2024
1228ad5
feat: log remote env name for self host
RihanArfan Oct 24, 2024
c5819d2
refactor: move logic into runtime
RihanArfan Oct 24, 2024
c9c2377
fix: correctly provide token
RihanArfan Oct 24, 2024
3af9654
chore: message consistency and fix type
RihanArfan Oct 24, 2024
aa3d09f
Merge remote-tracking branch 'upstream/main' into feat/migrations
RihanArfan Oct 24, 2024
6ed8589
docs: migrations docs
RihanArfan Oct 25, 2024
469c005
chore: rename table to _hub_migrations
atinux Oct 25, 2024
d6f7a29
chore: rename hook to database:migrations:done
atinux Oct 25, 2024
50c6052
chore: update
atinux Oct 25, 2024
f2100c2
Merge branch 'main' into feat/migrations
atinux Oct 25, 2024
e0ce88c
docs: update
atinux Oct 25, 2024
d02d1e9
typo
atinux Oct 25, 2024
398851d
chore: og image
atinux Oct 25, 2024
80f8b90
up
atinux Oct 25, 2024
157b1dd
up
atinux Oct 25, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
docs: migrations docs
RihanArfan committed Oct 25, 2024

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
commit 6ed85893e5ff267396a6b98d35a5efc0811063d7
61 changes: 61 additions & 0 deletions docs/content/1.docs/2.features/database.md
Original file line number Diff line number Diff line change
@@ -242,3 +242,64 @@ The methods [`.all()`](#all) and [`.batch()`](#batch) return an object that cont
::callout
Read more on [Cloudflare D1 documentation](https://developers.cloudflare.com/d1/build-databases/query-databases/).
::

## Migrations

Database migrations are a system for managing incremental, version-controlled changes to database schemas that tracks modifications and ensures consistent database evolution across all environments.

### Applying migrations

Database migrations are automatically applied during:
- Deploying via [CLI](/docs/getting-started/deploy#nuxthub-cli) or [Cloudflare Pages CI](/docs/getting-started/deploy#cloudflare-pages-ci) for projects linked to NuxtHub
- Starting the development server `npm run dev [--remote]`
- Locally previewing a build with [nuxthub preview](/changelog/nuxthub-preview)

::callout
Applied migrations are tracked within the `hub_migrations` database table.
::

### Create new migration

You can create a new blank database migration file by running this command.

```bash [Terminal]
npx nuxthub database migrations create <name>
```

::note
The migration name can only include alphanumeric characters and `-`. Spaces are converted into `-`.
::

Migration files are created in the `server/database/migrations/` directory.

### List applied and pending migrations

List migrations which are pending, and which have been applied to local/preview/production.

```bash [Terminal]
npx nuxthub database migrations list [--preview] [--production]
```

By default it will show you applied and pending migrations for the local environment.

### Migrating from Drizzle ORM

NuxtHub will attempt to rerun all migrations within `server/database/migrations/*.sql` since it is unaware they are already applied, as migrations previously applied with Drizzle ORM are stored within the `__drizzle_migrations` table.

Run the command `nuxthub database migrations mark-all-applied` on each environment to mark all existing migration files as applied.

```bash [Terminal]
nuxthub database migrations mark-all-applied --local|preview|production
```

By default it will mark all migrations as applied on the local environment.

::collapsible{name="self-hosting docs"}

If you are [self-hosting](/docs/getting-started/deploy#self-hosted) NuxtHub, set the `NUXT_HUB_PROJECT_SECRET_KEY` environment variable before running the command. <br><br>

```bash [Terminal]
NUXT_HUB_PROJECT_SECRET_KEY=<secret> nuxthub database migrations mark-all-applied --local|preview|production
```

::
20 changes: 6 additions & 14 deletions docs/content/1.docs/3.recipes/1.hooks.md
Original file line number Diff line number Diff line change
@@ -5,26 +5,18 @@ description: Use lifecycle hooks to stay synced with NuxtHub.

## `onHubReady()`

Use `onHubReady()` to ensure the execution of some code once NuxtHub environment bindings are set up.
Use `onHubReady()` to ensure the execution of some code once NuxtHub environment bindings are set up and migrations are applied.

::note
`onHubReady()` is a shortcut using the [`hubHooks`](#hubhooks) object under the hood to listen to the `bindings:ready` event.
`onHubReady()` is a shortcut using the [`hubHooks`](#hubhooks) object under the hood to listen to the `migrations:done` event.
::

This is useful to run database migrations inside your [server/plugins/](https://nuxt.com/docs/guide/directory-structure/server#server-plugins).

```ts [server/plugins/migrations.ts]
export default defineNitroPlugin(() => {
// Only run migrations in development
// Only run in development
if (import.meta.dev) {
onHubReady(async () => {
await hubDatabase().exec(`
CREATE TABLE IF NOT EXISTS todos (
id INTEGER PRIMARY KEY,
title TEXT NOT NULL,
completed INTEGER NOT NULL DEFAULT 0
)
`.replace(/\n/g, ''))
console.log('NuxtHub is ready! 🚀')
})
}
})
@@ -40,12 +32,13 @@ The `hubHooks` object is a collection of hooks that can be used to stay synced w
```ts [Signature]
export interface HubHooks {
'bindings:ready': () => any | void
'migrations:done': () => any | void
}
```

### Usage

You can use the `hubHooks` object to listen to the `bindings:ready` event in your server plugins:
You can use the `hubHooks` object to listen to `HubHooks` events in your server plugins:

```ts [server/plugins/hub.ts]
export default defineNitroPlugin(() => {
@@ -59,4 +52,3 @@ export default defineNitroPlugin(() => {
::note
Note that `hubHooks` is a [hookable](https://hookable.unjs.io) instance.
::

31 changes: 3 additions & 28 deletions docs/content/1.docs/3.recipes/2.drizzle.md
Original file line number Diff line number Diff line change
@@ -92,35 +92,10 @@ When running the `npm run db:generate` command, `drizzle-kit` will generate the

### Migrations

We can create a server plugin to run the migrations in development automatically:

```ts [server/plugins/migrations.ts]
import { consola } from 'consola'
import { migrate } from 'drizzle-orm/d1/migrator'

export default defineNitroPlugin(async () => {
if (!import.meta.dev) return

onHubReady(async () => {
await migrate(useDrizzle(), { migrationsFolder: 'server/database/migrations' })
.then(() => {
consola.success('Database migrations done')
})
.catch((err) => {
consola.error('Database migrations failed', err)
})
})
})
```

::callout
Drizzle will create a `__drizzle_migrations` table in your database to keep track of the applied migrations. It will also run the migrations automatically in development mode.
::

To apply the migrations in staging or production, you can run the server using `npx nuxi dev --remote` command to connect your local server to the remote database, learn more about [remote storage](/docs/getting-started/remote-storage).
Migrations created with `npm run db:generate` are automatically applied during deployment, preview and when starting the development server.

::note
We are planning to update this section to leverage [Nitro Tasks](https://nitro.unjs.io/guide/tasks) instead of a server plugin in the future.
::note{to="/docs/features/database#migrations"}
Learn more about migrations.
::

### `useDrizzle()`
87 changes: 87 additions & 0 deletions docs/content/4.changelog/migrations.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
---
title: Database migrations
description: "Database migrations are now automatically applied during development and deployment."
date: 2024-10-25
image: '/images/changelog/migrations.png'
category: Core
authors:
- name: Rihan Arfan
avatar:
src: https://avatars.githubusercontent.com/u/20425781?v=4
to: https://x.com/RihanArfan
username: RihanArfan
---

::tip
This feature is available on both [free and pro plans](/pricing) and in [`@nuxthub/core >= v0.0.0`](https://github.com/nuxt-hub/core/releases).
::

We are excited to introduce [database migrations](/docs/features/database#migrations) in NuxtHub. Database migration files in `server/database/migrations/*.sql` are now applied automatically when starting the development server, or when deploying a project.

:nuxt-img{src="/images/changelog/migrations.png" alt="NuxtHub migrations" width="915" height="515"}


## Usage

Read the [full documentation](/docs/features/database#migrations) to learn more about migrations.

### Create new migration

You can create a new blank database migration file by running this command.

```bash [Terminal]
npx nuxthub database migrations create <name>
```

Once the migration is created, you can add SQL queries to modify your database, such as to add a new table.

### List applied and pending migrations

You can view all applied and pending migrations for an environment using this command.

```bash [Terminal]
npx nuxthub database migrations list [--preview] [--production]
```

By default it will show you applied and pending migrations for the local environment.

### Apply migrations

Database migrations are automatically applied during:
- Deploying via [CLI](/docs/getting-started/deploy#nuxthub-cli) or [Cloudflare Pages CI](/docs/getting-started/deploy#cloudflare-pages-ci) for projects linked to NuxtHub
- Starting the development server `npm run dev [--remote]`
- Locally previewing a build with [nuxthub preview](/changelog/nuxthub-preview)

## Migration from existing ORM

::important
**If you are using Drizzle ORM** with a Nuxt plugin to automatically apply migrations, follow this migration path.
::

NuxtHub will attempt to rerun all migrations within `server/database/migrations/*.sql` since it is unaware they are already applied, as migrations previously applied with Drizzle ORM are stored within the `__drizzle_migrations` table.

Run the command `nuxthub database migrations mark-all-applied` on each environment to mark all existing migration files as applied.

```bash [Terminal]
nuxthub database migrations mark-all-applied --local|preview|production
```

By default it will mark all migrations as applied on the local environment.

::collapsible{name="self-hosting docs"}

If you are [self-hosting](/docs/getting-started/deploy#self-hosted) NuxtHub, set the `NUXT_HUB_PROJECT_SECRET_KEY` environment variable before running the command. <br><br>

```bash [Terminal]
NUXT_HUB_PROJECT_SECRET_KEY=<secret> nuxthub database migrations mark-all-applied --local|preview|production
```

::

## What are database migrations?

Database migrations are a system for managing incremental, version-controlled changes to database schemas that tracks modifications and ensures consistent database evolution across all environments.

::note
This feature has been implemented in [nuxt-hub/core#333](https://github.com/nuxt-hub/core/pull/333).
::