Merge branch 'main' into devin/1773717246-export-use-migrate-client

Author: NorOldBurden

AGENTS.md

@@ -62,8 +62,83 @@ This guide helps AI agents quickly navigate the Constructive monorepo. Construct
 - Generate types/SDK: `cnc codegen`
 - Export schema SDL: `cnc get-graphql-schema`
 
+## Best Practices
+
+### Environment Configuration
+
+Always use the unified environment configuration system — never read `process.env` directly for config values.
+
+- **PGPM packages** (`pgpm/*`): `import { getEnvOptions } from '@pgpmjs/env'`
+- **GraphQL/Constructive packages** (`graphql/*`, `packages/cli`): `import { getEnvOptions } from '@constructive-io/graphql-env'`
+- **PostgreSQL tools** (`postgres/*`): `import { getPgEnvOptions } from 'pg-env'` or `@pgpmjs/env`
+
+The system provides typed defaults, config file discovery (`pgpm.json`), env var parsing, and a clean merge hierarchy: **defaults → config file → env vars → runtime overrides**.
+
+```typescript
+// GOOD
+import { getEnvOptions } from '@pgpmjs/env';
+const opts = getEnvOptions({ pg: { database: 'mydb' } });
+
+// BAD — scattered, untyped, no defaults
+const host = process.env.PGHOST || 'localhost';
+const port = parseInt(process.env.PGPORT || '5432');
+```
+
+### Testing
+
+Constructive provides a layered testing framework stack. **Always use the appropriate framework** — never manually create `pg.Pool` or `pg.Client` instances in tests.
+
+#### Which Framework to Use
+
+| Scenario | Framework | Import |
+|----------|-----------|--------|
+| Raw SQL, RLS policies, database functions | `pgsql-test` | `import { getConnections } from 'pgsql-test'` |
+| PostGraphile schema, basic GraphQL queries | `graphile-test` | `import { getConnections } from 'graphile-test'` |
+| GraphQL with Constructive plugins (search, pgvector, etc.) | `@constructive-io/graphql-test` | `import { getConnections } from '@constructive-io/graphql-test'` |
+| HTTP endpoints, auth headers, middleware | `@constructive-io/graphql-server-test` | `import { getConnections } from '@constructive-io/graphql-server-test'` |
+
+Each layer builds on `pgsql-test` underneath — they all create isolated test databases with proper teardown.
+
+#### Required Test Hooks
+
+Always include `beforeEach`/`afterEach` hooks to ensure test isolation via savepoints:
+
+```typescript
+import { getConnections, PgTestClient } from 'pgsql-test';
+
+let pg: PgTestClient;
+let db: PgTestClient;
+let teardown: () => Promise<void>;
+
+beforeAll(async () => {
+  ({ pg, db, teardown } = await getConnections());
+});
+
+afterAll(async () => {
+  await teardown();
+});
+
+beforeEach(async () => {
+  await pg.beforeEach();
+  await db.beforeEach();
+});
+
+afterEach(async () => {
+  await db.afterEach();
+  await pg.afterEach();
+});
+```
+
+#### Anti-Patterns to Avoid
+
+- **Never** create `new pg.Pool()` or `new pg.Client()` in tests — use `getConnections()` from the appropriate framework
+- **Never** use `getPgPool()` from `pg-cache` in tests — that's for production connection pooling
+- **Never** manually create/drop databases in tests — `pgsql-test` handles this automatically
+- **Never** skip `beforeEach`/`afterEach` hooks — tests will leak state to each other
+- **Never** construct connection strings manually — use the env configuration system
+
 ## Tips
 
 1. Start with `pgpm/core/AGENTS.md` to understand the migration and plan model.
-2. Use `packages/cli/AGENTS.md` to understand Constructive’s command routing.
+2. Use `packages/cli/AGENTS.md` to understand Constructive's command routing.
 3. Use `postgres/pgsql-test/AGENTS.md` for patterns around isolated test DBs and seeding.

README.md

@@ -48,7 +48,7 @@ pgpm install @pgpm/faker
 # 4. Deploy everything
 pgpm deploy --createdb --database mydb1
 psql -d mydb1 -c "SELECT faker.city('MI');"
->  Ann Arbor
+>  Ann Arbor 
 ```
 
 ### Starting a New Project and Adding a Change

examples/codegen-integration/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.6.8](https://github.com/constructive-io/constructive/compare/@constructive-io/examples-codegen-integration@1.6.7...@constructive-io/examples-codegen-integration@1.6.8) (2026-03-17)
+
+**Note:** Version bump only for package @constructive-io/examples-codegen-integration
+
+## [1.6.7](https://github.com/constructive-io/constructive/compare/@constructive-io/examples-codegen-integration@1.6.6...@constructive-io/examples-codegen-integration@1.6.7) (2026-03-17)
+
+**Note:** Version bump only for package @constructive-io/examples-codegen-integration
+
 ## [1.6.6](https://github.com/constructive-io/constructive/compare/@constructive-io/examples-codegen-integration@1.6.5...@constructive-io/examples-codegen-integration@1.6.6) (2026-03-16)
 
 **Note:** Version bump only for package @constructive-io/examples-codegen-integration

examples/codegen-integration/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/examples-codegen-integration",
-  "version": "1.6.6",
+  "version": "1.6.8",
   "private": true,
   "scripts": {
     "codegen": "tsx scripts/codegen-runner.ts",

graphile/graphile-connection-filter/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.1.5](https://github.com/constructive-io/constructive/compare/graphile-connection-filter@1.1.4...graphile-connection-filter@1.1.5) (2026-03-17)
+
+**Note:** Version bump only for package graphile-connection-filter
+
+## [1.1.4](https://github.com/constructive-io/constructive/compare/graphile-connection-filter@1.1.3...graphile-connection-filter@1.1.4) (2026-03-17)
+
+**Note:** Version bump only for package graphile-connection-filter
+
 ## [1.1.3](https://github.com/constructive-io/constructive/compare/graphile-connection-filter@1.1.2...graphile-connection-filter@1.1.3) (2026-03-16)
 
 **Note:** Version bump only for package graphile-connection-filter

graphile/graphile-connection-filter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-connection-filter",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "PostGraphile v5 native connection filter plugin - adds advanced filtering to connections",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",