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, and RPC functions
• Handles PostgreSQL array types (TEXT[] → string[])
• Multi-word types (character varying, double precision, timestamp with time zone)
• Supports SSH key and password authentication
• Uploads the generator to the server, runs it there, downloads the result, and cleans up
• 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. Uploads a self-contained generator script to the server via SCP
3. SSHs in and runs it — the script calls pg_dump on the Docker container
4. Parses the SQL schema into TypeScript types (tables, views, functions)
5. Downloads the generated file to your chosen output path
6. Cleans up all remote files

The generator runs on the server because it needs direct access to the Docker container running PostgreSQL. No ports need to be exposed beyond SSH.

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. |

Requirements

• Node.js >= 18
• 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