@graphoria/server 0.4.0 → 0.5.0

package/src/cron/index.ts

@@ -7,6 +7,8 @@ import type { TickContext } from "../types/zod/cron";
 import { databasesConnections, repositoryMap } from "../singletons/databases";
 import { queueManager } from "../singletons/queues";
 import { logger } from "../logging";
+import { incMetric, observeMetric } from "../observability/metrics";
+import { startSpan, withActiveSpan } from "../observability/tracing";
 
 /**
  * Interface for a scheduled cron job instance
@@ -58,42 +60,63 @@ const createScheduledJob = (config: CronJob, gqlQuery: GqlQueryFn<true>): Schedu
       context: config.context,
     },
     async (self) => {
-      try {
-        log.info("executing");
-
-        executionCount++;
-
-        // Execute query if provided
-        const response = config.query
-          ? await gqlQuery(config.query, config.variables ?? {})
-          : undefined;
-
-        const tickContext: TickContext = {
-          name: config.name,
-          pattern: config.pattern,
-          variables: config.variables || {},
-          executionCount,
-          nextRun: self.nextRun(),
-          previousRun: self.previousRun(),
-        };
-
-        // Call the onTick callback if provided, passing options object
-        await config.onTick?.(
-          {
-            gqlQuery,
-            databases: databasesConnections,
-            queues: queueManager,
-            repository: repositoryMap,
-          },
-          tickContext,
-          response,
-        );
-
-        log.info({ executionCount, nextRun: self.nextRun() }, "completed");
-      } catch (error) {
-        log.error({ err: error }, "failed");
-        throw error;
-      }
+      const startTime = Bun.nanoseconds();
+      let outcome: "success" | "error" = "success";
+      // A tick is not inside a request, so it roots its own trace. The span is
+      // entered so anything `onTick` runs through `gqlQuery` lands under it.
+      const span = startSpan("cron.tick", {
+        parent: null,
+        attributes: { "graphoria.cron.job": config.name },
+      });
+
+      return withActiveSpan(span, async () => {
+        try {
+          log.info("executing");
+
+          executionCount++;
+
+          // Execute query if provided
+          const response = config.query
+            ? await gqlQuery(config.query, config.variables ?? {})
+            : undefined;
+
+          const tickContext: TickContext = {
+            name: config.name,
+            pattern: config.pattern,
+            variables: config.variables || {},
+            executionCount,
+            nextRun: self.nextRun(),
+            previousRun: self.previousRun(),
+          };
+
+          // Call the onTick callback if provided, passing options object
+          await config.onTick?.(
+            {
+              gqlQuery,
+              databases: databasesConnections,
+              queues: queueManager,
+              repository: repositoryMap,
+            },
+            tickContext,
+            response,
+          );
+
+          log.info({ executionCount, nextRun: self.nextRun() }, "completed");
+        } catch (error) {
+          outcome = "error";
+          log.error({ err: error }, "failed");
+          span?.recordError(error);
+          throw error;
+        } finally {
+          incMetric("graphoria_cron_runs_total", { job: config.name, outcome });
+          observeMetric(
+            "graphoria_cron_run_duration_seconds",
+            { job: config.name },
+            (Bun.nanoseconds() - startTime) / 1e9,
+          );
+          span?.end();
+        }
+      });
     },
   );
 

package/src/databases/common.ts

@@ -59,6 +59,18 @@ const resolveBooleanOperand = (
 
 export const generateTableAlias = (level: number): string => `t${level}`;
 
+/**
+ * A table whose alias is lexically in scope above the join being emitted, outermost
+ * first and including the immediate parent. Nested selections compile to correlated
+ * subqueries, so every enclosing alias stays referenceable — this is what lets a
+ * relationship condition name a column on an ancestor rather than a literal.
+ *
+ * Built fresh at each recursion rather than read off `aliasMap`: that map is flat,
+ * shared and written by two different level counters, so it cannot distinguish an
+ * enclosing scope from a sibling that merely ran earlier.
+ */
+export type QueryPathFrame = { table: string; alias: string };
+
 const mappingDbTypeCharVar: Record<DatabaseType, string> = {
   pg: "$",
   mysql: "$",
@@ -76,6 +88,7 @@ export const buildConditions = (
   aliasMap: { [alias: string]: string },
   /** Query name of the table being filtered — resolves its virtual columns. */
   tableName?: string,
+  ancestors: readonly QueryPathFrame[] = [],
 ): string => {
   if (!whereArgs) return "";
 
@@ -135,6 +148,13 @@ export const buildConditions = (
 
       const parentTableName = aliasMap[tableAlias];
 
+      // An EXISTS sits inside the WHERE of the block that binds `tableAlias`, so that
+      // block encloses it just as a selection subquery would. Extending the scope here
+      // is what makes a relation filter emit the same predicate as the selection form.
+      const scope = parentTableName
+        ? [...ancestors, { table: parentTableName, alias: tableAlias }]
+        : ancestors;
+
       const joinCondition = findJoinCondition(
         entities,
         parentTableName,
@@ -142,6 +162,7 @@ export const buildConditions = (
         tableAlias,
         nestedTableAlias,
         dbType,
+        scope,
       );
 
       // Record this relation's alias→table so a deeper nested where (3+ levels) can resolve
@@ -159,6 +180,7 @@ export const buildConditions = (
         level + 1,
         aliasMap,
         fieldName,
+        scope,
       );
 
       const existsClause = `EXISTS (
@@ -324,6 +346,47 @@ const columnCollation = (
   return column && "collation" in column ? column.collation : undefined;
 };
 
+// Resolves an `ancestor` condition to a qualified column on an enclosing alias.
+// Matches on entity identity rather than on the frame's key, because a frame may be
+// keyed by a suffixed relationship name (`app_users_ref`) and because resolverName
+// depends on the database's configurable `fieldNaming` — neither is comparable to
+// the schema/name pair the config declares. Nearest enclosing match wins, so a
+// self-referential chain binds to the closest occurrence.
+const ancestorOperand = (
+  entities: MergedEntities,
+  ancestors: readonly QueryPathFrame[],
+  ancestor: { schema: string; name: string; column: string },
+  leftTable: string,
+  leftColumn: string,
+  dbType: DatabaseType,
+): { sql: string; collate: string } => {
+  for (let i = ancestors.length - 1; i >= 0; i--) {
+    const frame = ancestors[i]!;
+    const entity = entities.queriesMap[frame.table];
+
+    if (entity?.schema !== ancestor.schema || entity.name !== ancestor.name) continue;
+
+    return {
+      sql: `${frame.alias}.${wrapIdentifierFp(dbType)(ancestor.column)}`,
+      // Unlike a literal comparison, this equates two character columns that may
+      // carry different collations — the case collateSuffix exists for.
+      collate: collateSuffix(
+        dbType,
+        columnCollation(entities, leftTable, leftColumn),
+        columnCollation(entities, frame.table, ancestor.column),
+      ),
+    };
+  }
+
+  const inScope = ancestors.map((a) => a.table).join(" > ");
+
+  throw new Error(
+    `Relationship condition references ancestor table "${ancestor.schema}.${ancestor.name}", which is not in this query's path. ` +
+      `In scope here: ${inScope || "(none)"}. ` +
+      `Nest this selection under ${ancestor.schema}.${ancestor.name}, or drop the "ancestor" condition.`,
+  );
+};
+
 const pairsToAnd = (
   pairs: {
     parentAlias: string;
@@ -377,6 +440,7 @@ const renderCondition = (
   column: string,
   operator: string,
   value: string | number | boolean | undefined,
+  ancestor?: { sql: string; collate: string },
 ): string => {
   const target = `${alias}.${wrapIdentifierFp(dbType)(column)}`;
 
@@ -384,7 +448,13 @@ const renderCondition = (
   if (operator === "is_not_null") return `${target} IS NOT NULL`;
 
   const sqlOperator = RELATIONSHIP_CONDITION_SQL_OPERATORS[operator];
-  if (!sqlOperator || value === undefined) {
+  if (!sqlOperator) {
+    throw new Error(`Invalid relationship condition operator "${operator}"`);
+  }
+
+  if (ancestor) return `${target} ${sqlOperator} ${ancestor.sql}${ancestor.collate}`;
+
+  if (value === undefined) {
     throw new Error(`Invalid relationship condition operator "${operator}"`);
   }
 
@@ -396,16 +466,25 @@ const renderCondition = (
 // toAlias). The from/to aliases flip between forward and reverse joins.
 const conditionsToAnd = (
   conditions: readonly RelationshipCondition[] | undefined,
-  fromAlias: string,
-  toAlias: string,
+  from: { alias: string; table: string },
+  to: { alias: string; table: string },
   dbType: DatabaseType,
+  entities: MergedEntities,
+  ancestors: readonly QueryPathFrame[],
 ): string =>
   (conditions ?? [])
-    .map((c) =>
-      c.source !== undefined
-        ? renderCondition(dbType, fromAlias, c.source, c.operator ?? "eq", c.value)
-        : renderCondition(dbType, toAlias, c.target!, c.operator ?? "eq", c.value),
-    )
+    .map((c) => {
+      const side = c.source !== undefined ? from : to;
+      const column = (c.source ?? c.target)!;
+
+      // The from/to flip above picks the left operand only; an ancestor is the right
+      // operand and resolves by table identity, so it is direction-independent.
+      const ancestor = c.ancestor
+        ? ancestorOperand(entities, ancestors, c.ancestor, side.table, column, dbType)
+        : undefined;
+
+      return renderCondition(dbType, side.alias, column, c.operator ?? "eq", c.value, ancestor);
+    })
     .join(" AND ");
 
 const joinParts = (...parts: string[]): string => parts.filter(Boolean).join(" AND ");
@@ -417,6 +496,7 @@ export const findJoinCondition = (
   parentAlias: string,
   childAlias: string,
   dbType: DatabaseType,
+  ancestors: readonly QueryPathFrame[] = [],
 ): string => {
   const relations = entities.getForeignKeysBetweenTables(parentTableName, childTableName);
 
@@ -436,7 +516,14 @@ export const findJoinCondition = (
           })),
           dbType,
         ),
-        conditionsToAnd(relation.conditions, parentAlias, childAlias, dbType),
+        conditionsToAnd(
+          relation.conditions,
+          { alias: parentAlias, table: parentTableName },
+          { alias: childAlias, table: childTableName },
+          dbType,
+          entities,
+          ancestors,
+        ),
       ),
     ) ?? []),
     ...(relations.relationshipsReversed?.map((relation) =>
@@ -452,7 +539,14 @@ export const findJoinCondition = (
           })),
           dbType,
         ),
-        conditionsToAnd(relation.conditions, childAlias, parentAlias, dbType),
+        conditionsToAnd(
+          relation.conditions,
+          { alias: childAlias, table: childTableName },
+          { alias: parentAlias, table: parentTableName },
+          dbType,
+          entities,
+          ancestors,
+        ),
       ),
     ) ?? []),
   ].join(" AND ");
@@ -470,6 +564,7 @@ export const buildWhereClauseFp =
     parentTableAlias: string | null,
     level: number,
     aliasMap: { [alias: string]: string },
+    ancestors: readonly QueryPathFrame[] = [],
   ): string => {
     const whereConditions: string[] = [
       buildConditions(
@@ -482,7 +577,10 @@ export const buildWhereClauseFp =
         level + 1,
         aliasMap,
         field.name ?? aliasMap[tableAlias],
+        ancestors,
       ),
+      // `ancestors` already ends with this join's parent, and the child is the field
+      // being emitted, so the scope needs no splicing here.
       parentTableName && parentTableAlias
         ? findJoinCondition(
             entities,
@@ -491,6 +589,7 @@ export const buildWhereClauseFp =
             parentTableAlias,
             tableAlias,
             dbType,
+            ancestors,
           )
         : null,
     ].filter(Boolean) as string[];

package/src/databases/core/executor.ts

@@ -1,14 +1,24 @@
 import type { VariableDefinition } from "../../analyzeQuery/types";
+import type { QuerySource } from "../../logging/slowQuery";
 import type { Database } from "../../types/configuration";
 import type { ProcedureResolver } from "../../types/db";
 
 import { databaseAdapters } from "./function-mapping";
 import { logger } from "../../logging";
+import { reportQueryDuration } from "../../logging/slowQuery";
+import { startSpan } from "../../observability/tracing";
 
 /**
  * Core database execution functions
  */
 
+/** Names only. The variable values are caller data and never reach a span. */
+const sourceAttributes = (source?: QuerySource) => ({
+  "graphql.operation.name": source?.operation.name ?? undefined,
+  "graphql.operation.type": source?.operation.type,
+  "graphoria.role": source?.role,
+});
+
 export const executeQuery = async <T>(
   query: string,
   db: Database,
@@ -16,6 +26,7 @@ export const executeQuery = async <T>(
   variables: Record<string, unknown>,
   /** Per-operation override. `undefined` leaves the engine on its own default. */
   timeoutMs?: number,
+  source?: QuerySource,
 ) => {
   const adapter = databaseAdapters[db?.type];
   if (!adapter) {
@@ -24,16 +35,40 @@ export const executeQuery = async <T>(
 
   const log = logger("db").child({ dbType: db.type, dbName: db.name });
   const startTime = Bun.nanoseconds();
+  const report = (durationMs: number, outcome: "success" | "error") =>
+    reportQueryDuration({
+      durationMs,
+      dbType: db.type,
+      dbName: db.name,
+      sql: query,
+      outcome,
+      ...source,
+    });
+  // Every literal is hoisted into a bound parameter, so the statement text
+  // carries no caller data and is safe to export.
+  const span = startSpan("db.query", {
+    kind: "client",
+    attributes: {
+      "db.system": db.type,
+      "db.name": db.name,
+      "db.statement": query,
+      ...sourceAttributes(source),
+    },
+  });
 
   try {
     const result = await adapter.execute<T>(query, db, variablesDefinition, variables, timeoutMs);
-    log.debug(
-      { durationMs: (Bun.nanoseconds() - startTime) / 1e6, queryLength: query.length },
-      "query executed",
-    );
+    const durationMs = (Bun.nanoseconds() - startTime) / 1e6;
+    log.debug({ durationMs, queryLength: query.length }, "query executed");
+    report(durationMs, "success");
+    span?.end();
     return result;
   } catch (error) {
-    log.error({ err: error, durationMs: (Bun.nanoseconds() - startTime) / 1e6 }, "query failed");
+    const durationMs = (Bun.nanoseconds() - startTime) / 1e6;
+    log.error({ err: error, durationMs }, "query failed");
+    report(durationMs, "error");
+    span?.recordError(error);
+    span?.end();
     throw error;
   }
 };
@@ -45,6 +80,7 @@ export const executeQueryJSON = async <T>(
   variables: Record<string, unknown>,
   /** Per-operation override. `undefined` leaves the engine on its own default. */
   timeoutMs?: number,
+  source?: QuerySource,
 ) => {
   const adapter = databaseAdapters[db.type];
   if (!adapter) {
@@ -53,6 +89,24 @@ export const executeQueryJSON = async <T>(
 
   const log = logger("db").child({ dbType: db.type, dbName: db.name });
   const startTime = Bun.nanoseconds();
+  const report = (durationMs: number, outcome: "success" | "error") =>
+    reportQueryDuration({
+      durationMs,
+      dbType: db.type,
+      dbName: db.name,
+      sql: query,
+      outcome,
+      ...source,
+    });
+  const span = startSpan("db.query", {
+    kind: "client",
+    attributes: {
+      "db.system": db.type,
+      "db.name": db.name,
+      "db.statement": query,
+      ...sourceAttributes(source),
+    },
+  });
 
   try {
     const result = await adapter.executeJson<T>(
@@ -62,16 +116,17 @@ export const executeQueryJSON = async <T>(
       variables,
       timeoutMs,
     );
-    log.debug(
-      { durationMs: (Bun.nanoseconds() - startTime) / 1e6, queryLength: query.length },
-      "query executed (json)",
-    );
+    const durationMs = (Bun.nanoseconds() - startTime) / 1e6;
+    log.debug({ durationMs, queryLength: query.length }, "query executed (json)");
+    report(durationMs, "success");
+    span?.end();
     return result;
   } catch (error) {
-    log.error(
-      { err: error, durationMs: (Bun.nanoseconds() - startTime) / 1e6 },
-      "query failed (json)",
-    );
+    const durationMs = (Bun.nanoseconds() - startTime) / 1e6;
+    log.error({ err: error, durationMs }, "query failed (json)");
+    report(durationMs, "error");
+    span?.recordError(error);
+    span?.end();
     throw error;
   }
 };
@@ -79,6 +134,7 @@ export const executeQueryJSON = async <T>(
 export const callStoredProcedure = async (
   sp: ProcedureResolver,
   variables: Record<string, unknown> = {},
+  source?: QuerySource,
 ) => {
   const adapter = databaseAdapters[sp.db!.type];
   if (!adapter) {
@@ -91,16 +147,38 @@ export const callStoredProcedure = async (
     procedure: sp.dottedName,
   });
   const startTime = Bun.nanoseconds();
+  const report = (durationMs: number, outcome: "success" | "error") =>
+    reportQueryDuration({
+      durationMs,
+      dbType: sp.db!.type,
+      dbName: sp.db!.name,
+      procedure: sp.dottedName,
+      outcome,
+      ...source,
+    });
+  const span = startSpan("db.procedure", {
+    kind: "client",
+    attributes: {
+      "db.system": sp.db!.type,
+      "db.name": sp.db!.name,
+      "db.operation": sp.dottedName,
+      ...sourceAttributes(source),
+    },
+  });
 
   try {
     const result = await adapter.callStoredProcedure(sp, variables);
-    log.debug({ durationMs: (Bun.nanoseconds() - startTime) / 1e6 }, "stored procedure executed");
+    const durationMs = (Bun.nanoseconds() - startTime) / 1e6;
+    log.debug({ durationMs }, "stored procedure executed");
+    report(durationMs, "success");
+    span?.end();
     return result;
   } catch (error) {
-    log.error(
-      { err: error, durationMs: (Bun.nanoseconds() - startTime) / 1e6 },
-      "stored procedure failed",
-    );
+    const durationMs = (Bun.nanoseconds() - startTime) / 1e6;
+    log.error({ err: error, durationMs }, "stored procedure failed");
+    report(durationMs, "error");
+    span?.recordError(error);
+    span?.end();
     throw error;
   }
 };

package/src/databases/core/function-mapping.ts

@@ -80,7 +80,7 @@ export type InsertAuthUserInput = {
   claims?: Record<string, unknown>;
 };
 
-type DatabaseFunctions = {
+export type DatabaseFunctions = {
   query: (
     entities: MergedEntities,
     operation: OperationAnalysis,

package/src/databases/engines/mssql/query/index.ts

@@ -4,7 +4,7 @@ import type {
   VariableDefinition,
 } from "../../../../analyzeQuery/types";
 import type { MergedEntities } from "../../../../configuration/getSchemas/mergeEntities";
-import type { GroupByInfo, PageLimits } from "../../../common";
+import type { GroupByInfo, PageLimits, QueryPathFrame } from "../../../common";
 
 import {
   buildOrderByClauseMSSQL,
@@ -265,6 +265,7 @@ export const buildSQLForField = (
   level: number,
   aliasMap: { [alias: string]: string },
   pageLimits: PageLimits | null,
+  ancestors: readonly QueryPathFrame[] = [],
 ): string => {
   const tableAlias = generateTableAlias(level);
 
@@ -290,6 +291,7 @@ export const buildSQLForField = (
     parentTableAlias,
     level,
     aliasMap,
+    ancestors,
   );
 
   // Check if this is a GROUP BY query
@@ -330,6 +332,7 @@ export const buildSQLForField = (
         level,
         aliasMap,
         pageLimits,
+        [...ancestors, { table: resolverName, alias: tableAlias }],
       ),
     ([name, selector]) => `${selector} AS ${wrapIdentifierMSSQL(name)}`,
   );

package/src/databases/engines/mysql/query/index.ts

@@ -4,7 +4,7 @@ import type {
   VariableDefinition,
 } from "../../../../analyzeQuery/types";
 import type { MergedEntities } from "../../../../configuration/getSchemas/mergeEntities";
-import type { GroupByInfo, PageLimits } from "../../../common";
+import type { GroupByInfo, PageLimits, QueryPathFrame } from "../../../common";
 
 import {
   buildOrderByClauseMySQL,
@@ -105,7 +105,7 @@ const buildGroupedQuery = (
       selectClauses.push(`'${agg.nameResolved}', ${cteAlias}.${agg.alias}`);
     } else {
       selectClauses.push(
-        `'${agg.nameResolved}', JSON_OBJECT('${agg.fieldAlias}', COALESCE(${cteAlias}.${agg.alias}, NULL))`,
+        `'${agg.nameResolved}', JSON_OBJECT('${agg.fieldAlias}', ${cteAlias}.${agg.alias})`,
       );
     }
   });
@@ -257,6 +257,7 @@ export const buildSQLForField = (
   level: number,
   aliasMap: { [alias: string]: string },
   pageLimits: PageLimits | null,
+  ancestors: readonly QueryPathFrame[] = [],
 ): string => {
   const tableAlias = generateTableAlias(level);
 
@@ -282,6 +283,7 @@ export const buildSQLForField = (
     parentTableAlias,
     level,
     aliasMap,
+    ancestors,
   );
 
   // Check if this is a GROUP BY query
@@ -322,6 +324,7 @@ export const buildSQLForField = (
         level,
         aliasMap,
         pageLimits,
+        [...ancestors, { table: resolverName, alias: tableAlias }],
       ),
     ([name, selector]) => `'${name}', ${selector}`,
   );

package/src/databases/engines/postgresql/query/index.ts

@@ -4,7 +4,7 @@ import type {
   VariableDefinition,
 } from "../../../../analyzeQuery/types";
 import type { MergedEntities } from "../../../../configuration/getSchemas/mergeEntities";
-import type { GroupByInfo, PageLimits } from "../../../common";
+import type { GroupByInfo, PageLimits, QueryPathFrame } from "../../../common";
 
 import {
   buildOrderByClausePG,
@@ -101,7 +101,7 @@ const buildGroupedQuery = (
       selectClauses.push(`'${agg.nameResolved}', ${cteAlias}.${agg.alias}`);
     } else {
       selectClauses.push(
-        `'${agg.nameResolved}', json_build_object('${agg.fieldAlias}', COALESCE(${cteAlias}.${agg.alias}, null))`,
+        `'${agg.nameResolved}', json_build_object('${agg.fieldAlias}', ${cteAlias}.${agg.alias})`,
       );
     }
   });
@@ -242,6 +242,7 @@ export const buildSQLForField = (
   level: number,
   aliasMap: { [alias: string]: string },
   pageLimits: PageLimits | null,
+  ancestors: readonly QueryPathFrame[] = [],
 ): string => {
   const tableAlias = generateTableAlias(level);
 
@@ -267,6 +268,7 @@ export const buildSQLForField = (
     parentTableAlias,
     level,
     aliasMap,
+    ancestors,
   );
 
   // Check if this is a GROUP BY query
@@ -307,6 +309,7 @@ export const buildSQLForField = (
         level,
         aliasMap,
         pageLimits,
+        [...ancestors, { table: resolverName, alias: tableAlias }],
       ),
     ([name, selector]) => `'${name}', ${selector}`,
   );