@prostgles/prostgles 2.3.6-dev.1786548258

package/common/utils.ts

@@ -0,0 +1,525 @@
+import { isDefined } from "./filterUtils";
+import { DBSSchema, type DBSSchemaForInsert } from "./publishUtils";
+
+export const SECOND = 1000;
+export const MINUTE = SECOND * 60;
+export const HOUR = MINUTE * 60;
+export const DAY = HOUR * 24;
+export const MONTH = DAY * 30;
+export const YEAR = DAY * 365;
+
+export type AGE = {
+  years?: number;
+  months?: number;
+  days?: number;
+  hours?: number;
+  minutes?: number;
+  seconds?: number;
+  milliseconds?: number;
+};
+export type StrictOmit<T, K extends keyof T> = Omit<T, K>;
+
+export type ExtractBy<U, D extends keyof U, V extends U[D]> =
+  U extends any ?
+    D extends keyof U ?
+      U[D] extends V ? U
+      : V extends U[D] ? Omit<U, D> & Record<D, V>
+      : never
+    : never
+  : never;
+
+export const EXCLUDE_FROM_SCHEMA_WATCH =
+  "prostgles internal query that should be excluded from schema watch ";
+export const STATUS_MONITOR_IGNORE_QUERY = "prostgles-status-monitor-query";
+
+export const getAgeFromDiff = (millisecondDiff: number) => {
+  const roundFunc = millisecondDiff > 0 ? Math.floor : Math.ceil;
+
+  const years = roundFunc(millisecondDiff / YEAR);
+  const months = roundFunc((millisecondDiff % YEAR) / MONTH);
+  const days = roundFunc((millisecondDiff % MONTH) / DAY);
+  const hours = roundFunc((millisecondDiff % DAY) / HOUR);
+  const minutes = roundFunc((millisecondDiff % HOUR) / MINUTE);
+  const seconds = roundFunc((millisecondDiff % MINUTE) / SECOND);
+  const milliseconds = millisecondDiff % SECOND;
+
+  return { years, months, days, hours, minutes, seconds, milliseconds };
+};
+export const getAge = <ReturnALL extends boolean = false>(
+  date1: number,
+  date2: number,
+  returnAll?: ReturnALL,
+): ReturnALL extends true ? Required<AGE> : AGE => {
+  const diff = +date2 - +date1;
+  const roundFunc = diff > 0 ? Math.floor : Math.ceil;
+  const years = roundFunc(diff / YEAR);
+  const months = roundFunc(diff / MONTH);
+  const days = roundFunc(diff / DAY);
+  const hours = roundFunc(diff / HOUR);
+  const minutes = roundFunc(diff / MINUTE);
+  const seconds = roundFunc(diff / SECOND);
+
+  if (returnAll && returnAll === true) {
+    return getAgeFromDiff(diff);
+  }
+
+  if (years >= 1) {
+    return { years, months } as any;
+  } else if (months >= 1) {
+    return { months, days } as any;
+  } else if (days >= 1) {
+    return { days, hours } as any;
+  } else if (hours >= 1) {
+    return { hours, minutes } as any;
+  } else {
+    return { minutes, seconds } as any;
+  }
+};
+
+export const DESTINATIONS = [
+  { key: "Local", subLabel: "Saved locally (server in address bar)" },
+  { key: "Cloud", subLabel: "Saved to Amazon S3" },
+] as const;
+
+export type DumpOpts = DBSSchema["backups"]["options"];
+
+export type PGDumpParams = {
+  options: DumpOpts;
+  credentialID?: DBSSchema["backups"]["credential_id"];
+  destination: (typeof DESTINATIONS)[number]["key"];
+  initiator?: string;
+  name?: string;
+};
+
+export const DEFAULT_DUMP_OPTS: PGDumpParams = {
+  options: {
+    command: "pg_dump",
+    excludeSchema: "prostgles",
+    format: "c",
+    clean: true,
+    ifExists: true,
+    keepLogs: true,
+  },
+  destination: "Local",
+};
+
+export type RestoreOpts = DBSSchema["backups"]["restore_options"];
+
+export const DEFAULT_RESTORE_OPTS: RestoreOpts = {
+  clean: true,
+  create: false,
+  dataOnly: false,
+  noOwner: false,
+  command: "pg_restore",
+  excludeSchema: "prostgles",
+  ifExists: true,
+  format: "c",
+  keepLogs: false,
+};
+
+export type DeepWriteable<T> = {
+  -readonly [P in keyof T]: DeepWriteable<T[P]>;
+};
+type AnyObject = Record<string, any>;
+
+export type WithUndef<T extends AnyObject | undefined> =
+  T extends AnyObject ?
+    {
+      [K in keyof T]: T[K] | undefined;
+    }
+  : T;
+
+export type GetElementType<T extends any[] | readonly any[]> =
+  T extends (infer U)[] ? U : never;
+
+export type OmitDistributive<T, K extends keyof any> =
+  T extends any ? Omit<T, K> : never;
+
+export type PG_STAT_ACTIVITY = {
+  datid: number | null;
+  datname: string | null;
+  pid: number;
+  usesysid: number | null;
+  usename: string | null;
+  application_name: string;
+  client_addr: string | null;
+  client_hostname: string | null;
+  client_port: number | null;
+  backend_start: string;
+  xact_start: string | null;
+  query_start: string | null;
+  state_change: string | null;
+  wait_event_type: string | null;
+  wait_event: string | null;
+  state: string | null;
+  backend_xid: any | null;
+  backend_xmin: any | null;
+  query: string;
+  backend_type: string;
+  blocked_by: number[];
+  running_time: AnyObject;
+};
+
+export type PG_STAT_DATABASE = {
+  datid: number;
+  datname: string;
+  numbackends: number;
+  xact_commit: number;
+  xact_rollback: number;
+  blks_read: number;
+  blks_hit: number;
+  tup_returned: number;
+  tup_fetched: number;
+  tup_inserted: number;
+  tup_updated: number;
+  tup_deleted: number;
+  conflicts: number;
+  temp_files: number;
+  temp_bytes: number;
+  deadlocks: number;
+  checksum_failures: number | null;
+  checksum_last_failure: string | null;
+  blk_read_time: number;
+  blk_write_time: number;
+  stats_reset: string;
+};
+
+export type IOStats = {
+  majorNumber: number;
+  minorNumber: number;
+  deviceName: string;
+  readsCompletedSuccessfully: number;
+  readsMerged: number;
+  sectorsRead: number;
+  timeSpentReadingMs: number;
+  writesCompleted: number;
+  writesMerged: number;
+  sectorsWritten: number;
+  timeSpentWritingMs: number;
+  IOsCurrentlyInProgress: number;
+  timeSpentDoingIOms: number;
+  weightedTimeSpentDoingIOms: number;
+};
+
+export type ServerStatus = {
+  clock_ticks: number;
+  total_memoryKb: number;
+  free_memoryKb: number;
+  uptimeSeconds: number;
+  cpu_model: string;
+  cpu_cores_mhz: string;
+  cpu_mhz: string;
+  disk_space: string;
+  memAvailable: number;
+  ioInfo?: IOStats[];
+};
+
+export type ConnectionStatus = {
+  queries: PG_STAT_ACTIVITY[];
+  topQueries: AnyObject[];
+  blockedQueries: AnyObject[];
+  connections: PG_STAT_DATABASE[];
+  maxConnections: number;
+  noBash: boolean;
+  getPidStatsErrors: Partial<Record<string, any>>;
+  serverStatus?: ServerStatus;
+};
+
+export type SampleSchema = {
+  name: string;
+  path: string;
+} & (
+  | {
+      type: "sql";
+      file: string;
+    }
+  | SampleSchemaDir
+);
+export type SampleSchemaDir = {
+  type: "dir";
+  tableConfigTs: string;
+  onMountTs: string;
+  onInitSQL: string;
+  workspaceConfig:
+    | { workspaces: DBSSchemaForInsert["workspaces"][] }
+    | undefined;
+  connection:
+    | Pick<
+        DBSSchema["connections"],
+        "db_schema_filter" | "info" | "table_options"
+      >
+    | undefined;
+  databaseConfig:
+    | Pick<
+        DBSSchema["database_configs"],
+        "table_schema_positions" | "table_schema_transform"
+      >
+    | undefined;
+};
+
+export type ProcStats = {
+  pid: number;
+  cpu: number;
+  mem: number;
+  uptime: number;
+};
+
+export function matchObj(
+  obj1: AnyObject | undefined,
+  obj2: AnyObject | undefined,
+): boolean {
+  if (obj1 && obj2) {
+    return !Object.keys(obj1).some((k) => obj1[k] !== obj2[k]);
+  }
+  return false;
+}
+
+export function sliceText<T extends string | undefined>(
+  _text: T,
+  maxLen: number,
+  ellipseText = "...",
+  midEllipse = false,
+): T {
+  const text = _text as string;
+  if (isDefined(text) && text.length > maxLen) {
+    if (!midEllipse) return `${text.slice(0, maxLen)}${ellipseText}` as T;
+    return `${text.slice(0, maxLen / 2)}${ellipseText}${text.slice(text.length - maxLen / 2 + 3)}` as T;
+  }
+
+  return _text;
+}
+
+export type ColType = {
+  table_oid: number | undefined;
+  column_name: string;
+  escaped_column_name: string;
+  data_type: string;
+  udt_name: string;
+  schema: string;
+};
+export const RELOAD_NOTIFICATION = "Prostgles UI accessible at";
+
+export function throttle<Params extends any[]>(
+  func: (...args: Params) => any,
+  timeout: number,
+): (...args: Params) => void {
+  //@ts-ignore
+  let timer: NodeJS.Timeout | undefined;
+  let lastCallArgs: Params | undefined;
+  const throttledFunc = (...args: Params) => {
+    if (timer !== undefined) {
+      lastCallArgs = args;
+      return;
+    } else {
+      lastCallArgs = undefined;
+    }
+    //@ts-ignore
+    timer = setTimeout(() => {
+      func(...args);
+      timer = undefined;
+      if (lastCallArgs) {
+        throttledFunc(...lastCallArgs);
+      }
+    }, timeout);
+  };
+  return throttledFunc;
+}
+
+export const SPOOF_TEST_VALUE = "trustme";
+
+export const getEntries = <T extends AnyObject>(obj: T) =>
+  Object.entries(obj) as [keyof T, T[keyof T]][];
+
+export const fromEntries = <K extends string | number | symbol, V>(
+  entries: readonly (readonly [K, V])[],
+): Record<K, V> => {
+  return Object.fromEntries(entries) as Record<K, V>;
+};
+export const CONNECTION_CONFIG_SECTIONS = [
+  "authentication",
+  "access_control",
+  "backups",
+  "table_config",
+  "details",
+  "status",
+  "methods",
+  "file_storage",
+  "API",
+  "webApp",
+  "security",
+  "config",
+] as const;
+
+export const SERVER_SETTINGS_SECTIONS = [
+  "security",
+  "auth",
+  "cloud",
+  "mcpServers",
+  "llmProviders",
+  "services",
+] as const;
+
+/**
+ * Ensure that multi-line strings are indented correctly
+ */
+export const fixIndent = (_str: string | TemplateStringsArray): string => {
+  const str = typeof _str === "string" ? _str : (_str[0] ?? "");
+  const lines = str.split("\n");
+  if (!lines.some((l) => l.trim())) return str;
+  let minIdentOffset = lines.reduce(
+    (a, line) => {
+      if (!line.trim()) return a;
+      const indent = line.length - line.trimStart().length;
+      return Math.min(a ?? indent, indent);
+    },
+    undefined as number | undefined,
+  );
+  minIdentOffset = Math.max(minIdentOffset ?? 0, 0);
+
+  return lines
+    .map((l, i) => (i === 0 ? l : l.slice(minIdentOffset)))
+    .join("\n")
+    .trim();
+};
+
+export const getConnectionApiPaths = ({
+  id,
+  url_path,
+  port,
+  is_state_db,
+}: Pick<
+  DBSSchema["connections"],
+  "id" | "url_path" | "port" | "is_state_db"
+>) => {
+  const { REST, WS_DB } = API_ENDPOINTS;
+  return {
+    rest: port && !is_state_db ? REST : `${REST}/${url_path || id}`,
+    ws: port && !is_state_db ? WS_DB : `${WS_DB}/${url_path || id}`,
+  };
+};
+export const getConnectionPaths = (
+  { id }: Pick<DBSSchema["connections"], "id">,
+  sectionName?: string,
+) => {
+  const ending = sectionName ? `${id}?section=${sectionName}` : id;
+  return {
+    dashboard: `${ROUTES.CONNECTIONS}/${ending}`,
+    config: `${ROUTES.CONFIG}/${ending}`,
+    webAppTests: `${ROUTES.PLAYWRIGHT_REPORT}/${ending}`,
+  };
+};
+
+export const API_ENDPOINTS = {
+  REST: "/rest-api",
+  WS_DB: "/ws-api",
+  WS_DBS: "/ws-api-dbs",
+  MAGIC_LINK: "/magic-link",
+  DBS: "/dbs",
+} as const;
+
+export const ROUTES = {
+  LOGIN: "/login",
+  LOGOUT: "/logout",
+  ACCOUNT: "/account",
+  CONNECTIONS: "/connections",
+  CONFIG: "/connection-config",
+  DOCUMENTATION: "/documentation",
+  SERVER_SETTINGS: "/server-settings",
+  COMPONENT_LIST: "/component-list",
+  EDIT_CONNECTION: "/edit-connection",
+  NEW_CONNECTION: "/new-connection",
+  USERS: "/users",
+  BACKUPS: "/prostgles_backups",
+  STORAGE: "/prostgles_storage",
+  PLAYWRIGHT_REPORT: "/playwright-report",
+  MCP_OAUTH_CALLBACK: "/mcp-oauth-callback",
+} as const;
+
+const testForDuplicateValues = <T extends AnyObject>(obj: T, name: string) => {
+  if (new Set(Object.values(obj)).size !== Object.keys(obj).length) {
+    throw new Error(
+      `${name} must not have duplicate values: ${Object.values(obj)}`,
+    );
+  }
+};
+testForDuplicateValues(API_ENDPOINTS, "API_ENDPOINTS");
+testForDuplicateValues(ROUTES, "ROUTES");
+
+export const PROSTGLES_CLOUD_URL = "https://cloud1.prostgles.com";
+
+export const FORKED_PROC_ENV_NAME = "IS_FORKED_PROC" as const;
+
+export function debouncePromise<Args extends any[], T>(
+  promiseFuncDef: (...pArgs: Args) => Promise<T>,
+): (...args: Args) => Promise<T> {
+  let currentPromise: Promise<any> | undefined;
+
+  return function (...args: Args): Promise<T> {
+    // If there's no active promise, create a new one
+    if (!currentPromise) {
+      currentPromise = promiseFuncDef(...args).finally(() => {
+        currentPromise = undefined;
+      });
+      return currentPromise;
+    }
+
+    // Otherwise, wait for the current promise to finish, then run the new one
+    return currentPromise.then(() => promiseFuncDef(...args));
+  };
+}
+
+export const getCaller = () => {
+  //@ts-ignore
+  // Error.stackTraceLimit = 30;
+
+  const error = new Error();
+  const stackLines = error.stack?.split("\n") ?? [];
+  const callerLine = stackLines[2] ?? "";
+  return stackLines;
+};
+
+//TODO: add file table column info to prostgles-types
+export type FileTable = {
+  original_name: string;
+};
+
+export const getProperty = <T extends object, K extends string>(
+  obj: T,
+  key: K | string,
+): K extends keyof T ? T[K]
+: K extends string ? T[keyof T] | undefined
+: undefined => {
+  if (!Object.keys(obj).includes(key))
+    return undefined as K extends keyof T ? T[K] : undefined;
+  return obj[key as keyof T] as K extends keyof T ? T[K] : undefined;
+};
+
+type OptionalKeys<T> = {
+  [K in keyof T]-?: {} extends Pick<T, K> ? K : never;
+}[keyof T];
+
+type RequiredKeys<T> = Exclude<keyof T, OptionalKeys<T>>;
+
+type Simplify<T> = { [K in keyof T]: T[K] };
+
+export type RequiredKeepUndefined<T> = Simplify<
+  { [K in RequiredKeys<T>]: T[K] } & {
+    [K in OptionalKeys<T>]: T[K] | undefined;
+  }
+>;
+
+export const getRandomElement = <Arr>(
+  items: Arr[],
+): { elem: Arr; index: number } => {
+  const randomIndex = Math.floor(Math.random() * items.length);
+  return { elem: items[randomIndex]!, index: randomIndex };
+};
+
+/**
+ * TODO: find a compile time solution
+ */
+export const tableMightBeUndefinedDueToAccessControl = <T>(
+  tableHandler: T,
+): Partial<T> | undefined => {
+  return tableHandler;
+};

package/docker-compose.yml

@@ -0,0 +1,99 @@
+name: prostgles
+
+# Define reusable blocks
+x-ui-environment: &ui-environment
+  POSTGRES_HOST: db
+  POSTGRES_DB: ${POSTGRES_DB}
+  POSTGRES_USER: ${POSTGRES_USER}
+  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+  PROSTGLES_UI_HOST: "0.0.0.0"
+  PROSTGLES_DATA_DIR: /var/lib/prostgles
+
+x-ui-base: &ui-base
+  image: prostgles/ui:v2.3.5
+  restart: unless-stopped
+  build:
+    context: .
+    dockerfile: Dockerfile
+  environment:
+    <<: *ui-environment
+  depends_on:
+    db:
+      condition: service_healthy
+  command: node /usr/src/app/server/dist/server/src/index.js
+  volumes:
+    - ui-data:/var/lib/prostgles
+
+services:
+  db:
+    image: prostgles/ui-db:v2.3.5
+    container_name: prostgles-ui-db
+    restart: unless-stopped
+    build:
+      context: .
+      dockerfile: DB.Dockerfile 
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB}
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+    command: >
+      postgres 
+      -c shared_preload_libraries=pg_stat_statements  
+      -c max_connections=200
+    volumes:
+      - db:/var/lib/postgresql/data
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          "sleep 1 && pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}",
+        ]
+      timeout: 3s
+      retries: 5
+
+  # Default UI service (default profile)
+  ui:
+    profiles: ["default", ""]
+    <<: *ui-base
+    container_name: prostgles-ui-default
+    ports:
+      - "${PRGL_DOCKER_IP:-127.0.0.1}:${PRGL_DOCKER_PORT:-3004}:3004"
+
+  # Debug profile - extends base with Node.js inspector
+  ui-debug:
+    profiles: ["debug"]
+    <<: *ui-base
+    container_name: prostgles-ui-debug
+    command: node --inspect=0.0.0.0:9229 /usr/src/app/server/dist/server/src/index.js
+    ports:
+      - "${PRGL_DOCKER_IP:-127.0.0.1}:${PRGL_DOCKER_PORT:-3004}:3004"
+      - "${PRGL_DOCKER_IP:-127.0.0.1}:9229:9229"
+
+  # Docker MCP profile - extends base with Docker capabilities
+  ui-docker-mcp:
+    profiles: ["docker-mcp"]
+    <<: *ui-base
+    container_name: prostgles-ui-docker-mcp
+    environment:
+      <<: *ui-environment
+      DOCKER_HOST: unix:///var/run/docker.sock
+    ports:
+      - "${PRGL_DOCKER_IP:-127.0.0.1}:${PRGL_DOCKER_PORT:-3004}:3004"
+      - "${PRGL_DOCKER_IP:-127.0.0.1}:3089:3089"
+    volumes:
+      - ui-data:/var/lib/prostgles
+      - /var/run/docker.sock:/var/run/docker.sock
+      - /usr/bin/docker:/usr/bin/docker:ro
+
+volumes:
+  db:
+  ui-data:
+# Used for docker mcp
+networks:
+  default:
+    name: prostgles-bridge-net
+    driver: bridge
+  internal-bridge:
+    name: prostgles-bridge-internal-net
+    driver: bridge
+    internal: true

package/docs/01_Overview.md

@@ -0,0 +1,25 @@
+<h1 id="overview"> Overview </h1> 
+
+Prostgles UI is a user-friendly way for interacting with PostgreSQL, creating dashboards and internal tools.
+
+<img src="./screenshots/overview.svgif.svg" alt="Prostgles UI Overview" width="100%" style="border: 1px solid; margin: 1em 0;" />
+
+## Features
+- SQL editor with syntax highlighting and auto-completion
+- Real-time dashboards and charts
+- AI assistant with MCP support and agentic workflows
+- User authentication (email, third-party OAuth and two-factor authentication)
+- Role-based access control
+- Database management
+- File storage and backups (locally or to AWS S3 compatible storage)
+- TypeScript API with database schema types and end to end type safety
+- LISTEN NOTIFY support
+- Mobile friendly
+
+It comes in two versions: 
+- **Prostgles UI** - Web-based app with the full feature set, accessible from modern browsers.
+- **Prostgles Desktop** - Electron-based app for Linux, macOS, and Windows, focused on data exploration and database management.
+
+Note: Multi-user features such as User Management are not available in the desktop version.
+
+

package/docs/02_Installation_(Docker).md

@@ -0,0 +1,37 @@
+<h1 id="installation_(docker)"> Installation (Docker) </h1> 
+
+The quickest way to start is with Docker. 
+If you don't have Docker installed, please follow the official 
+<a href="https://docs.docker.com/engine/install/" target="_blank">Docker installation guide</a>
+
+Download the source code:
+
+```bash
+git clone https://github.com/prostgles/ui.git
+cd ui
+```
+
+Start the application:
+
+```docker-compose.sh
+docker compose up -d --build
+``` 
+
+Once running, Prostgles UI will be available at [localhost:3004](http://localhost:3004)
+
+### Initial Setup & Authentication
+
+When first launching Prostgles UI, an admin user will be created automatically:
+- If `PRGL_USERNAME` and `PRGL_PASSWORD` environment variables are provided, an admin user is created with these credentials. 
+- Otherwise, a passwordless admin user is created. 
+It gets assigned to the first client that accesses the app. 
+Subsequent clients accessing the app will be rejected with an appropriate error message detailing that the passwordless admin user has already been assigned.
+
+To setup multiple users, the passwordless admin user must be converted to a normal admin account by setting up a password.
+This will allow accessing /users page where you can manage users.
+
+Users login using their username and password. Two-factor authentication is provided through TOTP (Time-based One-Time Password) and can be enabled in the account section.
+
+Email and third-party (OAuth) authentication can be configured in Server Settings section. It allows users to register and log in using their email address or third-party accounts like Google, GitHub, etc.
+
+

package/docs/03_Installation_(Desktop_Version).md

@@ -0,0 +1,27 @@
+<h1 id="installation_(desktop_version)"> Installation (Desktop Version) </h1> 
+
+To get started with Prostgles Desktop, download and install the binary file that's appropriate for your operating system (Windows, macOS, or Linux) from [our website](/download).
+
+- **Linux**: We provide **.deb**, **.rpm** or **.AppImage** files to suit your distribution,
+- **macOS**: Open the downloaded **.dmg** file, drag the Prostgles Desktop icon into your Applications folder, and launch the application.
+- **Windows** - Run the downloaded **.exe** file and follow the on-screen instructions to complete the installation.
+
+Alternatively, you can visit the [releases page](https://github.com/prostgles/ui/releases) for checksums, release notes or older versions.
+
+## Setting up
+
+When you open Prostgles Desktop, you see the Welcome screen while it loads.
+You'll need to complete two initial setup steps:
+
+1. Accept the privacy policy
+2. Connect to a state database
+
+#### State database
+
+Prostgles Desktop stores its state and configuration data in a PostgreSQL database.
+To maintain a secure and responsive environment, we highly recommend [installing Postgres](https://www.postgresql.org/download/) on your local machine.
+You will need to create a dedicated database and superuser account with a strong password for Prostgles Desktop.
+
+<img src="./screenshots/electron_setup.svgif.svg" alt="Electron Setup" style="border: 1px solid; margin: 1em 0;" />
+
+