chore: ZXDB env validation, MySQL setup, API & UI

This sanity commit wires up the initial ZXDB integration and a minimal UI to explore it.

Key changes:
- Add Zod-based env parsing (`src/env.ts`) validating `ZXDB_URL` as a mysql:// URL (t3.gg style).
- Configure Drizzle ORM with mysql2 connection pool (`src/server/db.ts`) driven by `ZXDB_URL`.
- Define minimal ZXDB schema models (`src/server/schema/zxdb.ts`): `entries` and helper `search_by_titles`.
- Implement repository search with pagination using helper table (`src/server/repo/zxdb.ts`).
- Expose Next.js API route `GET /api/zxdb/search` with Zod query validation and Node runtime (`src/app/api/zxdb/search/route.ts`).
- Create new app section “ZXDB Explorer” at `/zxdb` with search UI, results table, and pagination (`src/app/zxdb/*`).
- Add navbar link to ZXDB (`src/components/Navbar.tsx`).
- Update example.env with readonly-role notes and example `ZXDB_URL`.
- Add drizzle-kit config scaffold (`drizzle.config.ts`).
- Update package.json deps: drizzle-orm, mysql2, zod; devDeps: drizzle-kit. Lockfile updated.
- Extend .gitignore to exclude large ZXDB structure dump.

Notes:
- Ensure ZXDB data and helper tables are loaded (see `ZXDB/scripts/ZXDB_help_search.sql`).
- This commit provides structure-only browsing; future work can enrich schema (authors, labels, publishers) and UI filters.

Signed-off-by: Junie@lucy.xalior.com

.gitignore

@@ -44,3 +44,4 @@ next-env.d.ts
 # PNPM build artifacts
 .pnpm 
 .pnpm-store
+ZXDB/ZXDB_mysql_STRUCTURE_ONLY.sql

drizzle.config.ts

@@ -0,0 +1,14 @@
+import type { Config } from "drizzle-kit";
+
+// This configuration is optional at the moment (no migrations run here),
+// but kept for future schema generation if needed.
+
+export default {
+  schema: "./src/server/schema/**/*.ts",
+  out: "./drizzle",
+  driver: "mysql2",
+  dbCredentials: {
+    // Read from env at runtime when using drizzle-kit
+    url: process.env.ZXDB_URL!,
+  },
+} satisfies Config;

example.env

@@ -1 +1,5 @@
-ZXDB_URL=mysql://username:password@hostname:3306/zxdb_imported_db
+# ZXDB MySQL connection URL
+# Example using a readonly user created by ZXDB scripts
+# CREATE ROLE 'zxdb_readonly';
+# GRANT SELECT, SHOW VIEW ON `zxdb`.* TO 'zxdb_readonly';
+ZXDB_URL=mysql://zxdb_readonly:password@hostname:3306/zxdb

package.json

@@ -17,7 +17,10 @@
     "react-bootstrap": "^2.10.10",
     "react-bootstrap-icons": "^1.11.6",
     "react-dom": "19.1.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "drizzle-orm": "^0.36.1",
+    "mysql2": "^3.12.0",
+    "zod": "^3.23.8"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.3",
@@ -26,6 +29,7 @@
     "@types/react-dom": "^19.2.3",
     "eslint": "^9.39.1",
     "eslint-config-next": "15.5.4",
-    "sass": "^1.94.2"
+    "sass": "^1.94.2",
+    "drizzle-kit": "^0.30.1"
   }
 }

src/app/api/zxdb/search/route.ts

@@ -0,0 +1,31 @@
+import { NextRequest } from "next/server";
+import { z } from "zod";
+import { searchEntries } from "@/server/repo/zxdb";
+
+const querySchema = z.object({
+  q: z.string().optional(),
+  page: z.coerce.number().int().positive().optional(),
+  pageSize: z.coerce.number().int().positive().max(100).optional(),
+});
+
+export async function GET(req: NextRequest) {
+  const { searchParams } = new URL(req.url);
+  const parsed = querySchema.safeParse({
+    q: searchParams.get("q") ?? undefined,
+    page: searchParams.get("page") ?? undefined,
+    pageSize: searchParams.get("pageSize") ?? undefined,
+  });
+  if (!parsed.success) {
+    return new Response(
+      JSON.stringify({ error: parsed.error.flatten() }),
+      { status: 400, headers: { "content-type": "application/json" } }
+    );
+  }
+  const data = await searchEntries(parsed.data);
+  return new Response(JSON.stringify(data), {
+    headers: { "content-type": "application/json" },
+  });
+}
+
+// Ensure Node.js runtime (required for mysql2)
+export const runtime = "nodejs";

src/app/zxdb/ZxdbExplorer.tsx

@@ -0,0 +1,132 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+
+type Item = {
+  id: number;
+  title: string;
+  isXrated: number;
+  machinetypeId: number | null;
+  languageId: string | null;
+};
+
+type Paged<T> = {
+  items: T[];
+  page: number;
+  pageSize: number;
+  total: number;
+};
+
+export default function ZxdbExplorer() {
+  const [q, setQ] = useState("");
+  const [page, setPage] = useState(1);
+  const [loading, setLoading] = useState(false);
+  const [data, setData] = useState<Paged<Item> | null>(null);
+
+  const pageSize = 20;
+  const totalPages = useMemo(() => (data ? Math.max(1, Math.ceil(data.total / data.pageSize)) : 1), [data]);
+
+  async function fetchData(query: string, p: number) {
+    setLoading(true);
+    try {
+      const params = new URLSearchParams();
+      if (query) params.set("q", query);
+      params.set("page", String(p));
+      params.set("pageSize", String(pageSize));
+      const res = await fetch(`/api/zxdb/search?${params.toString()}`);
+      if (!res.ok) throw new Error(`Failed: ${res.status}`);
+      const json: Paged<Item> = await res.json();
+      setData(json);
+    } catch (e) {
+      // eslint-disable-next-line no-console
+      console.error(e);
+      setData({ items: [], page: 1, pageSize, total: 0 });
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  useEffect(() => {
+    fetchData(q, page);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [page]);
+
+  function onSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    setPage(1);
+    fetchData(q, 1);
+  }
+
+  return (
+    <div className="container">
+      <h1 className="mb-3">ZXDB Explorer</h1>
+      <form className="row gy-2 gx-2 align-items-center" onSubmit={onSubmit}>
+        <div className="col-sm-8 col-md-6 col-lg-4">
+          <input
+            type="text"
+            className="form-control"
+            placeholder="Search titles..."
+            value={q}
+            onChange={(e) => setQ(e.target.value)}
+          />
+        </div>
+        <div className="col-auto">
+          <button className="btn btn-primary" type="submit" disabled={loading}>Search</button>
+        </div>
+        {loading && (
+          <div className="col-auto text-secondary">Loading...</div>
+        )}
+      </form>
+
+      <div className="mt-3">
+        {data && data.items.length === 0 && !loading && (
+          <div className="alert alert-warning">No results.</div>
+        )}
+        {data && data.items.length > 0 && (
+          <div className="table-responsive">
+            <table className="table table-striped table-hover align-middle">
+              <thead>
+                <tr>
+                  <th style={{width: 80}}>ID</th>
+                  <th>Title</th>
+                  <th style={{width: 120}}>Machine</th>
+                  <th style={{width: 80}}>Lang</th>
+                </tr>
+              </thead>
+              <tbody>
+                {data.items.map((it) => (
+                  <tr key={it.id}>
+                    <td>{it.id}</td>
+                    <td>{it.title}</td>
+                    <td>{it.machinetypeId ?? "-"}</td>
+                    <td>{it.languageId ?? "-"}</td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        )}
+      </div>
+
+      <div className="d-flex align-items-center gap-2 mt-2">
+        <button
+          className="btn btn-outline-secondary"
+          onClick={() => setPage((p) => Math.max(1, p - 1))}
+          disabled={loading || page <= 1}
+        >
+          Prev
+        </button>
+        <span>
+          Page {data?.page ?? page} / {totalPages}
+        </span>
+        <button
+          className="btn btn-outline-secondary"
+          onClick={() => setPage((p) => p + 1)}
+          disabled={loading || (data ? data.page >= totalPages : false)}
+        >
+          Next
+        </button>
+      </div>
+    </div>
+  );
+}

src/app/zxdb/page.tsx

@@ -0,0 +1,9 @@
+import ZxdbExplorer from "./ZxdbExplorer";
+
+export const metadata = {
+  title: "ZXDB Explorer",
+};
+
+export default function Page() {
+  return <ZxdbExplorer />;
+}

src/components/Navbar.tsx

@@ -15,6 +15,7 @@ export default function NavbarClient() {
                     <Nav className="me-auto mb-2 mb-lg-0">
                         <Link className="nav-link" href="/">Home</Link>
                         <Link className="nav-link" href="/registers">Registers</Link>
+                        <Link className="nav-link" href="/zxdb">ZXDB</Link>
                     </Nav>
 
                     <ThemeDropdown />

src/env.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+
+// Server-side environment schema (t3.gg style)
+const serverSchema = z.object({
+  // Full MySQL connection URL, e.g. mysql://user:pass@host:3306/zxdb
+  ZXDB_URL: z
+    .string()
+    .url()
+    .refine((s) => s.startsWith("mysql://"), {
+      message: "ZXDB_URL must be a valid mysql:// URL",
+    }),
+});
+
+function formatErrors(errors: z.ZodFormattedError<Map<string, string>, string>) {
+  return Object.entries(errors)
+    .map(([name, value]) => {
+      if (value && "_errors" in value) {
+        return `${name}: ${(value as any)._errors.join(", ")}`;
+      }
+      return `${name}: invalid`;
+    })
+    .join("\n");
+}
+
+const parsed = serverSchema.safeParse(process.env);
+if (!parsed.success) {
+  // Fail fast with helpful output in server context
+  // eslint-disable-next-line no-console
+  console.error("❌ Invalid environment variables:\n" + formatErrors(parsed.error.format()));
+  throw new Error("Invalid environment variables");
+}
+
+export const env = parsed.data;

src/server/db.ts

@@ -0,0 +1,15 @@
+import mysql from "mysql2/promise";
+import { drizzle } from "drizzle-orm/mysql2";
+import { env } from "@/env";
+
+// Create a singleton connection pool for the ZXDB database
+const pool = mysql.createPool({
+  uri: env.ZXDB_URL,
+  connectionLimit: 10,
+  // Larger queries may be needed for ZXDB
+  maxPreparedStatements: 256,
+});
+
+export const db = drizzle(pool);
+
+export type Db = typeof db;

src/server/repo/zxdb.ts

@@ -0,0 +1,74 @@
+import { and, desc, eq, like, sql } from "drizzle-orm";
+import { db } from "@/server/db";
+import { entries, searchByTitles } from "@/server/schema/zxdb";
+
+export interface SearchParams {
+  q?: string;
+  page?: number; // 1-based
+  pageSize?: number; // default 20
+}
+
+export interface SearchResultItem {
+  id: number;
+  title: string;
+  isXrated: number;
+  machinetypeId: number | null;
+  languageId: string | null;
+}
+
+export interface PagedResult<T> {
+  items: T[];
+  page: number;
+  pageSize: number;
+  total: number;
+}
+
+export async function searchEntries(params: SearchParams): Promise<PagedResult<SearchResultItem>> {
+  const q = (params.q ?? "").trim();
+  const pageSize = Math.max(1, Math.min(params.pageSize ?? 20, 100));
+  const page = Math.max(1, params.page ?? 1);
+  const offset = (page - 1) * pageSize;
+
+  if (q.length === 0) {
+    // Default listing: return first page by id desc (no guaranteed ordering field; using id)
+    const [items, [{ total }]] = await Promise.all([
+      db.select().from(entries).orderBy(desc(entries.id)).limit(pageSize).offset(offset),
+      db.execute(sql`select count(*) as total from ${entries}`) as Promise<any>,
+    ]);
+    return {
+      items: items as any,
+      page,
+      pageSize,
+      total: Number((total as any) ?? 0),
+    };
+  }
+
+  const pattern = `%${q.toLowerCase().replace(/[^a-z0-9]+/g, "")}%`;
+
+  // Count matches via helper table
+  const countRows = await db
+    .select({ total: sql<number>`count(distinct ${searchByTitles.entryId})` })
+    .from(searchByTitles)
+    .where(like(searchByTitles.entryTitle, pattern));
+
+  const total = Number(countRows[0]?.total ?? 0);
+
+  // Items using join to entries, distinct entry ids
+  const items = await db
+    .select({
+      id: entries.id,
+      title: entries.title,
+      isXrated: entries.isXrated,
+      machinetypeId: entries.machinetypeId,
+      languageId: entries.languageId,
+    })
+    .from(searchByTitles)
+    .innerJoin(entries, eq(entries.id, searchByTitles.entryId))
+    .where(like(searchByTitles.entryTitle, pattern))
+    .groupBy(entries.id)
+    .orderBy(entries.title)
+    .limit(pageSize)
+    .offset(offset);
+
+  return { items: items as any, page, pageSize, total };
+}

src/server/schema/zxdb.ts

@@ -0,0 +1,18 @@
+import { mysqlTable, int, varchar, tinyint, char } from "drizzle-orm/mysql-core";
+
+// Minimal subset needed for browsing/searching
+export const entries = mysqlTable("entries", {
+  id: int("id").notNull().primaryKey(),
+  title: varchar("title", { length: 250 }).notNull(),
+  isXrated: tinyint("is_xrated").notNull(),
+  machinetypeId: tinyint("machinetype_id"),
+  languageId: char("language_id", { length: 2 }),
+});
+
+// Helper table created by ZXDB_help_search.sql
+export const searchByTitles = mysqlTable("search_by_titles", {
+  entryTitle: varchar("entry_title", { length: 250 }).notNull(),
+  entryId: int("entry_id").notNull(),
+});
+
+export type Entry = typeof entries.$inferSelect;