@supabase/postgrest-typegen 0.5.0 → 0.7.0

package/README.md

@@ -89,8 +89,10 @@ A type reference carries `type_id`, `format` (the type's name, spelled like
 `PostgresColumn.format`) and `type_schema`, so a generator maps it with the
 same table it uses for columns. An overload's `error` is the message the
 TypeScript generator emits as the `Returns` type of an unresolvable overload:
-two overloads PostgREST cannot tell apart, or a computed field that returns no
-rows. Overloads are ordered by argument list, then by return type; the
+two overloads PostgREST cannot tell apart, or a sole unnamed row parameter,
+which PostgREST never matches under `/rpc` (such a function is a computed
+field or computed relationship, reached by embedding it from its relation).
+Overloads are ordered by argument list, then by return type; the
 TypeScript generator emits them in that order.
 
 `resolveRpcFunctions` is pure and deterministic, so a custom producer attaches
@@ -98,6 +100,38 @@ it the same way, and a document without the collection (produced before it
 existed) still generates: the TypeScript generator falls back to running the
 pass itself.
 
+### View column nullability
+
+PostgreSQL never marks view columns `NOT NULL`, so `introspect()` works out
+`is_nullable` for view and materialized view columns from the view's query
+tree. A column is not nullable when it is a plain reference to a `NOT NULL`
+column (directly, through another view, a subquery, a non-recursive CTE, a
+join alias or a `GROUP BY` key) and nothing on the way puts it on the nullable
+side of an outer join, in a set operation such as `UNION` or under
+`GROUPING SETS`/`ROLLUP`/`CUBE`. This works the same on every supported
+PostgreSQL version. Expressions stay nullable, even ones that cannot return
+null.
+
+For a column the catalog cannot prove non-null, such as `coalesce(x, 0)` or
+`count(*)`, add a line containing only `@notNull` to its comment:
+
+```sql
+comment on column my_view.total is '@notNull';
+```
+
+The directive is honored on view and materialized view columns only, and the
+comment is passed through unchanged.
+
+The inference describes the rows a query reads, so a few values can still be
+null where the type says otherwise:
+
+- Rows returned by a write through an `INSTEAD OF` trigger are the trigger's
+  `NEW`, so a column the trigger leaves unset comes back null.
+- PostgreSQL does not enforce `NOT NULL` inside composite values, so a column
+  whose type is a view's row type can hold a row with null fields.
+- A materialized view keeps the rows of its last refresh, including nulls from
+  before its source column became `NOT NULL`.
+
 ### Runtime validation (opt-in)
 
 `GeneratorMetadata` is backed by an [ArkType](https://arktype.io) schema, so a

package/dist/generation/typescript.js

@@ -29,7 +29,6 @@ const defaultFormat = async (code) => {
  */
 export const generateTypescript = async (metadata, opts = {}) => {
     const { schemas, tables, foreignTables, views, materializedViews, columns, relationships, types, } = metadata;
-    // Documents predating the collection (still valid version 1) resolve it here.
     const rpcFunctions = metadata.rpcFunctions ?? resolveRpcFunctions(metadata);
     const { detectOneToOneRelationships = false, postgrestVersion, defaultSchema = "public", format = defaultFormat, } = opts;
     const resolvedDefaultSchema = schemas.some(({ name }) => name === defaultSchema) || !schemas[0]
@@ -177,7 +176,10 @@ export const generateTypescript = async (metadata, opts = {}) => {
         // Without that metadata PostgREST still returns an array, so the collapse would make
         // the type diverge from the actual response.
         const collapsibleSingleRow = setof_options?.is_one_to_one === true;
-        return `${returnType}${overload.is_set_returning && !collapsibleSingleRow ? "[]" : ""}
+        const isArray = overload.error === null &&
+            overload.is_set_returning &&
+            !collapsibleSingleRow;
+        return `${returnType}${isArray ? "[]" : ""}
                           ${setofOptionsInfo}`;
     };
     const getFunctionReturnType = (schema, { returns }) => {

package/dist/introspection/index.d.ts

@@ -13,6 +13,12 @@ export interface Queryable {
 export interface IntrospectOptions {
     includedSchemas?: string[];
     excludedSchemas?: string[];
+    /**
+     * PostgREST's `db-extra-search-path` schemas. A view in a generated schema
+     * that selects from a view in one of them keeps the relationships of the
+     * underlying tables, as in PostgREST. Nothing in these schemas is generated.
+     */
+    extraSearchPath?: string[];
 }
 /**
  * Introspect a database into the `GeneratorMetadata` contract.

package/dist/introspection/index.js

@@ -11,7 +11,9 @@ import { PRIMARY_KEYS_SQL } from "./sql/primary_keys.sql.js";
 import { SCHEMAS_SQL } from "./sql/schemas.sql.js";
 import { TABLES_SQL } from "./sql/table.sql.js";
 import { TYPES_SQL } from "./sql/types.sql.js";
+import { VIEW_DEFINITIONS_SQL } from "./sql/view_definitions.sql.js";
 import { VIEWS_SQL } from "./sql/views.sql.js";
+import { applyViewColumnNullability } from "./view-nullability.js";
 /**
  * Introspect a database into the `GeneratorMetadata` contract.
  *
@@ -32,7 +34,7 @@ export async function introspect(db, opts = {}) {
     // introspection queries under Promise.all. A pooled Queryable runs them in
     // parallel; a single-connection one pipelines them, which is no worse than
     // awaiting each in turn.
-    const [schemas, tables, foreignTables, views, materializedViews, columns, primaryKeys, relationships, functions, types,] = await Promise.all([
+    const [schemas, tables, foreignTables, views, materializedViews, columns, primaryKeys, relationships, functions, types, viewDefinitions,] = await Promise.all([
         queryRows(SCHEMAS_SQL({ schemaFilter: systemExcludingFilter })),
         queryRows(TABLES_SQL({ schemaFilter: systemExcludingFilter })),
         queryRows(FOREIGN_TABLES_SQL({ schemaFilter: plainFilter })),
@@ -40,9 +42,10 @@ export async function introspect(db, opts = {}) {
         queryRows(MATERIALIZED_VIEWS_SQL({ schemaFilter: plainFilter })),
         queryRows(COLUMNS_SQL({ schemaFilter: systemExcludingFilter })),
         queryRows(PRIMARY_KEYS_SQL({ schemaFilter: systemExcludingFilter })),
-        listRelationships(db, systemExcludingFilter),
+        listRelationships(db, systemExcludingFilter, opts.extraSearchPath),
         queryRows(FUNCTIONS_SQL({ schemaFilter: systemExcludingFilter })),
         queryRows(TYPES_SQL),
+        queryRows(VIEW_DEFINITIONS_SQL({ schemaFilter: systemExcludingFilter })),
     ]);
     const metadata = {
         version: GENERATOR_METADATA_VERSION,
@@ -51,7 +54,7 @@ export async function introspect(db, opts = {}) {
         foreignTables,
         views,
         materializedViews,
-        columns,
+        columns: applyViewColumnNullability(columns, viewDefinitions),
         primaryKeys,
         relationships,
         functions: functions.filter(({ return_type }) => !["trigger", "event_trigger"].includes(return_type)),

package/dist/introspection/node-tree.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A value in the text form of a `pg_node_tree`: a scalar token, `null` for
+ * `<>`, a list, or a node. Integer, OID and bitmapset lists (`(i 1 2)`,
+ * `(o 23)`, `(b 3)`) lose their marker and become lists of scalar tokens.
+ */
+export type NodeTreeValue = string | null | NodeTreeValue[] | NodeTreeNode;
+export interface NodeTreeNode {
+    type: string;
+    fields: Record<string, NodeTreeValue>;
+}
+/**
+ * Parse the text form of a `pg_node_tree` (for example
+ * `pg_rewrite.ev_action::text`), following the tokenizer of PostgreSQL's
+ * `read.c`: tokens are separated by whitespace, `(`, `)`, `{` and `}` are
+ * tokens of their own, and a backslash escapes the next character.
+ */
+export declare function parseNodeTree(text: string): NodeTreeValue;
+export declare function isNode(value: NodeTreeValue | undefined, type?: string): value is NodeTreeNode;

package/dist/introspection/node-tree.js

@@ -0,0 +1,100 @@
+const LIST_MARKERS = new Set(["i", "o", "b", "x"]);
+const WHITESPACE = " \t\n";
+const PUNCTUATION = "(){}";
+/**
+ * Parse the text form of a `pg_node_tree` (for example
+ * `pg_rewrite.ev_action::text`), following the tokenizer of PostgreSQL's
+ * `read.c`: tokens are separated by whitespace, `(`, `)`, `{` and `}` are
+ * tokens of their own, and a backslash escapes the next character.
+ */
+export function parseNodeTree(text) {
+    const tokens = tokenize(text);
+    let position = 0;
+    const peek = () => tokens[position];
+    const next = () => {
+        const token = tokens[position++];
+        if (token === undefined) {
+            throw new Error("Unexpected end of pg_node_tree");
+        }
+        return token;
+    };
+    const isFieldEnd = (token) => token === undefined || token.raw === "}" || token.raw.startsWith(":");
+    const parseValue = () => {
+        const token = next();
+        if (token.raw === "{") {
+            const type = next().text;
+            const fields = {};
+            while (peek()?.raw !== "}") {
+                const name = next().raw.slice(1);
+                fields[name] = isFieldEnd(peek()) ? null : parseValue();
+                // Some fields span several tokens, such as a constant's
+                // `:constvalue 4 [ 1 0 0 0 ]`; only the first one is kept.
+                while (!isFieldEnd(peek())) {
+                    parseValue();
+                }
+            }
+            next();
+            return { type, fields };
+        }
+        if (token.raw === "(") {
+            const items = [];
+            const first = peek();
+            if (first !== undefined && LIST_MARKERS.has(first.raw)) {
+                next();
+            }
+            while (peek()?.raw !== ")") {
+                items.push(parseValue());
+            }
+            next();
+            return items;
+        }
+        if (token.raw === "<>") {
+            return null;
+        }
+        return token.text;
+    };
+    const value = parseValue();
+    if (position !== tokens.length) {
+        throw new Error("Trailing tokens after pg_node_tree");
+    }
+    return value;
+}
+function tokenize(text) {
+    const tokens = [];
+    let index = 0;
+    while (index < text.length) {
+        const character = text.charAt(index);
+        if (WHITESPACE.includes(character)) {
+            index++;
+            continue;
+        }
+        if (PUNCTUATION.includes(character)) {
+            tokens.push({ raw: character, text: character });
+            index++;
+            continue;
+        }
+        const start = index;
+        let unescaped = "";
+        while (index < text.length) {
+            const current = text.charAt(index);
+            if (current === "\\" && index + 1 < text.length) {
+                unescaped += text.charAt(index + 1);
+                index += 2;
+                continue;
+            }
+            if (WHITESPACE.includes(current) || PUNCTUATION.includes(current)) {
+                break;
+            }
+            unescaped += current;
+            index++;
+        }
+        tokens.push({ raw: text.slice(start, index), text: unescaped });
+    }
+    return tokens;
+}
+export function isNode(value, type) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        (type === undefined || value.type === type));
+}

package/dist/introspection/relationships.d.ts

@@ -10,7 +10,8 @@ import type { Queryable } from "./index.ts";
  *     by mapping a base table's foreign key columns onto the view columns that
  *     select them (`VIEWS_KEY_DEPENDENCIES_SQL` + the cartesian-product
  *     expansion below). This second part is pure TypeScript, not SQL — ported
- *     verbatim from upstream.
+ *     from postgres-meta, except that the expansion sees every non-system
+ *     schema's foreign keys, as PostgREST does (see `listRelationships`).
  *
  * Adapted from:
  * https://github.com/PostgREST/postgrest/blob/f9f0f79fa914ac00c11fbf7f4c558e14821e67e2/src/PostgREST/SchemaCache.hs#L392
@@ -33,15 +34,22 @@ export type ViewKeyDependency = {
  * view↔view relationships implied by the view key dependencies. Pure function
  * (no database) so the cartesian-product expansion can be unit-tested directly.
  *
- * Ported verbatim from `PostgresMetaRelationships.list()` (the body of the
- * `allViewM2oAndO2oRelationships` block).
+ * Ported from `PostgresMetaRelationships.list()` (the body of the
+ * `allViewM2oAndO2oRelationships` block). Every table relationship feeds the
+ * expansion, but a table→view relationship is emitted on the table itself, so
+ * `isTableEmitted` keeps it to the tables the caller returns relationships for.
  */
-export declare function expandViewRelationships(allTableM2oAndO2oRelationships: PostgresRelationship[], viewsKeyDependencies: ViewKeyDependency[]): PostgresRelationship[];
+export declare function expandViewRelationships(allTableM2oAndO2oRelationships: PostgresRelationship[], viewsKeyDependencies: ViewKeyDependency[], isTableEmitted: (relationship: PostgresRelationship) => boolean): PostgresRelationship[];
 /**
  * List all relationships (table↔table plus the view-derived ones) for the
  * schemas selected by `schemaFilter`, the `IN (…)`/`NOT IN (…)` fragment
- * `introspect()` builds with the system schemas excluded. Errors from the
- * injected `Queryable` propagate by throwing — callers adapt.
+ * `introspect()` builds with the system schemas excluded. Like PostgREST, view
+ * expansion sees the foreign keys of every non-system schema, so a view over a
+ * table in a schema that is not selected keeps the table's foreign keys; only
+ * the views and tables in the selected schemas get relationships. Views in the
+ * `extraSearchPath` schemas are followed to their base tables but get no
+ * relationships of their own. Errors from the injected `Queryable` propagate
+ * by throwing — callers adapt.
  */
-export declare function listRelationships(db: Queryable, schemaFilter: string): Promise<PostgresRelationship[]>;
+export declare function listRelationships(db: Queryable, schemaFilter: string, extraSearchPath?: string[]): Promise<PostgresRelationship[]>;
 export {};

package/dist/introspection/relationships.js

@@ -1,3 +1,4 @@
+import { DEFAULT_SYSTEM_SCHEMAS, filterByList } from "./sql/helpers.js";
 import { TABLE_RELATIONSHIPS_SQL } from "./sql/table_relationships.sql.js";
 import { VIEWS_KEY_DEPENDENCIES_SQL } from "./sql/views_key_dependencies.sql.js";
 /**
@@ -5,10 +6,22 @@ import { VIEWS_KEY_DEPENDENCIES_SQL } from "./sql/views_key_dependencies.sql.js"
  * view↔view relationships implied by the view key dependencies. Pure function
  * (no database) so the cartesian-product expansion can be unit-tested directly.
  *
- * Ported verbatim from `PostgresMetaRelationships.list()` (the body of the
- * `allViewM2oAndO2oRelationships` block).
+ * Ported from `PostgresMetaRelationships.list()` (the body of the
+ * `allViewM2oAndO2oRelationships` block). Every table relationship feeds the
+ * expansion, but a table→view relationship is emitted on the table itself, so
+ * `isTableEmitted` keeps it to the tables the caller returns relationships for.
  */
-export function expandViewRelationships(allTableM2oAndO2oRelationships, viewsKeyDependencies) {
+export function expandViewRelationships(allTableM2oAndO2oRelationships, viewsKeyDependencies, isTableEmitted) {
+    const keyDepsByConstraint = new Map();
+    for (const vkd of viewsKeyDependencies) {
+        const key = keyDependencyKey(vkd.table_schema, vkd.table_name, vkd.constraint_name, vkd.constraint_type);
+        let bucket = keyDepsByConstraint.get(key);
+        if (!bucket) {
+            bucket = [];
+            keyDepsByConstraint.set(key, bucket);
+        }
+        bucket.push(vkd);
+    }
     return allTableM2oAndO2oRelationships.flatMap((r) => {
         const expandKeyDepCols = (colDeps) => {
             const tableColumns = colDeps.map(({ table_column }) => table_column);
@@ -19,14 +32,8 @@ export function expandViewRelationships(allTableM2oAndO2oRelationships, viewsKey
                 viewColumns,
             }));
         };
-        const viewToTableKeyDeps = viewsKeyDependencies.filter((vkd) => vkd.table_schema === r.schema &&
-            vkd.table_name === r.relation &&
-            vkd.constraint_name === r.foreign_key_name &&
-            vkd.constraint_type === "f");
-        const tableToViewKeyDeps = viewsKeyDependencies.filter((vkd) => vkd.table_schema === r.referenced_schema &&
-            vkd.table_name === r.referenced_relation &&
-            vkd.constraint_name === r.foreign_key_name &&
-            vkd.constraint_type === "f_ref");
+        const viewToTableKeyDeps = keyDepsByConstraint.get(keyDependencyKey(r.schema, r.relation, r.foreign_key_name, "f")) ?? [];
+        const tableToViewKeyDeps = keyDepsByConstraint.get(keyDependencyKey(r.referenced_schema, r.referenced_relation, r.foreign_key_name, "f_ref")) ?? [];
         const viewToTableRelationships = viewToTableKeyDeps.flatMap((vtkd) => expandKeyDepCols(vtkd.column_dependencies).map(({ viewColumns }) => ({
             foreign_key_name: r.foreign_key_name,
             schema: vtkd.view_schema,
@@ -37,7 +44,7 @@ export function expandViewRelationships(allTableM2oAndO2oRelationships, viewsKey
             referenced_relation: r.referenced_relation,
             referenced_columns: r.referenced_columns,
         })));
-        const tableToViewRelationships = tableToViewKeyDeps.flatMap((tvkd) => expandKeyDepCols(tvkd.column_dependencies).map(({ viewColumns }) => ({
+        const tableToViewRelationships = (isTableEmitted(r) ? tableToViewKeyDeps : []).flatMap((tvkd) => expandKeyDepCols(tvkd.column_dependencies).map(({ viewColumns }) => ({
             foreign_key_name: r.foreign_key_name,
             schema: r.schema,
             relation: r.relation,
@@ -67,12 +74,27 @@ export function expandViewRelationships(allTableM2oAndO2oRelationships, viewsKey
 /**
  * List all relationships (table↔table plus the view-derived ones) for the
  * schemas selected by `schemaFilter`, the `IN (…)`/`NOT IN (…)` fragment
- * `introspect()` builds with the system schemas excluded. Errors from the
- * injected `Queryable` propagate by throwing — callers adapt.
+ * `introspect()` builds with the system schemas excluded. Like PostgREST, view
+ * expansion sees the foreign keys of every non-system schema, so a view over a
+ * table in a schema that is not selected keeps the table's foreign keys; only
+ * the views and tables in the selected schemas get relationships. Views in the
+ * `extraSearchPath` schemas are followed to their base tables but get no
+ * relationships of their own. Errors from the injected `Queryable` propagate
+ * by throwing — callers adapt.
  */
-export async function listRelationships(db, schemaFilter) {
-    const { rows: allTableM2oAndO2oRelationships } = await db.query(TABLE_RELATIONSHIPS_SQL({ schemaFilter }));
-    const { rows: viewsKeyDependencies } = await db.query(VIEWS_KEY_DEPENDENCIES_SQL({ schemaFilter }));
-    const allViewM2oAndO2oRelationships = expandViewRelationships(allTableM2oAndO2oRelationships, viewsKeyDependencies);
-    return allTableM2oAndO2oRelationships.concat(allViewM2oAndO2oRelationships);
+export async function listRelationships(db, schemaFilter, extraSearchPath = []) {
+    const tableRelationshipsQuery = db.query(TABLE_RELATIONSHIPS_SQL({ schemaFilter }));
+    const [{ rows: tableRelationships }, { rows: allTableRelationships }, { rows: viewsKeyDependencies },] = await Promise.all([
+        tableRelationshipsQuery,
+        schemaFilter === NON_SYSTEM_SCHEMAS_FILTER
+            ? tableRelationshipsQuery
+            : db.query(TABLE_RELATIONSHIPS_SQL({ schemaFilter: NON_SYSTEM_SCHEMAS_FILTER })),
+        db.query(VIEWS_KEY_DEPENDENCIES_SQL({ schemaFilter, extraSearchPath })),
+    ]);
+    const emittedKeys = new Set(tableRelationships.map(relationshipKey));
+    const allViewM2oAndO2oRelationships = expandViewRelationships(allTableRelationships, viewsKeyDependencies, (r) => emittedKeys.has(relationshipKey(r)));
+    return tableRelationships.concat(allViewM2oAndO2oRelationships);
 }
+const NON_SYSTEM_SCHEMAS_FILTER = filterByList(undefined, undefined, DEFAULT_SYSTEM_SCHEMAS);
+const relationshipKey = (r) => JSON.stringify([r.schema, r.relation, r.foreign_key_name]);
+const keyDependencyKey = (tableSchema, tableName, constraintName, constraintType) => JSON.stringify([tableSchema, tableName, constraintName, constraintType]);

package/dist/introspection/sql/view_definitions.sql.d.ts

@@ -0,0 +1,8 @@
+import type { SchemaFilterProps } from "./common.ts";
+/**
+ * The query tree of every view and materialized view in the filtered schemas,
+ * plus every view they read from in any schema, with the `NOT NULL` columns
+ * each one references. `inferNonNullViewColumns` resolves view column
+ * nullability from it.
+ */
+export declare const VIEW_DEFINITIONS_SQL: (props: SchemaFilterProps) => string;

package/dist/introspection/sql/view_definitions.sql.js

@@ -0,0 +1,43 @@
+/**
+ * The query tree of every view and materialized view in the filtered schemas,
+ * plus every view they read from in any schema, with the `NOT NULL` columns
+ * each one references. `inferNonNullViewColumns` resolves view column
+ * nullability from it.
+ */
+export const VIEW_DEFINITIONS_SQL = (props) => /* SQL */ `
+WITH RECURSIVE view_closure(oid) AS (
+  SELECT c.oid
+  FROM pg_class c
+  JOIN pg_namespace n ON n.oid = c.relnamespace
+  WHERE
+    ${props.schemaFilter ? `n.nspname ${props.schemaFilter} AND` : ""}
+    c.relkind IN ('v', 'm')
+  UNION
+  SELECT dep.refobjid
+  FROM view_closure vc
+  JOIN pg_rewrite r ON r.ev_class = vc.oid AND r.rulename = '_RETURN'
+  JOIN pg_depend dep ON dep.classid = 'pg_rewrite' :: regclass
+    AND dep.objid = r.oid
+    AND dep.refclassid = 'pg_class' :: regclass
+  JOIN pg_class rc ON rc.oid = dep.refobjid AND rc.relkind IN ('v', 'm')
+)
+SELECT
+  r.ev_class :: int8 AS view_id,
+  r.ev_action :: text AS definition,
+  COALESCE(
+    (
+      SELECT json_agg(json_build_array(dep.refobjid :: int8, dep.refobjsubid))
+      FROM pg_depend dep
+      JOIN pg_attribute a ON a.attrelid = dep.refobjid AND a.attnum = dep.refobjsubid
+      JOIN pg_type t ON t.oid = a.atttypid
+      WHERE dep.classid = 'pg_rewrite' :: regclass
+        AND dep.objid = r.oid
+        AND dep.refclassid = 'pg_class' :: regclass
+        AND dep.refobjsubid > 0
+        AND (a.attnotnull OR t.typtype = 'd' AND t.typnotnull)
+    ),
+    '[]'
+  ) AS non_null_columns
+FROM view_closure vc
+JOIN pg_rewrite r ON r.ev_class = vc.oid AND r.rulename = '_RETURN'
+`;

package/dist/introspection/sql/views_key_dependencies.sql.d.ts

@@ -1,2 +1,4 @@
 import type { SchemaFilterProps } from "./common.ts";
-export declare const VIEWS_KEY_DEPENDENCIES_SQL: (props: SchemaFilterProps) => string;
+export declare const VIEWS_KEY_DEPENDENCIES_SQL: (props: SchemaFilterProps & {
+    extraSearchPath?: string[];
+}) => string;

package/dist/introspection/sql/views_key_dependencies.sql.js

@@ -1,3 +1,4 @@
+import { filterByList } from "./helpers.js";
 import { literal } from "./pg-format.js";
 export const VIEWS_KEY_DEPENDENCIES_SQL = (props) => /* SQL */ `
 -- Adapted from
@@ -27,7 +28,6 @@ pks_fks as (
   from pg_constraint
   left join lateral unnest(confkey) with ordinality as _(col, ord) on true
   where contype='f'
-  ${props.schemaFilter ? `and connamespace::regnamespace::text ${props.schemaFilter}` : ""}
 ),
 views as (
   select
@@ -39,7 +39,7 @@ views as (
   join pg_namespace n on n.oid = c.relnamespace
   join pg_rewrite r on r.ev_class = c.oid
   where c.relkind in ('v', 'm') 
-    ${props.schemaFilter ? `and n.nspname ${props.schemaFilter}` : ""}
+    ${viewSchemaFilter(props)}
 ),
 transform_json as (
   select
@@ -120,6 +120,18 @@ group by sch.nspname, tbl.relname,  rep.view_schema, rep.view_name, pks_fks.conn
 -- make sure we only return key for which all columns are referenced in the view - no partial PKs or FKs
 having ncol = array_length(array_agg(row(col.attname, view_columns) order by pks_fks.ord), 1)
 `;
+/**
+ * Like PostgREST, the views followed to their base tables also include the
+ * `db-extra-search-path` schemas; the recursion still starts from the selected
+ * schemas only.
+ */
+function viewSchemaFilter({ schemaFilter, extraSearchPath = [], }) {
+    if (!schemaFilter)
+        return "";
+    if (extraSearchPath.length === 0)
+        return `and n.nspname ${schemaFilter}`;
+    return `and (n.nspname ${schemaFilter} or n.nspname ${filterByList(extraSearchPath)})`;
+}
 /**
  * The rewrites, innermost first, that turn the `pg_node_tree` text of a view
  * definition into JSON exposing only `targetList`, `resno`, `resorigtbl` and

package/dist/introspection/view-nullability.d.ts

@@ -0,0 +1,14 @@
+import type { PostgresColumn } from "../types.ts";
+/** A row of `VIEW_DEFINITIONS_SQL`. */
+export interface ViewDefinitionRow {
+    view_id: number | string;
+    definition: string;
+    non_null_columns: [number | string, number | string][];
+}
+/**
+ * Mark view and materialized view columns as not nullable when PostgreSQL can
+ * prove it from the view's query tree (see {@link inferNonNullViewColumns}) or
+ * when the column comment has an `@notNull` line. PostgreSQL never sets
+ * `attnotnull` on view columns, so without this every one of them is nullable.
+ */
+export declare function applyViewColumnNullability<T extends PostgresColumn>(columns: T[], rows: ViewDefinitionRow[]): T[];

package/dist/introspection/view-nullability.js

@@ -0,0 +1,167 @@
+import { isNode, parseNodeTree, } from "./node-tree.js";
+const RTE_RELATION = "0";
+const RTE_SUBQUERY = "1";
+const RTE_JOIN = "2";
+const RTE_CTE = "6";
+const RTE_GROUP = "9";
+const JOIN_INNER = "0";
+const JOIN_LEFT = "1";
+const JOIN_RIGHT = "3";
+const NOT_NULL_DIRECTIVE = /^\s*@notNull\s*$/m;
+/**
+ * Mark view and materialized view columns as not nullable when PostgreSQL can
+ * prove it from the view's query tree (see {@link inferNonNullViewColumns}) or
+ * when the column comment has an `@notNull` line. PostgreSQL never sets
+ * `attnotnull` on view columns, so without this every one of them is nullable.
+ */
+export function applyViewColumnNullability(columns, rows) {
+    const viewIds = new Set(rows.map((row) => String(row.view_id)));
+    const nonNull = inferNonNullViewColumns(rows);
+    return columns.map((column) => column.is_nullable &&
+        viewIds.has(String(column.table_id)) &&
+        (nonNull.has(column.id) || NOT_NULL_DIRECTIVE.test(column.comment ?? ""))
+        ? { ...column, is_nullable: false }
+        : column);
+}
+/**
+ * The ids (`<view oid>.<attnum>`) of the view columns that can never be null.
+ * A column qualifies when it is a plain reference to a `NOT NULL` column, or
+ * to a view column that qualifies, followed through joins, subqueries,
+ * non-recursive CTEs and `GROUP BY`, and nothing on the way puts it on the
+ * nullable side of an outer join, in a set operation or under grouping sets.
+ * The outer-join check walks the join tree instead of reading
+ * `varnullingrels`, which PostgreSQL 15 does not have.
+ */
+function inferNonNullViewColumns(rows) {
+    const definitions = new Map(rows.map((row) => [String(row.view_id), row.definition]));
+    const nonNullBaseColumns = new Set(rows.flatMap((row) => row.non_null_columns.map(([relation, attnum]) => `${relation}.${attnum}`)));
+    const resolved = new Map();
+    const nullableIndexesByQuery = new Map();
+    const nullableIndexesOf = (query) => {
+        let indexes = nullableIndexesByQuery.get(query);
+        if (indexes === undefined) {
+            indexes = nullableRangeTableIndexes(query);
+            nullableIndexesByQuery.set(query, indexes);
+        }
+        return indexes;
+    };
+    const nonNullColumnsOfView = (viewId) => {
+        const cached = resolved.get(viewId);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const columns = new Set();
+        resolved.set(viewId, columns);
+        try {
+            const tree = parseNodeTree(definitions.get(viewId) ?? "");
+            const query = Array.isArray(tree) ? tree[0] : tree;
+            if (isNode(query, "QUERY") && allowsNonNull(query)) {
+                for (const entry of list(query.fields.targetList)) {
+                    if (isNode(entry, "TARGETENTRY") &&
+                        entry.fields.resjunk !== "true" &&
+                        isNonNullExpression(entry.fields.expr, [query])) {
+                        columns.add(Number(entry.fields.resno));
+                    }
+                }
+            }
+        }
+        catch {
+            columns.clear();
+        }
+        return columns;
+    };
+    const isNonNullColumn = (relation, attnum) => definitions.has(relation)
+        ? nonNullColumnsOfView(relation).has(attnum)
+        : nonNullBaseColumns.has(`${relation}.${attnum}`);
+    const isNonNullExpression = (expression, queries) => {
+        const query = queries.at(-1);
+        if (query === undefined ||
+            !isNode(expression, "VAR") ||
+            expression.fields.varlevelsup !== "0") {
+            return false;
+        }
+        const varno = Number(expression.fields.varno);
+        const attnum = Number(expression.fields.varattno);
+        if (attnum <= 0 || nullableIndexesOf(query).has(varno)) {
+            return false;
+        }
+        const entry = list(query.fields.rtable)[varno - 1];
+        if (!isNode(entry, "RANGETBLENTRY")) {
+            return false;
+        }
+        switch (entry.fields.rtekind) {
+            case RTE_RELATION:
+                return (typeof entry.fields.relid === "string" &&
+                    isNonNullColumn(entry.fields.relid, attnum));
+            case RTE_SUBQUERY:
+                return isNonNullOutput(entry.fields.subquery, attnum, queries);
+            case RTE_JOIN:
+                return isNonNullExpression(list(entry.fields.joinaliasvars)[attnum - 1], queries);
+            case RTE_GROUP:
+                return isNonNullExpression(list(entry.fields.groupexprs)[attnum - 1], queries);
+            case RTE_CTE: {
+                const levelsUp = Number(entry.fields.ctelevelsup);
+                const owner = queries.at(-1 - levelsUp);
+                const cte = list(owner?.fields.cteList).find((candidate) => isNode(candidate, "COMMONTABLEEXPR") &&
+                    candidate.fields.ctename === entry.fields.ctename);
+                return (isNode(cte) &&
+                    cte.fields.cterecursive !== "true" &&
+                    isNonNullOutput(cte.fields.ctequery, attnum, queries.slice(0, queries.length - levelsUp)));
+            }
+            default:
+                return false;
+        }
+    };
+    const isNonNullOutput = (subquery, resno, queries) => {
+        if (!isNode(subquery, "QUERY") || !allowsNonNull(subquery)) {
+            return false;
+        }
+        const entry = list(subquery.fields.targetList).find((candidate) => isNode(candidate, "TARGETENTRY") &&
+            Number(candidate.fields.resno) === resno);
+        return (isNode(entry) &&
+            isNonNullExpression(entry.fields.expr, [...queries, subquery]));
+    };
+    const result = new Set();
+    for (const viewId of definitions.keys()) {
+        for (const attnum of nonNullColumnsOfView(viewId)) {
+            result.add(`${viewId}.${attnum}`);
+        }
+    }
+    return result;
+}
+function allowsNonNull(query) {
+    return (query.fields.setOperations === null &&
+        list(query.fields.groupingSets).length === 0);
+}
+/**
+ * The range table indexes that sit on the nullable side of an outer join in
+ * the query's join tree, including the indexes of nested joins themselves.
+ */
+function nullableRangeTableIndexes(query) {
+    const nullable = new Set();
+    const visit = (node, isNullable) => {
+        if (isNode(node, "RANGETBLREF")) {
+            if (isNullable) {
+                nullable.add(Number(node.fields.rtindex));
+            }
+        }
+        else if (isNode(node, "FROMEXPR")) {
+            for (const item of list(node.fields.fromlist)) {
+                visit(item, isNullable);
+            }
+        }
+        else if (isNode(node, "JOINEXPR")) {
+            const joinType = node.fields.jointype;
+            if (isNullable) {
+                nullable.add(Number(node.fields.rtindex));
+            }
+            visit(node.fields.larg, isNullable || (joinType !== JOIN_INNER && joinType !== JOIN_LEFT));
+            visit(node.fields.rarg, isNullable || (joinType !== JOIN_INNER && joinType !== JOIN_RIGHT));
+        }
+    };
+    visit(query.fields.jointree, false);
+    return nullable;
+}
+function list(value) {
+    return Array.isArray(value) ? value : [];
+}