diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..49036cf --- /dev/null +++ b/CONTRIBUTING.md @@ -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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..bedbd01 --- /dev/null +++ b/README.md @@ -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) diff --git a/packages/drizzle-pg-extras/README.md b/packages/drizzle-pg-extras/README.md index 38448e4..5bf19d8 100644 --- a/packages/drizzle-pg-extras/README.md +++ b/packages/drizzle-pg-extras/README.md @@ -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