Title: __InternalSupabase type breaks generic database constraints for third-party libraries

[jordanburke]

Describe the bug

The generated Database types include an __InternalSupabase property that doesn't conform to the schema structure:

// Generated database.types.ts
export type Database = {
  public: {
    Tables: { ... }
    Views: { ... }
    // etc.
  }
  __InternalSupabase: {
    PostgrestVersion: "12.2.3 (519615d)"
  }
}

The __InternalSupabase object has PostgrestVersion but no Tables, Views, etc. This breaks generic constraints for libraries that want to accept any valid Database type.

Library affected

supabase-js

Reproduction

No response

Steps to reproduce

// Library code trying to accept any Supabase Database type
interface SchemaDefinition {
  Tables: Record<string, { Row: object; Insert: object; Update: object }>
  Views?: Record<string, { Row: object }>
  // etc.
}

interface DatabaseSchema {
  public: SchemaDefinition
  [schemaName: string]: SchemaDefinition  // Index signature
}

// This fails because __InternalSupabase doesn't have Tables
function query<DB extends DatabaseSchema>(client: SupabaseClient<DB>) { ... }

Error:

Type 'Database' does not satisfy the constraint 'DatabaseSchema'.
Property '__InternalSupabase' is incompatible with index signature.
Property 'Tables' is missing in type '{ PostgrestVersion: "12.2.3 (519615d)"; }'

Expected behavior

Third-party libraries should be able to define generic constraints on database types without workarounds.

Current workaround

We use Omit<Database, '__InternalSupabase'> everywhere (same pattern as in SupabaseClient source), but this:

1. Requires every library to know about this internal implementation detail
2. Forces use of any in index signatures, losing type safety for custom schemas
3. Adds complexity for library consumers

Suggested solutions

Option 1: Separate internal metadata type

export type Database = {
  public: { Tables: {...} }
  // Custom schemas work with index signature
}

// Separate from Database type
export type DatabaseMeta = {
  __PostgrestVersion: string
}

Option 2: Symbol key instead of string key

declare const __internal: unique symbol

export type Database = {
  public: { Tables: {...} }
  [__internal]?: { PostgrestVersion: string }  // Symbol keys don't affect string index signatures
}

Option 3: Branded/tagged type

export type Database = {
  public: { Tables: {...} }
} & { __brand?: { PostgrestVersion: string } }  // Intersection doesn't pollute index signature

System Info

- supabase-js version: 2.x
- TypeScript version: 5.x

Used Package Manager

pnpm

Logs

• supabase-js version: 2.x
• TypeScript version: 5.x

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Make sure this is a Supabase JS Library issue and not an issue with the Supabase platform. If it's a Supabase platform related bug, it should likely be reported to supabase/supabase instead.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion or join our Discord Chat Server.
• The provided reproduction is a minimal reproducible example of the bug.

[7ttp]

hi @jordanburke thanks for reporting💚,
i do confirm it was reproducible on my end too.

@mandarini if u havent started with it,
i would love to dig down and open a pr as needed!!

Edit: I've been digging into this and found that the __InternalSupabase type is generated by postgres-meta,
not supabase-js or the CLI. The proper fix would need to be implemented there.
However, I can open a PR here to export a DatabaseWithoutInternals helper type so library authors have an official utility instead of manually using Omit<Database, '__InternalSupabase'> everywhere.
Would that be helpful as an interim sol?

[jordanburke]

@7ttp fantastic, thank you for looking into so quickly.

[mandarini]

@7ttp feel free to attempt a fix, thanks!