feat(postgres): implement the first version of the PostgreSQL plugin
This commit is contained in:
Joakim Carlstein
parent
3d34b8ba13
commit
17c4723bb8
16 changed files with 761 additions and 18 deletions
|
|
@ -41,22 +41,22 @@ But for now, this is the way to go.
|
|||
|
||||
Emigrate uses a <Link href="/plugins/storage/">storage plugin</Link> to store the migration history.
|
||||
|
||||
Install the plugin you want to use, for example:
|
||||
Install the plugin you want to use, for example the <Link href="/plugins/storage/postgres/">PostgreSQL Storage</Link>:
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="npm">
|
||||
```bash
|
||||
npm install @emigrate/mysql
|
||||
npm install @emigrate/postgres
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem label="pnpm">
|
||||
```bash
|
||||
pnpm add @emigrate/mysql
|
||||
pnpm add @emigrate/postgres
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem label="yarn">
|
||||
```bash
|
||||
yarn add @emigrate/mysql
|
||||
yarn add @emigrate/postgres
|
||||
```
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
|
@ -66,7 +66,7 @@ Install the plugin you want to use, for example:
|
|||
Create a new migration file in your project using:
|
||||
|
||||
```bash title="Create a new migration file"
|
||||
npx emigrate new --plugin mysql create users table
|
||||
npx emigrate new --plugin postgres create users table
|
||||
```
|
||||
|
||||
```txt title="Output"
|
||||
|
|
@ -79,12 +79,12 @@ Emigrate new v0.10.0 /your/project/path
|
|||
```
|
||||
|
||||
:::note
|
||||
The `mysql` plugin is used here to generate a migration file with the `.sql` extension.
|
||||
The `postgres` plugin is used here to generate a migration file with the `.sql` extension.
|
||||
Otherwise the file would have the `.js` extension by default.
|
||||
:::
|
||||
|
||||
:::tip[Did you know?]
|
||||
You can avoid typing `--plugin mysql` by configuring Emigrate using an `emigrate.config.js` file.
|
||||
You can avoid typing `--plugin postgres` by configuring Emigrate using an `emigrate.config.js` file.
|
||||
See <Link href="/reference/configuration/">Configuration</Link> for more information.
|
||||
:::
|
||||
|
||||
|
|
@ -95,10 +95,9 @@ Open the migration file in your editor and fill it with your SQL query:
|
|||
```sql title="migrations/20231215125421364_create_users_table.sql" {2-7}
|
||||
-- Migration: create users table
|
||||
CREATE TABLE users (
|
||||
id INT NOT NULL AUTO_INCREMENT,
|
||||
id SERIAL PRIMARY KEY,
|
||||
name VARCHAR(255) NOT NULL,
|
||||
email VARCHAR(255) NOT NULL,
|
||||
PRIMARY KEY (id)
|
||||
email VARCHAR(255) NOT NULL
|
||||
);
|
||||
```
|
||||
|
||||
|
|
@ -111,7 +110,7 @@ There's no magic about the first line comment as when using Liquibase, it's just
|
|||
To show both pending and already applied migrations (or previously failed), use the `list` command:
|
||||
|
||||
```bash title="Show all migrations"
|
||||
npx emigrate list --storage mysql
|
||||
npx emigrate list --storage postgres
|
||||
```
|
||||
|
||||
```txt title="Example output"
|
||||
|
|
@ -129,7 +128,7 @@ Emigrate list v0.10.0 /your/project/path
|
|||
A good way to test your configuration is to run the migrations in dry mode:
|
||||
|
||||
```bash title="Show pending migrations"
|
||||
npx emigrate up --storage mysql --plugin mysql --dry
|
||||
npx emigrate up --storage postgres --plugin postgres --dry
|
||||
```
|
||||
|
||||
:::note
|
||||
|
|
@ -142,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 <Link href="/plugins/storage/">Storage Plugin</Link>
|
||||
In the example above the `@emigrate/postgres` plugin is used twice, once for the `--storage` option as a <Link href="/plugins/storage/">Storage Plugin</Link>
|
||||
and once for the `--plugin` option as a <Link href="/plugins/loaders/">Loader Plugin</Link> to be able to read `.sql` files.
|
||||
:::
|
||||
|
|
|
|||
|
|
@ -17,6 +17,7 @@ The generator is responsible for generating migration files in a specific format
|
|||
|
||||
<CardGrid>
|
||||
<LinkCard title="JavaScript generator" href="js/" description="A generator that generates .js migration files (using ESM and default export)" />
|
||||
<LinkCard title="PostgreSQL generator" href="postgres/" description="A generator that generates .sql migration files" />
|
||||
<LinkCard title="MySQL generator" href="mysql/" description="A generator that generates .sql migration files" />
|
||||
</CardGrid>
|
||||
|
||||
|
|
|
|||
36
docs/src/content/docs/plugins/generators/postgres.mdx
Normal file
36
docs/src/content/docs/plugins/generators/postgres.mdx
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
---
|
||||
title: "PostgreSQL Generator"
|
||||
---
|
||||
|
||||
import { Tabs, TabItem } from '@astrojs/starlight/components';
|
||||
import Link from '@components/Link.astro';
|
||||
|
||||
The PostgreSQL generator creates new migration files with the `.sql` extension. In the same package you can find the <Link href="/plugins/loaders/postgres/">PostgreSQL Loader</Link> and the <Link href="/plugins/storage/postgres/">PostgreSQL Storage</Link>.
|
||||
|
||||
## Installation
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="npm">
|
||||
```bash
|
||||
npm install @emigrate/postgres
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem label="pnpm">
|
||||
```bash
|
||||
pnpm add @emigrate/postgres
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem label="yarn">
|
||||
```bash
|
||||
yarn add @emigrate/postgres
|
||||
```
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
emigrate new --plugin postgres create some fancy table
|
||||
```
|
||||
|
||||
For more information see <Link href="/commands/new/">the `new` command</Link>'s documentation.
|
||||
|
|
@ -21,7 +21,7 @@ Or set it up in your configuration file, see <Link href="/reference/configuratio
|
|||
|
||||
:::tip[Did you know?]
|
||||
You can specify multiple loader plugins at the same time, which is needed when you mix file types in your migrations folder.
|
||||
For example, you can use the `mysql` loader for `.sql` files and the `typescript` loader for `.ts` files.
|
||||
For example, you can use the `postgres` or `mysql` loader for `.sql` files and the `typescript` loader for `.ts` files.
|
||||
The <Link href="/plugins/loaders/default/">default loader</Link> will be used for all other file types, and doesn't need to be specified.
|
||||
:::
|
||||
|
||||
|
|
@ -29,5 +29,6 @@ The <Link href="/plugins/loaders/default/">default loader</Link> will be used fo
|
|||
|
||||
<CardGrid>
|
||||
<LinkCard title="Default Loader" href="default/" description="The loader responsible for loading .js, .cjs and .mjs files" />
|
||||
<LinkCard title="PostgreSQL Loader" href="postgres/" description="Can load and execute .sql files against a PostgreSQL database" />
|
||||
<LinkCard title="MySQL Loader" href="mysql/" description="Can load and execute .sql files against a MySQL database" />
|
||||
</CardGrid>
|
||||
|
|
|
|||
86
docs/src/content/docs/plugins/loaders/postgres.mdx
Normal file
86
docs/src/content/docs/plugins/loaders/postgres.mdx
Normal file
|
|
@ -0,0 +1,86 @@
|
|||
---
|
||||
title: PostgreSQL Loader Plugin
|
||||
---
|
||||
|
||||
import { Tabs, TabItem } from '@astrojs/starlight/components';
|
||||
import Link from '@components/Link.astro';
|
||||
|
||||
The PostgreSQL loader plugin transforms `.sql` files into JavaScript functions that Emigrate can use to execute the migrations. In the same package you can find the <Link href="/plugins/generators/postgres/">PostgreSQL Generator</Link> and the <Link href="/plugins/storage/postgres/">PostgreSQL Storage</Link>.
|
||||
|
||||
## Installation
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="npm">
|
||||
```bash
|
||||
npm install @emigrate/postgres
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem label="pnpm">
|
||||
```bash
|
||||
pnpm add @emigrate/postgres
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem label="yarn">
|
||||
```bash
|
||||
yarn add @emigrate/postgres
|
||||
```
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Configuration
|
||||
|
||||
The PostgreSQL loader plugin can be configured either using environment variables or by configuring the plugin directly in the <Link href="/reference/configuration/">`emigrate.config.js` file</Link>.
|
||||
|
||||
### Configuration file
|
||||
|
||||
```js title="emigrate.config.js" {1,4-8}
|
||||
import { createPostgresLoader } from '@emigrate/postgres';
|
||||
|
||||
export default {
|
||||
plugins: [
|
||||
createPostgresLoader({
|
||||
connection: { ... },
|
||||
}),
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
##### `connection` (required)
|
||||
|
||||
**type:** `object | string`
|
||||
|
||||
The connection options to use for connecting to the PostgreSQL database when the SQL statements from the migration files are executed. This can either be a connection URI or an object with connection options.
|
||||
For a list of supported connection options, see the [postgres documentation](https://github.com/porsager/postgres#connection).
|
||||
|
||||
### Environment variables
|
||||
|
||||
The following environment variables are supported:
|
||||
|
||||
| Variable | Description | Default |
|
||||
| ------------------- | ----------------------------------------------------------------------------------------------------------- | ------------- |
|
||||
| `POSTGRES_URL` | The full URI for connecting to a PostgreSQL database, e.g: `"postgres://user:pass@127.0.0.1:3306/database"` | |
|
||||
| `POSTGRES_HOST` | The host on which the PostgreSQL server instance is running | `"localhost"` |
|
||||
| `POSTGRES_USER` | The PostgreSQL user account to use for the authentication | |
|
||||
| `POSTGRES_PASSWORD` | The PostgreSQL user password to use for the authentication | |
|
||||
| `POSTGRES_PORT` | The network port on which the PostgreSQL server is listening | `5432` |
|
||||
| `POSTGRES_DB` | The PostgreSQL database to use for the connection | |
|
||||
|
||||
:::note
|
||||
The `POSTGRES_URL` environment variable takes precedence over the other environment variables. If `POSTGRES_URL` is set, the other environment variables are ignored.
|
||||
:::
|
||||
|
||||
The environment variables are used when the plugin is used using the `--plugin` command line option:
|
||||
|
||||
```bash
|
||||
npx emigrate list --plugin postgres
|
||||
```
|
||||
|
||||
Or when specifying the plugin in the <Link href="/reference/configuration/">`emigrate.config.js` file</Link> as a string:
|
||||
|
||||
```js title="emigrate.config.js" {2}
|
||||
export default {
|
||||
plugins: ['postgres'],
|
||||
};
|
||||
```
|
||||
|
|
@ -13,7 +13,7 @@ Usually you'll want to store the migration history in the same database as the o
|
|||
You can specify a storage plugin via the `--storage` (or `-s` for short) option:
|
||||
|
||||
```bash
|
||||
npx emigrate list --storage mysql
|
||||
npx emigrate list --storage postgres
|
||||
```
|
||||
|
||||
Or set it up in your configuration file, see <Link href="/reference/configuration/#storage">Storage configuration</Link> for more information.
|
||||
|
|
@ -22,6 +22,7 @@ Or set it up in your configuration file, see <Link href="/reference/configuratio
|
|||
|
||||
<CardGrid>
|
||||
<LinkCard title="File System" href="file-system/" description="The most basic storage plugin - for simple setups" />
|
||||
<LinkCard title="PostgreSQL" href="postgres/" description="A storage plugin that uses a PostgreSQL database for storing the migration history state" />
|
||||
<LinkCard title="MySQL" href="mysql/" description="A storage plugin that uses a MySQL database for storing the migration history state" />
|
||||
</CardGrid>
|
||||
|
||||
|
|
|
|||
93
docs/src/content/docs/plugins/storage/postgres.mdx
Normal file
93
docs/src/content/docs/plugins/storage/postgres.mdx
Normal file
|
|
@ -0,0 +1,93 @@
|
|||
---
|
||||
title: PostgreSQL Storage
|
||||
---
|
||||
|
||||
import { Tabs, TabItem } from '@astrojs/starlight/components';
|
||||
import Link from '@components/Link.astro';
|
||||
|
||||
The PostgreSQL storage plugin uses a PostgreSQL database to store the migration history (*duh*). In the same package you can find the <Link href="/plugins/loaders/postgres/">PostgreSQL Loader</Link> and the <Link href="/plugins/generators/postgres/">PostgreSQL Generator</Link>.
|
||||
|
||||
## Installation
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="npm">
|
||||
```bash
|
||||
npm install @emigrate/postgres
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem label="pnpm">
|
||||
```bash
|
||||
pnpm add @emigrate/postgres
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem label="yarn">
|
||||
```bash
|
||||
yarn add @emigrate/postgres
|
||||
```
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Configuration
|
||||
|
||||
The PostgreSQL storage can be configured either using environment variables or by configuring the plugin directly in the <Link href="/reference/configuration/">`emigrate.config.js` file</Link>.
|
||||
|
||||
### Configuration file
|
||||
|
||||
```js title="emigrate.config.js" {1,4-7}
|
||||
import { createPostgresStorage } from '@emigrate/postgres';
|
||||
|
||||
export default {
|
||||
storage: createPostgresStorage({
|
||||
table: 'migrations',
|
||||
connection: { ... },
|
||||
}),
|
||||
};
|
||||
```
|
||||
|
||||
#### Options
|
||||
|
||||
##### `table`
|
||||
|
||||
**type:** `string`
|
||||
**default:** `"migrations"`
|
||||
|
||||
The name of the table to use for storing the migrations.
|
||||
|
||||
##### `connection` (required)
|
||||
|
||||
**type:** `object | string`
|
||||
|
||||
The connection options to use for connecting to the PostgreSQL database. This can either be a connection URI or an object with connection options.
|
||||
For a list of supported connection options, see the [postgres documentation](https://github.com/porsager/postgres#connection).
|
||||
|
||||
### Environment variables
|
||||
|
||||
The following environment variables are supported:
|
||||
|
||||
| Variable | Description | Default |
|
||||
| ------------------- | ----------------------------------------------------------------------------------------------------------- | -------------- |
|
||||
| `POSTGRES_TABLE` | The name of the table to use for storing the migrations | `"migrations"` |
|
||||
| `POSTGRES_URL` | The full URI for connecting to a PostgreSQL database, e.g: `"postgres://user:pass@127.0.0.1:3306/database"` | |
|
||||
| `POSTGRES_HOST` | The host on which the PostgreSQL server instance is running | `"localhost"` |
|
||||
| `POSTGRES_USER` | The PostgreSQL user account to use for the authentication | |
|
||||
| `POSTGRES_PASSWORD` | The PostgreSQL user password to use for the authentication | |
|
||||
| `POSTGRES_PORT` | The network port on which the PostgreSQL server is listening | `5432` |
|
||||
| `POSTGRES_DB` | The PostgreSQL database to use for the connection | |
|
||||
|
||||
:::note
|
||||
The `POSTGRES_URL` environment variable takes precedence over the other environment variables. If `POSTGRES_URL` is set, the other environment variables are ignored, except for `POSTGRES_TABLE`.
|
||||
:::
|
||||
|
||||
The environment variables are used when the storage plugin is used using the `--storage` command line option:
|
||||
|
||||
```bash
|
||||
npx emigrate list --storage postgres
|
||||
```
|
||||
|
||||
Or when specifying the storage in the <Link href="/reference/configuration/">`emigrate.config.js` file</Link> as a string:
|
||||
|
||||
```js title="emigrate.config.js" {2}
|
||||
export default {
|
||||
storage: 'postgres',
|
||||
};
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue