Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
34 changes: 34 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Contributing

The library lives in [`packages/drizzle-pg-extras`](packages/drizzle-pg-extras). The repository root holds the workspace, the toolchain and the release configuration.

## Setup

The toolchain is pinned in `flake.nix`. With Nix installed:

```sh
nix develop
pnpm install
```

## Checks

```sh
pnpm test
pnpm typecheck
pnpm lint
pnpm format:check
```

Unit tests cover SQL generation and the snapshot diff, including comments, trigger rules, partition bounds and hypertable SQL.

The integration tests run against real servers and are skipped unless their URL is set:

- `POSTGRES_URL` points the Postgres tests at a server. One runs `drizzle-kit migrate`, checks that the trigger fires, and checks the comments on the table, column, enum, view, function, trigger, index, constraint and extension. Another checks a deferred constraint trigger, transition tables, `INSTEAD OF` on a view, `UPDATE OF` / `WHEN` and `DISABLE TRIGGER`. The partition test checks range, list and hash routing, attach, the empty-table guard and the down file.
- `TIMESCALE_URL` points the Timescale test at a server with the extension. It checks `create_hypertable`, compression, both policies, a second generate that changes the chunk interval, the down file, and that `drizzle-kit generate` reports no schema changes.

CI runs the Postgres tests on PostgreSQL 16 and the Timescale test in its own job on `timescale/timescaledb:2.32.1-pg16`.

## Changes and releases

Each change to the package carries a changeset intent in [`.changeset/`](.changeset/README.md). Pull requests merge through the merge queue once CI is green and the change is approved. The Release workflow turns pending intents into a version pull request, writes `CHANGELOG.md`, tags the release and publishes to npm through trusted publishing, with no npm token stored in the repository.
78 changes: 78 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
# drizzle-pg-extras

Declare the Postgres objects Drizzle can't model yet, next to your Drizzle tables, and get ordinary SQL migration files for them: functions, triggers, comments, extensions, partitioned tables and TimescaleDB hypertables.

`drizzle-kit migrate` applies those files like any other migration. Nothing in Drizzle is patched, so if Drizzle later learns to generate one of these objects itself, the SQL you already committed stays valid.

## Example

A TimescaleDB hypertable with compression and retention, declared in the same schema file as the table:

```ts
import { hypertable, pgExtension } from '@systemfsoftware/drizzle-pg-extras'
import { integer, pgTable, primaryKey, text, timestamp } from 'drizzle-orm/pg-core'

export const timescale = pgExtension('timescaledb')

export const metrics = pgTable('metrics', {
time: timestamp('time', { withTimezone: true }).notNull(),
deviceId: text('device_id').notNull(),
value: integer('value').notNull(),
}, (t) => [primaryKey({ columns: [t.time, t.deviceId] })])

export const metricsHypertable = hypertable(metrics, {
timeColumn: metrics.time,
chunkTimeInterval: '1 day',
compression: { segmentBy: [metrics.deviceId] },
compressionPolicy: { compressAfter: '7 days' },
retention: { dropAfter: '6 months' },
})
```

```sh
drizzle-kit generate && drizzle-pg-extras generate && drizzle-kit migrate
```

The first `generate` writes a migration with `CREATE EXTENSION`, `create_hypertable` and the policy calls. The next one writes nothing until a declaration changes, and then only the difference, with a matching down file.

## Install

```sh
npm install @systemfsoftware/drizzle-pg-extras
```

It needs `drizzle-orm` 0.36.4 or newer, including 1.0, and Node.js 18 or newer. `drizzle-kit` 0.31 or 1.0 applies the migrations. Add the CLI to your scripts and run `check` in CI, where it exits 1 when a declaration changed and no migration was written:

```json
{
"scripts": {
"db:generate": "drizzle-kit generate && drizzle-pg-extras generate",
"db:check": "drizzle-pg-extras check",
"db:migrate": "drizzle-kit migrate"
}
}
```

## What it covers

| Object | Drizzle request | Docs |
| ---------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Functions and triggers | [drizzle-orm#843](https://github.com/drizzle-team/drizzle-orm/issues/843) | [Triggers](packages/drizzle-pg-extras/README.md#triggers) |
| `COMMENT ON` | [drizzle-orm#886](https://github.com/drizzle-team/drizzle-orm/issues/886) | [Programmatic API](packages/drizzle-pg-extras/README.md#programmatic-api) |
| Extensions | [drizzle-orm#2124](https://github.com/drizzle-team/drizzle-orm/issues/2124) | [Install](packages/drizzle-pg-extras/README.md#install) |
| Partitioned tables | [drizzle-orm#2854](https://github.com/drizzle-team/drizzle-orm/issues/2854) | [Partitioning](packages/drizzle-pg-extras/README.md#partitioning) |
| TimescaleDB | [drizzle-orm#2962](https://github.com/drizzle-team/drizzle-orm/issues/2962) | [TimescaleDB](packages/drizzle-pg-extras/README.md#timescaledb) |

The [package README](packages/drizzle-pg-extras/README.md) is the full reference: the files `generate` writes for drizzle-kit 0.31 and 1.0, the limits of each object, `drizzle-kit push`, and what is not supported yet.

## Compatibility

Tested with drizzle-orm 0.45 and 1.0.0-rc.5, drizzle-kit 0.31 and 1.0.0-rc.5, PostgreSQL 16 (14 or newer is required), and TimescaleDB 2.32 on PostgreSQL 16. CI runs the integration tests against real Postgres and TimescaleDB servers.

## Contributing

Development setup, tests and releases: [CONTRIBUTING.md](CONTRIBUTING.md).

## License

[MIT](packages/drizzle-pg-extras/LICENSE)
12 changes: 0 additions & 12 deletions packages/drizzle-pg-extras/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -464,18 +464,6 @@ drizzle-pg-extras generate [--config drizzle.config.ts] [--name touch_updated_at
drizzle-pg-extras check [--config drizzle.config.ts]
```

## Development

```sh
pnpm install
pnpm test
pnpm typecheck
pnpm lint
pnpm format:check
```

Unit tests cover SQL generation and the snapshot diff, including comments, trigger rules, partition bounds, and hypertable SQL. `POSTGRES_URL` points the Postgres integration tests at a real server. One runs `drizzle-kit migrate`, checks that the trigger fires, and that comments on the table, column, enum, view, function, trigger, index, constraint, and extension exist. Another checks a deferred constraint trigger, transition tables, `INSTEAD OF` on a view, `UPDATE OF` / `WHEN`, and `DISABLE TRIGGER`. The partition test checks range, list, and hash routing, attach, the empty-table guard, and the down file. `TIMESCALE_URL` points the Timescale test at a server with the extension. It checks `create_hypertable`, compression, both policies, a second generate that changes the chunk interval, the down file, and that `drizzle-kit generate` reports no schema changes. CI keeps the Postgres 16 job as it was and runs the Timescale test in a separate job on `timescale/timescaledb:2.32.1-pg16`.

## License

MIT