feat: _meta plumbing + CleanManyToManyRelation junction key fields

- Extend CleanManyToManyRelation with junctionLeftKeyFields,
  junctionRightKeyFields, leftKeyFields, rightKeyFields (both codegen
  and query packages)
- Add MetaTableInfo type to SchemaSourceResult for _meta data flow
- Add fetchGraphqlQuery() helper for arbitrary GraphQL queries
- Endpoint source now fetches _meta in parallel with introspection
  (graceful fallback if endpoint lacks MetaSchemaPlugin)
- Add buildSchemaWithMeta() to graphile-schema that returns SDL +
  cached tablesMeta from MetaSchemaPlugin
- Database source now returns tablesMeta via buildSchemaWithMeta()

Sets up the plumbing for PR 3 (ORM add/remove junction methods).

Author: pyramation

graphile/graphile-schema/src/build-schema.ts

@@ -1,6 +1,6 @@
 import deepmerge from 'deepmerge'
 import { printSchema } from 'graphql'
-import { ConstructivePreset, makePgService } from 'graphile-settings'
+import { ConstructivePreset, makePgService, _cachedTablesMeta } from 'graphile-settings'
 import { makeSchema } from 'graphile-build'
 import { getPgPool } from 'pg-cache'
 import { getPgEnvOptions } from 'pg-env'
@@ -12,7 +12,13 @@ export type BuildSchemaOptions = {
   graphile?: Partial<GraphileConfig.Preset>;
 };
 
-export async function buildSchemaSDL(opts: BuildSchemaOptions): Promise<string> {
+export interface BuildSchemaWithMetaResult {
+  sdl: string;
+  /** Table metadata collected by MetaSchemaPlugin during schema build */
+  tablesMeta: unknown[];
+}
+
+async function buildSchemaInternal(opts: BuildSchemaOptions) {
   const database = opts.database ?? 'constructive'
   const schemas = Array.isArray(opts.schemas) ? opts.schemas : []
 
@@ -39,5 +45,23 @@ export async function buildSchemaSDL(opts: BuildSchemaOptions): Promise<string>
     : basePreset
 
   const { schema } = await makeSchema(preset)
+  return { schema }
+}
+
+export async function buildSchemaSDL(opts: BuildSchemaOptions): Promise<string> {
+  const { schema } = await buildSchemaInternal(opts)
   return printSchema(schema)
 }
+
+/**
+ * Build schema SDL and also return _meta table metadata.
+ * The MetaSchemaPlugin populates a module-level cache during makeSchema();
+ * we snapshot it immediately after the build completes.
+ */
+export async function buildSchemaWithMeta(opts: BuildSchemaOptions): Promise<BuildSchemaWithMetaResult> {
+  const { schema } = await buildSchemaInternal(opts)
+  return {
+    sdl: printSchema(schema),
+    tablesMeta: [..._cachedTablesMeta],
+  }
+}

graphile/graphile-schema/src/index.ts

@@ -1,4 +1,4 @@
-export { buildSchemaSDL } from './build-schema';
-export type { BuildSchemaOptions } from './build-schema';
+export { buildSchemaSDL, buildSchemaWithMeta } from './build-schema';
+export type { BuildSchemaOptions, BuildSchemaWithMetaResult } from './build-schema';
 export { fetchEndpointSchemaSDL } from './fetch-endpoint-schema';
 export type { FetchEndpointSchemaOptions } from './fetch-endpoint-schema';

graphql/codegen/src/core/introspect/fetch-schema.ts

@@ -71,6 +71,79 @@ export interface FetchSchemaResult {
   statusCode?: number;
 }
 
+export interface FetchGraphqlQueryResult<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  statusCode?: number;
+}
+
+/**
+ * Execute an arbitrary GraphQL query against an endpoint.
+ * Reuses the same HTTP plumbing as fetchSchema but accepts any query string.
+ */
+export async function fetchGraphqlQuery<T = unknown>(
+  options: FetchSchemaOptions & { query: string },
+): Promise<FetchGraphqlQueryResult<T>> {
+  const { endpoint, authorization, headers = {}, timeout = 30000, query } = options;
+
+  const url = new URL(endpoint);
+
+  const requestHeaders: Record<string, string> = {
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+    ...headers,
+  };
+
+  if (authorization) {
+    requestHeaders['Authorization'] = authorization;
+  }
+
+  const body = JSON.stringify({ query, variables: {} });
+
+  const requestOptions: http.RequestOptions = {
+    method: 'POST',
+    headers: requestHeaders,
+  };
+
+  try {
+    const response = await makeRequest(url, requestOptions, body, timeout);
+
+    if (response.statusCode < 200 || response.statusCode >= 300) {
+      return {
+        success: false,
+        error: `HTTP ${response.statusCode}: ${response.statusMessage}`,
+        statusCode: response.statusCode,
+      };
+    }
+
+    const json = JSON.parse(response.data) as {
+      data?: T;
+      errors?: Array<{ message: string }>;
+    };
+
+    if (json.errors && json.errors.length > 0) {
+      const errorMessages = json.errors.map((e) => e.message).join('; ');
+      return {
+        success: false,
+        error: `GraphQL errors: ${errorMessages}`,
+        statusCode: response.statusCode,
+      };
+    }
+
+    return {
+      success: true,
+      data: json.data,
+      statusCode: response.statusCode,
+    };
+  } catch (err) {
+    if (err instanceof Error) {
+      return { success: false, error: err.message };
+    }
+    return { success: false, error: 'Unknown error occurred' };
+  }
+}
+
 /**
  * Fetch the full schema introspection from a GraphQL endpoint
  */

graphql/codegen/src/core/introspect/index.ts

@@ -12,6 +12,7 @@ export { pluralize, singularize } from 'inflekt';
 // Schema sources
 export type {
   CreateSchemaSourceOptions,
+  MetaTableInfo,
   SchemaSource,
   SchemaSourceResult,
 } from './source';
@@ -24,8 +25,8 @@ export {
 } from './source';
 
 // Schema fetching (still used by watch mode)
-export type { FetchSchemaOptions, FetchSchemaResult } from './fetch-schema';
-export { fetchSchema } from './fetch-schema';
+export type { FetchSchemaOptions, FetchSchemaResult, FetchGraphqlQueryResult } from './fetch-schema';
+export { fetchSchema, fetchGraphqlQuery } from './fetch-schema';
 
 // Transform utilities (only filterTables, getTableNames, findTable are still useful)
 export { filterTables, findTable, getTableNames } from './transform';

graphql/codegen/src/core/introspect/source/database.ts

@@ -3,18 +3,19 @@
  *
  * Loads GraphQL schema directly from a PostgreSQL database using PostGraphile
  * introspection and converts it to introspection format.
+ * Also returns _meta table metadata when available (via MetaSchemaPlugin cache).
  */
 import { buildSchema, introspectionFromSchema } from 'graphql';
 
-import { buildSchemaSDL } from 'graphile-schema';
+import { buildSchemaWithMeta } from 'graphile-schema';
 
 import type { IntrospectionQueryResponse } from '../../../types/introspection';
 import {
   createDatabasePool,
   resolveApiSchemas,
   validateServicesSchemas,
 } from './api-schemas';
-import type { SchemaSource, SchemaSourceResult } from './types';
+import type { MetaTableInfo, SchemaSource, SchemaSourceResult } from './types';
 import { SchemaSourceError } from './types';
 
 export interface DatabaseSchemaSourceOptions {
@@ -78,13 +79,16 @@ export class DatabaseSchemaSource implements SchemaSource {
       schemas = this.options.schemas ?? ['public'];
     }
 
-    // Build SDL from database
+    // Build SDL + _meta from database
     let sdl: string;
+    let tablesMeta: unknown[] = [];
     try {
-      sdl = await buildSchemaSDL({
+      const result = await buildSchemaWithMeta({
         database,
         schemas,
       });
+      sdl = result.sdl;
+      tablesMeta = result.tablesMeta;
     } catch (err) {
       throw new SchemaSourceError(
         `Failed to introspect database: ${err instanceof Error ? err.message : 'Unknown error'}`,
@@ -130,7 +134,10 @@ export class DatabaseSchemaSource implements SchemaSource {
       JSON.stringify(introspectionResult),
     ) as IntrospectionQueryResponse;
 
-    return { introspection };
+    return {
+      introspection,
+      tablesMeta: tablesMeta as MetaTableInfo[],
+    };
   }
 
   describe(): string {

graphql/codegen/src/core/introspect/source/endpoint.ts

@@ -2,12 +2,43 @@
  * Endpoint Schema Source
  *
  * Fetches GraphQL schema via introspection from a live endpoint.
- * Wraps the existing fetchSchema() function with the SchemaSource interface.
+ * Optionally fetches _meta query in parallel for M:N junction key metadata.
  */
-import { fetchSchema } from '../fetch-schema';
-import type { SchemaSource, SchemaSourceResult } from './types';
+import { fetchSchema, fetchGraphqlQuery } from '../fetch-schema';
+import type { MetaTableInfo, SchemaSource, SchemaSourceResult } from './types';
 import { SchemaSourceError } from './types';
 
+/**
+ * _meta GraphQL query — fetches M:N junction key metadata.
+ * Only the fields needed for enriching CleanManyToManyRelation are selected.
+ */
+const META_QUERY = `{
+  _meta {
+    tables {
+      name
+      schemaName
+      relations {
+        manyToMany {
+          fieldName
+          type
+          junctionTable { name }
+          junctionLeftKeyAttributes { name }
+          junctionRightKeyAttributes { name }
+          leftKeyAttributes { name }
+          rightKeyAttributes { name }
+          rightTable { name }
+        }
+      }
+    }
+  }
+}`;
+
+interface MetaQueryResponse {
+  _meta: {
+    tables: MetaTableInfo[];
+  };
+}
+
 export interface EndpointSchemaSourceOptions {
   /**
    * GraphQL endpoint URL
@@ -41,30 +72,45 @@ export class EndpointSchemaSource implements SchemaSource {
   }
 
   async fetch(): Promise<SchemaSourceResult> {
-    const result = await fetchSchema({
+    const fetchOpts = {
       endpoint: this.options.endpoint,
       authorization: this.options.authorization,
       headers: this.options.headers,
       timeout: this.options.timeout,
-    });
+    };
+
+    // Run introspection and _meta query in parallel.
+    // _meta is best-effort: if the endpoint doesn't expose it, we proceed without.
+    const [introspectionResult, metaResult] = await Promise.all([
+      fetchSchema(fetchOpts),
+      fetchGraphqlQuery<MetaQueryResponse>({ ...fetchOpts, query: META_QUERY })
+        .catch((): null => null),
+    ]);
 
-    if (!result.success) {
+    if (!introspectionResult.success) {
       throw new SchemaSourceError(
-        result.error ?? 'Unknown error fetching schema',
+        introspectionResult.error ?? 'Unknown error fetching schema',
         this.describe(),
       );
     }
 
-    if (!result.data) {
+    if (!introspectionResult.data) {
       throw new SchemaSourceError(
         'No introspection data returned',
         this.describe(),
       );
     }
 
-    return {
-      introspection: result.data,
+    const result: SchemaSourceResult = {
+      introspection: introspectionResult.data,
     };
+
+    // Attach _meta data if available
+    if (metaResult?.success && metaResult.data?._meta?.tables) {
+      result.tablesMeta = metaResult.data._meta.tables;
+    }
+
+    return result;
   }
 
   describe(): string {

graphql/codegen/src/core/introspect/source/types.ts

@@ -6,6 +6,27 @@
  */
 import type { IntrospectionQueryResponse } from '../../../types/introspection';
 
+/**
+ * Minimal table metadata from the _meta query, used to enrich M:N relations
+ * with junction key field information that isn't available from introspection alone.
+ */
+export interface MetaTableInfo {
+  name: string;
+  schemaName: string;
+  relations: {
+    manyToMany: Array<{
+      fieldName: string | null;
+      type: string | null;
+      junctionTable: { name: string };
+      junctionLeftKeyAttributes: Array<{ name: string }>;
+      junctionRightKeyAttributes: Array<{ name: string }>;
+      leftKeyAttributes: Array<{ name: string }>;
+      rightKeyAttributes: Array<{ name: string }>;
+      rightTable: { name: string };
+    }>;
+  };
+}
+
 /**
  * Result from fetching a schema source
  */
@@ -14,6 +35,12 @@ export interface SchemaSourceResult {
    * The GraphQL introspection data
    */
   introspection: IntrospectionQueryResponse;
+
+  /**
+   * Optional table metadata from _meta query (provides M:N junction key details).
+   * Present when the source supports _meta (database mode or endpoints with MetaSchemaPlugin).
+   */
+  tablesMeta?: MetaTableInfo[];
 }
 
 /**

graphql/codegen/src/types/schema.ts

@@ -192,6 +192,14 @@ export interface CleanManyToManyRelation {
   rightTable: string;
   junctionTable: string;
   type: string | null;
+  /** Junction FK field names pointing to the left table */
+  junctionLeftKeyFields?: string[];
+  /** Junction FK field names pointing to the right table */
+  junctionRightKeyFields?: string[];
+  /** Left table key fields (usually just 'id') */
+  leftKeyFields?: string[];
+  /** Right table key fields (usually just 'id') */
+  rightKeyFields?: string[];
 }
 
 // ============================================================================

graphql/query/src/types/schema.ts

@@ -192,6 +192,14 @@ export interface CleanManyToManyRelation {
   rightTable: string;
   junctionTable: string;
   type: string | null;
+  /** Junction FK field names pointing to the left table */
+  junctionLeftKeyFields?: string[];
+  /** Junction FK field names pointing to the right table */
+  junctionRightKeyFields?: string[];
+  /** Left table key fields (usually just 'id') */
+  leftKeyFields?: string[];
+  /** Right table key fields (usually just 'id') */
+  rightKeyFields?: string[];
 }
 
 // ============================================================================