supatypes

Generate TypeScript types from a remote Supabase PostgreSQL database via SSH.

Connects to your server, dumps the database schema, parses tables/views/functions, and generates a fully typed database.types.ts file — all in one command.

Features

• Generates types for tables, views, enums, foreign-key relationships, and RPC functions
• Handles PostgreSQL array types (TEXT[] → string[]), including arrays of enums
• Correct nullability and Insert-optionality for columns with DEFAULT, IDENTITY, or GENERATED
• Supports SSH key and password authentication
• Runs entirely over SSH — introspects the database via docker exec … psql and generates types locally (nothing installed or uploaded server-side beyond Docker)
• Config file so you only set up once per project

Install

# Global
npm install -g supatypes

# Per project
npm install --save-dev supatypes

Quick start

# 1. Create config file
npx supatypes init

# 2. Generate types
npx supatypes generate

Configuration

Running init creates a .supatypes.json file:

{
  "server": "[email protected]",
  "sshPort": 2222,
  "sshKey": "~/.ssh/id_rsa",
  "dbContainer": "supabase-db-abc123",
  "output": "./database.types.ts"
}

Options

| Field | Required | Description | |-------|----------|-------------| | server | Yes | SSH connection string (e.g. [email protected]) | | sshPort | No | SSH port (default: 22) | | sshKey | One of these | Path to SSH private key | | sshPassword | One of these | SSH password (uses sshpass) | | dbContainer | Yes | Docker container name for the Supabase PostgreSQL instance | | output | No | Output file path (default: ./database.types.ts) |

The config file is automatically added to .gitignore since it may contain server credentials.

CLI

# Generate with default config
npx supatypes generate

# Custom config file
npx supatypes generate -c ./config/typegen.json

# Override output path
npx supatypes generate -o ./src/types/database.ts

# Preview what would happen
npx supatypes generate --dry-run

How it works

1. Reads your .supatypes.json config
2. SSHs in and runs a handful of introspection queries against pg_catalog / information_schema, piping each one over stdin into docker exec -i <container> psql — nothing is uploaded to the server
3. Builds TypeScript types locally from the introspected schema (tables, views, enums, relationships, functions)
4. Writes the generated file to your chosen output path

Queries run inside the Docker container over SSH because that's where PostgreSQL lives — no ports need to be exposed beyond SSH, and the server needs nothing installed beyond Docker (no Node, no uploaded scripts, no temp files to clean up).

Type mapping

| PostgreSQL | TypeScript | |-----------|-----------| | text, varchar, char, uuid | string | | integer, bigint, serial, real, numeric | number | | boolean | boolean | | jsonb, json | Json | | timestamptz, date, time | string | | text[], integer[], etc. | string[], number[], etc. | | CREATE TYPE … AS ENUM (…) | Literal union (e.g. "free" \| "starter" \| "pro") and referenced via Database["public"]["Enums"]["…"] on columns |

Requirements

• Node.js >= 18 (on your machine — not required on the server)
• SSH access to the server running Supabase
• sshpass installed locally (only if using password auth)
• Docker must be accessible on the server (the SSH user needs docker permissions)

Licence

MIT