chore: import upstream snapshot with attribution

python/mirage/core/postgres/__init__.py

@@ -0,0 +1,13 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========

python/mirage/core/postgres/_client.py

@@ -0,0 +1,232 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import json
+
+import asyncpg
+
+
+async def list_schemas(conn: asyncpg.Connection,
+                       allowlist: list[str] | None) -> list[str]:
+    rows = await conn.fetch(
+        "SELECT schema_name FROM information_schema.schemata "
+        "WHERE schema_name NOT IN ('pg_catalog', 'information_schema') "
+        "AND schema_name NOT LIKE 'pg_%' "
+        "ORDER BY schema_name")
+    names = [r["schema_name"] for r in rows]
+    if allowlist is not None:
+        names = [n for n in names if n in allowlist]
+    return names
+
+
+async def list_tables(conn: asyncpg.Connection, schema: str) -> list[str]:
+    rows = await conn.fetch(
+        "SELECT table_name FROM information_schema.tables "
+        "WHERE table_schema = $1 AND table_type = 'BASE TABLE' "
+        "ORDER BY table_name", schema)
+    return [r["table_name"] for r in rows]
+
+
+async def list_views(conn: asyncpg.Connection, schema: str) -> list[str]:
+    rows = await conn.fetch(
+        "SELECT table_name FROM information_schema.views "
+        "WHERE table_schema = $1 "
+        "ORDER BY table_name", schema)
+    return [r["table_name"] for r in rows]
+
+
+async def list_matviews(conn: asyncpg.Connection, schema: str) -> list[str]:
+    rows = await conn.fetch(
+        "SELECT matviewname AS name FROM pg_matviews "
+        "WHERE schemaname = $1 "
+        "ORDER BY matviewname", schema)
+    return [r["name"] for r in rows]
+
+
+async def count_rows(conn: asyncpg.Connection, schema: str, name: str) -> int:
+    return await conn.fetchval(f'SELECT COUNT(*) FROM "{schema}"."{name}"')
+
+
+async def estimate_size(conn: asyncpg.Connection, schema: str,
+                        name: str) -> tuple[int, int]:
+    plan = await conn.fetchval(
+        f'EXPLAIN (FORMAT JSON) SELECT * FROM "{schema}"."{name}"')
+    if isinstance(plan, str):
+        plan = json.loads(plan)
+    top = plan[0]["Plan"]
+    return int(top.get("Plan Rows", 0)), int(top.get("Plan Width", 0))
+
+
+async def estimated_row_count(conn: asyncpg.Connection, schema: str,
+                              name: str) -> int:
+    val = await conn.fetchval(
+        "SELECT reltuples::bigint FROM pg_class c "
+        "JOIN pg_namespace n ON c.relnamespace = n.oid "
+        "WHERE n.nspname = $1 AND c.relname = $2", schema, name)
+    return int(val) if val is not None else 0
+
+
+async def table_size_bytes(conn: asyncpg.Connection, schema: str,
+                           name: str) -> int:
+    val = await conn.fetchval(
+        "SELECT pg_total_relation_size(c.oid) FROM pg_class c "
+        "JOIN pg_namespace n ON c.relnamespace = n.oid "
+        "WHERE n.nspname = $1 AND c.relname = $2", schema, name)
+    return int(val) if val is not None else 0
+
+
+async def fetch_rows(conn: asyncpg.Connection, schema: str, name: str, *,
+                     limit: int, offset: int) -> list[dict]:
+    rows = await conn.fetch(
+        f'SELECT * FROM "{schema}"."{name}" LIMIT $1 OFFSET $2', limit, offset)
+    return [dict(r) for r in rows]
+
+
+async def fetch_columns(conn: asyncpg.Connection, schema: str,
+                        name: str) -> list[dict]:
+    rows = await conn.fetch(
+        "SELECT column_name, data_type, is_nullable "
+        "FROM information_schema.columns "
+        "WHERE table_schema = $1 AND table_name = $2 "
+        "ORDER BY ordinal_position", schema, name)
+    return [{
+        "name": r["column_name"],
+        "type": r["data_type"],
+        "nullable": r["is_nullable"] == "YES",
+    } for r in rows]
+
+
+async def fetch_primary_key(conn: asyncpg.Connection, schema: str,
+                            name: str) -> list[str]:
+    rows = await conn.fetch(
+        "SELECT kcu.column_name "
+        "FROM information_schema.table_constraints tc "
+        "JOIN information_schema.key_column_usage kcu "
+        "  ON tc.constraint_name = kcu.constraint_name "
+        " AND tc.table_schema = kcu.table_schema "
+        "WHERE tc.constraint_type = 'PRIMARY KEY' "
+        "  AND tc.table_schema = $1 AND tc.table_name = $2 "
+        "ORDER BY kcu.ordinal_position", schema, name)
+    return [r["column_name"] for r in rows]
+
+
+async def fetch_foreign_keys(conn: asyncpg.Connection, schema: str,
+                             name: str) -> list[dict]:
+    rows = await conn.fetch(
+        "SELECT con.conname AS constraint_name, "
+        "       a.attname AS from_column, "
+        "       af.attname AS to_column, "
+        "       k.ord, "
+        "       nf.nspname AS to_schema, "
+        "       cf.relname AS to_table "
+        "FROM pg_constraint con "
+        "JOIN pg_class c ON c.oid = con.conrelid "
+        "JOIN pg_namespace n ON n.oid = c.relnamespace "
+        "JOIN pg_class cf ON cf.oid = con.confrelid "
+        "JOIN pg_namespace nf ON nf.oid = cf.relnamespace "
+        "JOIN unnest(con.conkey) WITH ORDINALITY AS k(attnum, ord) ON TRUE "
+        "JOIN unnest(con.confkey) WITH ORDINALITY AS kf(attnum, ord) "
+        "  ON kf.ord = k.ord "
+        "JOIN pg_attribute a "
+        "  ON a.attrelid = con.conrelid AND a.attnum = k.attnum "
+        "JOIN pg_attribute af "
+        "  ON af.attrelid = con.confrelid AND af.attnum = kf.attnum "
+        "WHERE con.contype = 'f' AND n.nspname = $1 AND c.relname = $2 "
+        "ORDER BY con.conname, k.ord", schema, name)
+    grouped: dict[str, dict] = {}
+    for r in rows:
+        cn = r["constraint_name"]
+        if cn not in grouped:
+            grouped[cn] = {
+                "columns": [],
+                "references": {
+                    "schema": r["to_schema"],
+                    "table": r["to_table"],
+                    "columns": [],
+                },
+            }
+        grouped[cn]["columns"].append(r["from_column"])
+        grouped[cn]["references"]["columns"].append(r["to_column"])
+    return list(grouped.values())
+
+
+async def fetch_indexes(conn: asyncpg.Connection, schema: str,
+                        name: str) -> list[dict]:
+    rows = await conn.fetch(
+        "SELECT i.relname AS name, "
+        "       ix.indisunique AS unique, "
+        "       array_agg(a.attname ORDER BY x.ord) AS columns "
+        "FROM pg_class t "
+        "JOIN pg_namespace n ON t.relnamespace = n.oid "
+        "JOIN pg_index ix ON ix.indrelid = t.oid "
+        "JOIN pg_class i ON i.oid = ix.indexrelid "
+        "JOIN unnest(ix.indkey) WITH ORDINALITY AS x(attnum, ord) ON TRUE "
+        "JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = x.attnum "
+        "WHERE n.nspname = $1 AND t.relname = $2 "
+        "GROUP BY i.relname, ix.indisunique "
+        "ORDER BY i.relname", schema, name)
+    return [{
+        "name": r["name"],
+        "columns": list(r["columns"]),
+        "unique": r["unique"],
+    } for r in rows]
+
+
+async def fetch_all_relationships(conn: asyncpg.Connection,
+                                  schemas: list[str]) -> list[dict]:
+    if not schemas:
+        return []
+    rows = await conn.fetch(
+        "SELECT con.conname AS constraint_name, "
+        "       n.nspname AS from_schema, "
+        "       c.relname AS from_table, "
+        "       a.attname AS from_column, "
+        "       af.attname AS to_column, "
+        "       k.ord, "
+        "       nf.nspname AS to_schema, "
+        "       cf.relname AS to_table "
+        "FROM pg_constraint con "
+        "JOIN pg_class c ON c.oid = con.conrelid "
+        "JOIN pg_namespace n ON n.oid = c.relnamespace "
+        "JOIN pg_class cf ON cf.oid = con.confrelid "
+        "JOIN pg_namespace nf ON nf.oid = cf.relnamespace "
+        "JOIN unnest(con.conkey) WITH ORDINALITY AS k(attnum, ord) ON TRUE "
+        "JOIN unnest(con.confkey) WITH ORDINALITY AS kf(attnum, ord) "
+        "  ON kf.ord = k.ord "
+        "JOIN pg_attribute a "
+        "  ON a.attrelid = con.conrelid AND a.attnum = k.attnum "
+        "JOIN pg_attribute af "
+        "  ON af.attrelid = con.confrelid AND af.attnum = kf.attnum "
+        "WHERE con.contype = 'f' AND n.nspname = ANY($1::text[]) "
+        "ORDER BY n.nspname, c.relname, con.conname, k.ord", schemas)
+    grouped: dict[tuple[str, str, str], dict] = {}
+    for r in rows:
+        key = (r["from_schema"], r["from_table"], r["constraint_name"])
+        if key not in grouped:
+            grouped[key] = {
+                "from": {
+                    "schema": r["from_schema"],
+                    "table": r["from_table"],
+                    "columns": [],
+                },
+                "to": {
+                    "schema": r["to_schema"],
+                    "table": r["to_table"],
+                    "columns": [],
+                },
+                "kind": "many_to_one",
+            }
+        grouped[key]["from"]["columns"].append(r["from_column"])
+        grouped[key]["to"]["columns"].append(r["to_column"])
+    return list(grouped.values())

python/mirage/core/postgres/_schema_json.py

@@ -0,0 +1,91 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from mirage.accessor.postgres import PostgresAccessor
+from mirage.core.postgres import _client
+from mirage.resource.secrets import reveal_secret
+
+
+async def build_database_json(accessor: PostgresAccessor) -> dict:
+    pool = await accessor.pool()
+    async with pool.acquire() as conn:
+        schemas = await _client.list_schemas(conn, accessor.config.schemas)
+        tables: list[dict] = []
+        views: list[dict] = []
+        for s in schemas:
+            for t in await _client.list_tables(conn, s):
+                tables.append({
+                    "schema":
+                    s,
+                    "name":
+                    t,
+                    "row_count_estimate":
+                    await _client.estimated_row_count(conn, s, t),
+                    "size_bytes_estimate":
+                    await _client.table_size_bytes(conn, s, t),
+                })
+            for v in await _client.list_views(conn, s):
+                views.append({"schema": s, "name": v, "kind": "view"})
+            for v in await _client.list_matviews(conn, s):
+                views.append({"schema": s, "name": v, "kind": "materialized"})
+        relationships = await _client.fetch_all_relationships(conn, schemas)
+    return {
+        "database": _db_name_from_dsn(reveal_secret(accessor.config.dsn)),
+        "schemas": schemas,
+        "tables": tables,
+        "views": views,
+        "relationships": relationships,
+    }
+
+
+async def build_entity_schema_json(accessor: PostgresAccessor, schema: str,
+                                   name: str, kind: str) -> dict:
+    pool = await accessor.pool()
+    async with pool.acquire() as conn:
+        cols = await _client.fetch_columns(conn, schema, name)
+        pk = await _client.fetch_primary_key(conn, schema, name)
+        fks = await _client.fetch_foreign_keys(conn, schema, name)
+        idx = await _client.fetch_indexes(conn, schema, name)
+        rows = await _client.estimated_row_count(conn, schema, name)
+        size = await _client.table_size_bytes(conn, schema, name)
+    pk_set = set(pk)
+    fk_map: dict[str, dict] = {}
+    for fk in fks:
+        ref = fk["references"]
+        for from_col, to_col in zip(fk["columns"], ref["columns"]):
+            fk_map[from_col] = {
+                "schema": ref["schema"],
+                "table": ref["table"],
+                "column": to_col,
+            }
+    for col in cols:
+        if col["name"] in pk_set:
+            col["primary_key"] = True
+        if col["name"] in fk_map:
+            col["references"] = fk_map[col["name"]]
+    return {
+        "schema": schema,
+        "name": name,
+        "kind": kind,
+        "columns": cols,
+        "primary_key": pk,
+        "foreign_keys": fks,
+        "indexes": idx,
+        "row_count_estimate": rows,
+        "size_bytes_estimate": size,
+    }
+
+
+def _db_name_from_dsn(dsn: str) -> str:
+    return dsn.rstrip("/").rsplit("/", 1)[-1].split("?")[0] or "postgres"

python/mirage/core/postgres/glob.py

@@ -0,0 +1,29 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from mirage.accessor.postgres import PostgresAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.commands.builtin.constants import SCOPE_ERROR
+from mirage.core.postgres.readdir import readdir
+from mirage.types import PathSpec
+from mirage.utils.glob_walk import resolve_glob_with
+
+
+async def resolve_glob(
+    accessor: PostgresAccessor,
+    paths: list[PathSpec],
+    index: IndexCacheStore | None = None,
+) -> list[PathSpec]:
+    return await resolve_glob_with(readdir, accessor, paths, index,
+                                   SCOPE_ERROR)

python/mirage/core/postgres/read.py

@@ -0,0 +1,102 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import orjson
+
+from mirage.accessor.postgres import PostgresAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.core.postgres import _client
+from mirage.core.postgres._schema_json import (build_database_json,
+                                               build_entity_schema_json)
+from mirage.core.postgres.scope import detect_scope
+from mirage.types import PathSpec
+from mirage.utils.errors import enoent
+from mirage.utils.key_prefix import mount_key, mount_prefix_of
+
+
+async def read(
+    accessor: PostgresAccessor,
+    path: PathSpec,
+    index: IndexCacheStore = None,
+    *,
+    limit: int | None = None,
+    offset: int | None = None,
+) -> bytes:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    prefix = mount_prefix_of(path.virtual, path.resource_path)
+    raw = path.virtual
+    if prefix and raw.startswith(prefix):
+        raw = raw[len(prefix):] or "/"
+    scope = detect_scope(
+        PathSpec(virtual=raw,
+                 directory=raw,
+                 resource_path=mount_key(raw, prefix)))
+
+    if scope.level == "database_json":
+        doc = await build_database_json(accessor)
+        return orjson.dumps(doc, option=orjson.OPT_INDENT_2)
+
+    if scope.level == "entity_schema":
+        kind = "table" if scope.kind == "tables" else "view"
+        doc = await build_entity_schema_json(accessor, scope.schema,
+                                             scope.entity, kind)
+        return orjson.dumps(doc, option=orjson.OPT_INDENT_2)
+
+    if scope.level == "entity_rows":
+        return await _read_rows(accessor,
+                                scope.schema,
+                                scope.entity,
+                                kind=scope.kind,
+                                limit=limit,
+                                offset=offset)
+
+    raise enoent(path)
+
+
+async def _read_rows(accessor: PostgresAccessor, schema: str, entity: str, *,
+                     kind: str, limit: int | None,
+                     offset: int | None) -> bytes:
+    cfg = accessor.config
+    if limit is None and offset is None:
+        pool = await accessor.pool()
+        async with pool.acquire() as conn:
+            rows, width = await _client.estimate_size(conn, schema, entity)
+        if (rows > cfg.max_read_rows
+                or rows * max(width, 1) > cfg.max_read_bytes):
+            raise ValueError(
+                f"{schema}/{kind}/{entity}/rows.jsonl too large to read "
+                f"entirely: ~{rows} rows / ~{rows * max(width, 1)} bytes "
+                f"(thresholds: {cfg.max_read_rows} rows / "
+                f"{cfg.max_read_bytes} bytes); use head, tail, wc, grep, "
+                f"or pass limit/offset")
+        effective_limit = rows or cfg.default_row_limit
+        effective_offset = 0
+    else:
+        effective_limit = limit if limit is not None else cfg.default_row_limit
+        effective_offset = offset or 0
+
+    pool = await accessor.pool()
+    async with pool.acquire() as conn:
+        data = await _client.fetch_rows(conn,
+                                        schema,
+                                        entity,
+                                        limit=effective_limit,
+                                        offset=effective_offset)
+    if not data:
+        return b""
+    lines = [orjson.dumps(r, default=str).decode() for r in data]
+    return ("\n".join(lines) + "\n").encode()

python/mirage/core/postgres/readdir.py

@@ -0,0 +1,119 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from mirage.accessor.postgres import PostgresAccessor
+from mirage.cache.index import IndexCacheStore, IndexEntry
+from mirage.core.postgres import _client
+from mirage.core.postgres.scope import detect_scope
+from mirage.types import PathSpec
+from mirage.utils.errors import enoent
+from mirage.utils.key_prefix import mount_key, mount_prefix_of
+
+
+def is_dir_name(child: str) -> bool:
+    # Entries are recognized by extension, so classification never needs the
+    # stat fallback.
+    name = child.rsplit("/", 1)[-1]
+    return not (name.endswith(".json") or name.endswith(".jsonl"))
+
+
+async def readdir(accessor: PostgresAccessor,
+                  path: PathSpec,
+                  index: IndexCacheStore = None) -> list[str]:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    prefix = mount_prefix_of(path.virtual, path.resource_path)
+    raw = path.directory if path.pattern else path.virtual
+    if prefix and raw.startswith(prefix):
+        raw = raw[len(prefix):] or "/"
+    scope = detect_scope(
+        PathSpec(virtual=raw,
+                 directory=raw,
+                 resource_path=mount_key(raw, prefix)))
+    # Canonical key: no trailing slash (except root), or the same dir
+    # indexes under two keys and cache hits return doubled-slash entries.
+    virtual_key = ((prefix or "") + raw).rstrip("/") or "/"
+
+    if scope.level == "root":
+        return await _list_root(accessor, virtual_key, index, prefix)
+    if scope.level == "schema":
+        base = raw.rstrip("/")
+        return [f"{prefix}{base}/tables", f"{prefix}{base}/views"]
+    if scope.level == "kind":
+        return await _list_entities(accessor, scope.schema, scope.kind,
+                                    virtual_key, index, prefix, raw)
+    if scope.level == "entity":
+        base = raw.rstrip("/")
+        return [
+            f"{prefix}{base}/schema.json",
+            f"{prefix}{base}/rows.jsonl",
+        ]
+    raise enoent(path)
+
+
+async def _list_root(accessor: PostgresAccessor, virtual_key: str,
+                     index: IndexCacheStore | None, prefix: str) -> list[str]:
+    if index is not None:
+        listing = await index.list_dir(virtual_key)
+        if listing.entries is not None:
+            return listing.entries
+    pool = await accessor.pool()
+    async with pool.acquire() as conn:
+        schemas = await _client.list_schemas(conn, accessor.config.schemas)
+    entries: list[tuple[str, IndexEntry]] = [(
+        "database.json",
+        IndexEntry(id="database.json",
+                   name="database.json",
+                   resource_type="postgres/database_json",
+                   vfs_name="database.json"),
+    )]
+    for s in schemas:
+        entries.append((s,
+                        IndexEntry(id=s,
+                                   name=s,
+                                   resource_type="postgres/schema",
+                                   vfs_name=s)))
+    if index is not None:
+        await index.set_dir(virtual_key, entries)
+    return [f"{prefix}/{name}" for name, _ in entries]
+
+
+async def _list_entities(accessor: PostgresAccessor, schema: str, kind: str,
+                         virtual_key: str, index: IndexCacheStore | None,
+                         prefix: str, raw: str) -> list[str]:
+    if index is not None:
+        listing = await index.list_dir(virtual_key)
+        if listing.entries is not None:
+            return listing.entries
+    pool = await accessor.pool()
+    async with pool.acquire() as conn:
+        if kind == "tables":
+            names = await _client.list_tables(conn, schema)
+        else:
+            views = await _client.list_views(conn, schema)
+            mviews = await _client.list_matviews(conn, schema)
+            names = sorted(set(views) | set(mviews))
+    entries: list[tuple[str, IndexEntry]] = []
+    for n in names:
+        entries.append((n,
+                        IndexEntry(id=n,
+                                   name=n,
+                                   resource_type=f"postgres/{kind[:-1]}",
+                                   vfs_name=n)))
+    if index is not None:
+        await index.set_dir(virtual_key, entries)
+    base = raw.rstrip("/")
+    return [f"{prefix}{base}/{n}" for n, _ in entries]

python/mirage/core/postgres/scope.py

@@ -0,0 +1,72 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from dataclasses import dataclass
+
+from mirage.types import PathSpec
+
+
+@dataclass
+class PostgresScope:
+    level: str
+    schema: str | None = None
+    kind: str | None = None
+    entity: str | None = None
+    file: str | None = None
+    resource_path: str = "/"
+
+
+def detect_scope(path: PathSpec) -> PostgresScope:
+    raw = path.mount_path if isinstance(path, PathSpec) else path
+    key = raw.strip("/")
+
+    if not key:
+        return PostgresScope(level="root", resource_path="/")
+
+    if key == "database.json":
+        return PostgresScope(level="database_json",
+                             file="database.json",
+                             resource_path=raw)
+
+    parts = key.split("/")
+
+    if len(parts) == 1:
+        return PostgresScope(level="schema",
+                             schema=parts[0],
+                             resource_path=raw)
+
+    if len(parts) == 2 and parts[1] in ("tables", "views"):
+        return PostgresScope(level="kind",
+                             schema=parts[0],
+                             kind=parts[1],
+                             resource_path=raw)
+
+    if len(parts) == 3 and parts[1] in ("tables", "views"):
+        return PostgresScope(level="entity",
+                             schema=parts[0],
+                             kind=parts[1],
+                             entity=parts[2],
+                             resource_path=raw)
+
+    if len(parts) == 4 and parts[1] in ("tables", "views") and parts[3] in (
+            "schema.json", "rows.jsonl"):
+        level = "entity_schema" if parts[3] == "schema.json" else "entity_rows"
+        return PostgresScope(level=level,
+                             schema=parts[0],
+                             kind=parts[1],
+                             entity=parts[2],
+                             file=parts[3],
+                             resource_path=raw)
+
+    return PostgresScope(level="invalid", resource_path=raw)

python/mirage/core/postgres/search.py

@@ -0,0 +1,99 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import orjson
+
+from mirage.accessor.postgres import PostgresAccessor
+from mirage.core.postgres import _client
+
+_TEXT_TYPES = (
+    "text",
+    "character varying",
+    "character",
+    "name",
+    "uuid",
+    "json",
+    "jsonb",
+)
+
+
+async def _text_columns(conn, schema: str, name: str) -> list[str]:
+    rows = await conn.fetch(
+        "SELECT column_name FROM information_schema.columns "
+        "WHERE table_schema = $1 AND table_name = $2 "
+        "AND data_type = ANY($3::text[]) "
+        "ORDER BY ordinal_position", schema, name, list(_TEXT_TYPES))
+    return [r["column_name"] for r in rows]
+
+
+async def search_entity(accessor: PostgresAccessor, schema: str, kind: str,
+                        entity: str, pattern: str, limit: int) -> list[dict]:
+    pool = await accessor.pool()
+    async with pool.acquire() as conn:
+        cols = await _text_columns(conn, schema, entity)
+        if not cols:
+            return []
+        where = " OR ".join(f'"{c}"::text ILIKE $1' for c in cols)
+        sql = f'SELECT * FROM "{schema}"."{entity}" WHERE {where} LIMIT $2'
+        rows = await conn.fetch(sql, f"%{pattern}%", limit)
+        return [dict(r) for r in rows]
+
+
+async def search_kind(accessor: PostgresAccessor, schema: str, kind: str,
+                      pattern: str,
+                      limit: int) -> list[tuple[str, str, str, list[dict]]]:
+    pool = await accessor.pool()
+    async with pool.acquire() as conn:
+        if kind == "tables":
+            names = await _client.list_tables(conn, schema)
+        else:
+            views = await _client.list_views(conn, schema)
+            mviews = await _client.list_matviews(conn, schema)
+            names = sorted(set(views) | set(mviews))
+    out: list[tuple[str, str, str, list[dict]]] = []
+    for n in names:
+        rows = await search_entity(accessor, schema, kind, n, pattern, limit)
+        if rows:
+            out.append((schema, kind, n, rows))
+    return out
+
+
+async def search_schema(accessor: PostgresAccessor, schema: str, pattern: str,
+                        limit: int) -> list[tuple[str, str, str, list[dict]]]:
+    out: list[tuple[str, str, str, list[dict]]] = []
+    for kind in ("tables", "views"):
+        out.extend(await search_kind(accessor, schema, kind, pattern, limit))
+    return out
+
+
+async def search_database(
+        accessor: PostgresAccessor, pattern: str,
+        limit: int) -> list[tuple[str, str, str, list[dict]]]:
+    pool = await accessor.pool()
+    async with pool.acquire() as conn:
+        schemas = await _client.list_schemas(conn, accessor.config.schemas)
+    out: list[tuple[str, str, str, list[dict]]] = []
+    for s in schemas:
+        out.extend(await search_schema(accessor, s, pattern, limit))
+    return out
+
+
+def format_grep_results(
+        results: list[tuple[str, str, str, list[dict]]]) -> list[str]:
+    lines: list[str] = []
+    for schema, kind, entity, rows in results:
+        for r in rows:
+            line = orjson.dumps(r, default=str).decode()
+            lines.append(f"{schema}/{kind}/{entity}/rows.jsonl:{line}")
+    return lines

python/mirage/core/postgres/stat.py

@@ -0,0 +1,142 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import hashlib
+
+import orjson
+
+from mirage.accessor.postgres import PostgresAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.core.postgres import _client
+from mirage.core.postgres.scope import detect_scope
+from mirage.types import FileStat, FileType, PathSpec
+from mirage.utils.errors import enoent
+from mirage.utils.key_prefix import mount_key, mount_prefix_of
+
+
+async def stat(accessor: PostgresAccessor,
+               path: PathSpec,
+               index: IndexCacheStore = None) -> FileStat:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    prefix = mount_prefix_of(path.virtual, path.resource_path)
+    raw = path.virtual
+    if prefix and raw.startswith(prefix):
+        raw = raw[len(prefix):] or "/"
+    scope = detect_scope(
+        PathSpec(virtual=raw,
+                 directory=raw,
+                 resource_path=mount_key(raw, prefix)))
+
+    if scope.level == "root":
+        return FileStat(name="/", type=FileType.DIRECTORY)
+
+    if scope.level == "database_json":
+        return FileStat(name="database.json", type=FileType.JSON)
+
+    if scope.level == "schema":
+        if not await _schema_exists(accessor, scope.schema):
+            raise enoent(path)
+        return FileStat(name=scope.schema,
+                        type=FileType.DIRECTORY,
+                        extra={"schema": scope.schema})
+
+    if scope.level == "kind":
+        if not await _schema_exists(accessor, scope.schema):
+            raise enoent(path)
+        return FileStat(name=scope.kind,
+                        type=FileType.DIRECTORY,
+                        extra={
+                            "schema": scope.schema,
+                            "kind": scope.kind
+                        })
+
+    if scope.level == "entity":
+        if not await _entity_exists(accessor, scope.schema, scope.kind,
+                                    scope.entity):
+            raise enoent(path)
+        return FileStat(name=scope.entity,
+                        type=FileType.DIRECTORY,
+                        extra={
+                            "schema": scope.schema,
+                            "kind": scope.kind,
+                            "name": scope.entity
+                        })
+
+    if scope.level == "entity_schema":
+        if not await _entity_exists(accessor, scope.schema, scope.kind,
+                                    scope.entity):
+            raise enoent(path)
+        return FileStat(name="schema.json",
+                        type=FileType.JSON,
+                        extra={
+                            "schema": scope.schema,
+                            "kind": scope.kind,
+                            "name": scope.entity
+                        })
+
+    if scope.level == "entity_rows":
+        if not await _entity_exists(accessor, scope.schema, scope.kind,
+                                    scope.entity):
+            raise enoent(path)
+        return await _rows_stat(accessor, scope.schema, scope.kind,
+                                scope.entity)
+
+    raise enoent(path)
+
+
+async def _schema_exists(accessor: PostgresAccessor, schema: str) -> bool:
+    pool = await accessor.pool()
+    async with pool.acquire() as conn:
+        schemas = await _client.list_schemas(conn, accessor.config.schemas)
+    return schema in schemas
+
+
+async def _entity_exists(accessor: PostgresAccessor, schema: str, kind: str,
+                         entity: str) -> bool:
+    pool = await accessor.pool()
+    async with pool.acquire() as conn:
+        if kind == "tables":
+            names = await _client.list_tables(conn, schema)
+        else:
+            views = await _client.list_views(conn, schema)
+            mviews = await _client.list_matviews(conn, schema)
+            names = sorted(set(views) | set(mviews))
+    return entity in names
+
+
+async def _rows_stat(accessor: PostgresAccessor, schema: str, kind: str,
+                     entity: str) -> FileStat:
+    pool = await accessor.pool()
+    async with pool.acquire() as conn:
+        cols = await _client.fetch_columns(conn, schema, entity)
+        rows = await _client.estimated_row_count(conn, schema, entity)
+        size = await _client.table_size_bytes(conn, schema, entity)
+    fp_payload = orjson.dumps({"columns": cols, "rows": rows})
+    fingerprint = hashlib.sha256(fp_payload).hexdigest()
+    return FileStat(
+        name="rows.jsonl",
+        type=FileType.TEXT,
+        size=size,
+        fingerprint=fingerprint,
+        extra={
+            "schema": schema,
+            "kind": kind,
+            "name": entity,
+            "row_count": rows,
+            "size_bytes": size
+        },
+    )