114 lines
2.8 KiB
Markdown
114 lines
2.8 KiB
Markdown
---
|
|
title: Migrations
|
|
---
|
|
|
|
import Tabs from '@theme/Tabs';
|
|
import TabItem from '@theme/TabItem';
|
|
|
|
This page covers migration behavior for both database schema and storage data in OpenReader WebUI.
|
|
|
|
## Startup migration behavior
|
|
|
|
By default, the shared entrypoint runs migrations automatically before app startup in:
|
|
|
|
- Docker container startup
|
|
- `pnpm dev`
|
|
- `pnpm start`
|
|
|
|
Startup migration phases:
|
|
|
|
- DB schema migrations (`pnpm migrate`)
|
|
- Storage/data migration (`pnpm migrate-fs`) for legacy filesystem content into S3 + DB rows
|
|
|
|
:::info
|
|
In most setups, you do not need to run migration commands manually because startup handles this automatically.
|
|
:::
|
|
|
|
To skip automatic startup migrations:
|
|
|
|
- Set `RUN_DRIZZLE_MIGRATIONS=false`
|
|
- Set `RUN_FS_MIGRATIONS=false`
|
|
|
|
:::warning
|
|
If you disable startup migrations, ensure your deployment process runs migrations before serving traffic.
|
|
:::
|
|
|
|
## Apply migrations
|
|
|
|
In most cases, you do not need manual migration commands because startup runs migrations automatically.
|
|
|
|
`pnpm migrate` applies migrations for one database target:
|
|
|
|
- Postgres when `POSTGRES_URL` is set
|
|
- SQLite when `POSTGRES_URL` is unset
|
|
|
|
You can always override the target explicitly with `--config`.
|
|
|
|
<Tabs groupId="apply-migration-commands">
|
|
<TabItem value="project-scripts" label="Project Scripts" default>
|
|
|
|
```bash
|
|
# Run pending migrations for one target:
|
|
# - Postgres if POSTGRES_URL is set
|
|
# - SQLite if POSTGRES_URL is unset
|
|
pnpm migrate
|
|
|
|
# Run storage migration (filesystem -> S3 + DB)
|
|
pnpm migrate-fs
|
|
|
|
# Dry-run storage migration without uploading/deleting
|
|
pnpm migrate-fs:dry-run
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="drizzle-direct" label="Manual Drizzle Cmd">
|
|
|
|
```bash
|
|
# Migrate SQLite
|
|
pnpm exec drizzle-kit migrate --config drizzle.config.sqlite.ts
|
|
|
|
# Migrate Postgres
|
|
pnpm exec drizzle-kit migrate --config drizzle.config.pg.ts
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
## Generate migrations
|
|
|
|
`pnpm generate` creates migration files for both configs in one run:
|
|
|
|
- `drizzle.config.sqlite.ts`
|
|
- `drizzle.config.pg.ts`
|
|
|
|
:::note
|
|
Most users do not need to run `pnpm generate`. Use it when contributing or when you have changed Drizzle schema files and need new migration files.
|
|
:::
|
|
|
|
<Tabs groupId="generate-migration-commands">
|
|
<TabItem value="project-script" label="Project Script" default>
|
|
|
|
```bash
|
|
# Generate migration files for both SQLite and Postgres outputs
|
|
pnpm generate
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="drizzle-direct" label="Manual Drizzle Cmd">
|
|
|
|
```bash
|
|
# Generate SQLite migrations
|
|
pnpm exec drizzle-kit generate --config drizzle.config.sqlite.ts
|
|
|
|
# Generate Postgres migrations
|
|
pnpm exec drizzle-kit generate --config drizzle.config.pg.ts
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
## Related docs
|
|
|
|
- [Database](./database)
|
|
- [Object / Blob Storage](./object-blob-storage)
|
|
- [Migration Environment Variables](../reference/environment-variables#migration-controls)
|