the introspection cache and buildkey solution

Author: Zetazzz

.gitignore

@@ -13,3 +13,4 @@ postgres/pgsql-test/output/
 .env.local
 graphql/server/logs/
 graphql/server/*.heapsnapshot
+graphql/server/perf/results/

graphile/graphile-multi-tenancy-cache/README.md

@@ -0,0 +1,24 @@
+# graphile-multi-tenancy-cache
+
+Template-based multi-tenancy optimization for PostGraphile v5. Shares PostGraphile instances across tenants with identical schema structures using AST-based SQL rewriting.
+
+## Features
+
+- **Schema fingerprinting** — structural comparison (tables, columns, constraints) ignoring schema names
+- **Template sharing** — one PostGraphile instance per unique fingerprint, shared across N tenants
+- **AST-based SQL rewrite** — safe schema remapping via `pgsql-parser`/`pgsql-deparser`
+- **Three cache layers** — introspection cache, template registry, SQL rewrite cache (all LRU + TTL)
+- **No Crystal fork** — wrapper plugin intercepts at `withPgClient` level via Grafast middleware
+
+## Architecture
+
+```
+Request → authenticate → resolve tenant schemas
+  → introspection cache (fingerprint lookup)
+  → template registry (shared PostGraphile instance)
+  → PgMultiTenancyWrapperPlugin (client.query Proxy)
+  → AST rewrite cache (schema name remapping)
+  → PostgreSQL
+```
+
+See [SPEC.md](./SPEC.md) for full architecture documentation.

graphile/graphile-multi-tenancy-cache/SPEC.md

@@ -0,0 +1,18 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        babelConfig: false,
+        tsconfig: 'tsconfig.json',
+      },
+    ],
+  },
+  transformIgnorePatterns: [`/node_modules/*`],
+  testRegex: '(/__tests__/.*|(\\.|/)(test|spec))\\.(jsx?|tsx?)$',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  modulePathIgnorePatterns: ['dist/*']
+};

graphile/graphile-multi-tenancy-cache/jest.config.js

@@ -0,0 +1,58 @@
+{
+  "name": "graphile-multi-tenancy-cache",
+  "version": "0.1.0",
+  "author": "Constructive <developers@constructive.io>",
+  "description": "Template-based multi-tenancy cache for PostGraphile v5 — shares instances across tenants with identical schemas",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "keywords": [
+    "postgraphile",
+    "graphile",
+    "multi-tenancy",
+    "cache",
+    "template",
+    "constructive",
+    "v5"
+  ],
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "dependencies": {
+    "@pgpmjs/logger": "workspace:^",
+    "express": "^5.2.1",
+    "grafserv": "1.0.0",
+    "graphile-config": "1.0.0",
+    "pg": "^8.11.3",
+    "pg-env": "workspace:^",
+    "pg-introspection": "1.0.0",
+    "pgsql-deparser": "^17.18.2",
+    "pgsql-parser": "^17.9.14",
+    "postgraphile": "5.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/pg": "^8.10.9",
+    "makage": "^0.3.0",
+    "ts-node": "^10.9.2"
+  }
+}