Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

15.2 KB
Raw Blame
import re
from typing import Optional

from products.warehouse_sources.sources.sdk import (
    SUPABASE_DIRECT_HOST_IPV4_HINT as _SUPABASE_DIRECT_HOST_IPV4_HINT,
    SUPABASE_DIRECT_HOST_RE as _SUPABASE_DIRECT_HOST_RE,
    DataWarehouseSourceCategory,
    ExternalDataSourceType,
    FieldType,
    ReleaseStatus,
    SourceConfig,
    SourceFieldInputConfig,
    SourceRegistry,
    SourceSchema,
    detect,
    rank_incremental_fields,
)
from products.warehouse_sources.sources.sdk.internals import (
    _HOST_UNREACHABLE_ERROR,
    _INVALID_CREDENTIALS_VALIDATION_ERROR,
    PostgresSource,
    PostgresSourceConfig,
)

# The Supabase dashboard shows `https://<ref>.supabase.co` as the "Project URL" — that's the
# REST/API endpoint, not a Postgres host. Pasting it (often with the scheme) into the host field
# just yields an opaque DNS failure, so detect it and point users at the actual database host.
_SUPABASE_PROJECT_HOST_RE = re.compile(r"^(?P<ref>[a-z0-9]+)\.supabase\.co$", re.IGNORECASE)

# The pooler username is `postgres.<project-ref>`, which reads like a host name — our own pooler
# guidance spells it out, and it lands in the host field often enough to be worth naming. A project
# ref is 20 characters, and a bare `postgres.<label>` that long is not a resolvable host either
# way, so matching it can't reject a host that would have worked.
_SUPABASE_POOLER_USERNAME_HOST_RE = re.compile(r"^postgres\.[a-z0-9]{16,}$", re.IGNORECASE)

_SUPABASE_POOLER_USERNAME_AS_HOST_ERROR = (
    "The host looks like your Supabase pooler username, not a database host. Enter the Session "
    "pooler host (aws-0-<region>.pooler.supabase.com) as the host, and postgres.<project-ref> as "
    "the user."
)

# Supabase has a separate database password, set when the project is created, and people often
# enter their Supabase account password instead.
_SUPABASE_INVALID_CREDENTIALS_ERROR = (
    "The database rejected the username or password. Use your Supabase database password, not your "
    "account password, or reset it in your project's database settings."
)


def _strip_host_scheme(host: str) -> str:
    """Reduce a pasted value to a bare host: drop any URL scheme, path, and surrounding whitespace."""
    stripped = re.sub(r"^[a-z][a-z0-9+.-]*://", "", (host or "").strip(), flags=re.IGNORECASE)
    return stripped.split("/", 1)[0]


_SUPABASE_POOLER_HOST_CAPTION = (
    "To get your connection string, click **Connect** in the top bar of your Supabase "
    "dashboard, open the **Direct** tab, and pick **Session pooler** or **Direct "
    "connection** — the URL is shown at the bottom. For standard syncs use the "
    "**Session pooler** host, e.g. `aws-0-<region>.pooler.supabase.com`, with username "
    "`postgres.<project-ref>` — the direct host `db.<ref>.supabase.co` is IPv6-only. "
    "For **change data capture (CDC)** you must use **Direct connection** instead and "
    "enable Supabase's **IPv4 add-on**, because logical replication doesn't work through "
    "the pooler."
)

# Supabase Realtime stores messages in daily partitions of its internal `realtime.messages` table
# named `realtime.messages_YYYY_MM_DD`, and its retention job drops the old partitions. A sync that
# targets one of these dated partitions fails with `relation "realtime.messages_..." does not exist`
# once that day is dropped. Match the stable partition-name prefix (never the volatile date). The
# inherited generic `"does not exist"` already classifies this non-retryable; this entry only adds an
# actionable message, so it must precede the generic key in `get_non_retryable_errors` (first match
# wins) with a non-None value.
_SUPABASE_REALTIME_PARTITION_ERROR = "realtime.messages_"
_SUPABASE_REALTIME_PARTITION_MESSAGE = (
    "Supabase creates a new realtime.messages partition each day and drops old ones automatically, "
    "so the dated partition this sync read no longer exists. These partitions are temporary and "
    "aren't meant to be synced. Remove this table from the source's selected tables, then re-enable "
    "the sync."
)

# The same partitions as they arrive from discovery, where the schema and table names come
# separately and the display name carries the schema only for a multi-schema source.
_REALTIME_SCHEMA = "realtime"
_REALTIME_MESSAGES_TABLE_PREFIX = "messages_"

# Supabase Vault's schema: its `decrypted_secrets` view decrypts every stored secret on read,
# so sync-enabling it by default would copy a secrets vault into the warehouse.
_VAULT_SCHEMA = "vault"


@SourceRegistry.register
class SupabaseSource(PostgresSource):
    codebase_detection = detect(
        env=(
            "^SUPABASE_",
            "^NEXT_PUBLIC_SUPABASE_",
            "^VITE_SUPABASE_",
            "^PUBLIC_SUPABASE_",
            "^EXPO_PUBLIC_SUPABASE_",
            "^REACT_APP_SUPABASE_",
            "^NUXT_PUBLIC_SUPABASE_",
            "^VUE_APP_SUPABASE_",
        ),
        npm=(
            "@supabase/supabase-js",
            "@supabase/ssr",
            "@supabase/auth-helpers-nextjs",
            "supabase",
            "@supabase/auth-js",
            "@supabase/gotrue-js",
            "@supabase/postgrest-js",
            "@supabase/realtime-js",
            "@supabase/storage-js",
            "@supabase/functions-js",
            "@supabase/server",
            "@supabase/auth-helpers-react",
            "@supabase/auth-helpers-sveltekit",
            "@supabase/auth-helpers-svelte",
            "@supabase/auth-helpers-remix",
            "@supabase/auth-helpers-shared",
            "@supabase/supabase-auth-helpers",
            "@supabase/auth-ui-react",
            "@supabase/auth-ui-svelte",
            "@supabase/auth-ui-solid",
            "@supabase/auth-ui-shared",
            "@supabase/sentry-js-integration",
            "@supabase/mcp-server-supabase",
            "@nuxtjs/supabase",
            "@refinedev/supabase",
            "@redwoodjs/auth-supabase-web",
            "@redwoodjs/auth-supabase-api",
        ),
        pypi=(
            "supabase",
            "supabase-auth",
            "gotrue",
            "postgrest",
            "postgrest-py",
            "realtime",
            "storage3",
            "supabase-functions",
            "supafunc",
        ),
        cargo=("supabase_rs", "supabase-auth", "postgrest"),
        composer=(
            "supabase/supabase-php",
            "supabase/postgrest-php",
            "supabase/gotrue-php",
            "supabase/storage-php",
            "supabase/functions-php",
            "rafaelwendel/phpsupabase",
        ),
        go=(
            "github.com/supabase-community/supabase-go",
            "github.com/supabase/supabase-go/supabase",
            "github.com/supabase/supabase-go/core",
            "github.com/supabase/supabase-go/auth",
            "github.com/supabase/supabase-go/postgrest",
            "github.com/supabase-community/auth-go",
            "github.com/supabase-community/gotrue-go",
            "github.com/supabase-community/postgrest-go",
            "github.com/supabase-community/storage-go",
            "github.com/supabase-community/functions-go",
            "github.com/supabase-community/realtime-go",
            "github.com/nedpals/supabase-go",
        ),
        hex=(
            "supabase_potion",
            "supabase_auth",
            "supabase_gotrue",
            "supabase_postgrest",
            "supabase_storage",
            "supabase_functions",
            "supabase_realtime",
            "supabase",
        ),
        maven=(
            "io.github.jan-tennert.supabase:supabase-kt",
            "io.github.jan-tennert.supabase:bom",
            "io.github.jan-tennert.supabase:auth-kt",
            "io.github.jan-tennert.supabase:gotrue-kt",
            "io.github.jan-tennert.supabase:postgrest-kt",
            "io.github.jan-tennert.supabase:realtime-kt",
            "io.github.jan-tennert.supabase:storage-kt",
            "io.github.jan-tennert.supabase:functions-kt",
            "io.github.jan-tennert.supabase:compose-auth",
            "io.github.jan-tennert.supabase:compose-auth-ui",
            "io.github.jan-tennert.supabase:apollo-graphql",
            "io.github.jan-tennert.supabase:coil-integration",
            "io.github.jan-tennert.supabase:coil3-integration",
            "io.github.jan-tennert.supabase:imageloader-integration",
            "io.github.jan-tennert.supabase:sketch-integration",
            "io.github.jan-tennert.supabase:serializer-jackson",
            "io.github.jan-tennert.supabase:serializer-moshi",
            "io.github.jan-tennert.supabase:ksp-compiler",
        ),
        pub=(
            "supabase_flutter",
            "supabase",
            "gotrue",
            "supabase_auth",
            "postgrest",
            "realtime_client",
            "storage_client",
            "functions_client",
            "supabase_functions",
            "supabase_auth_ui",
            "supabase_flutter_web_auth",
            "supabase_typegen",
        ),
        rubygems=("supabase", "supabase-rb"),
        swiftpm=(
            "github.com/supabase/supabase-swift",
            "github.com/supabase-community/supabase-swift",
            "github.com/supabase-community/gotrue-swift",
            "github.com/supabase-community/postgrest-swift",
            "github.com/supabase-community/realtime-swift",
            "github.com/supabase-community/storage-swift",
            "github.com/supabase-community/functions-swift",
        ),
    )

    def __init__(self):
        super().__init__(source_name="Supabase")

    @property
    def source_type(self) -> ExternalDataSourceType:
        return ExternalDataSourceType.SUPABASE

    @property
    def credential_kind(self) -> str | None:
        # Without this, the source inherits the kind of `PostgresSource`.
        return "supabase"

    def get_non_retryable_errors(self) -> dict[str, str | None]:
        return {
            _SUPABASE_REALTIME_PARTITION_ERROR: _SUPABASE_REALTIME_PARTITION_MESSAGE,
            **super().get_non_retryable_errors(),
        }

    def get_schemas(
        self,
        config: PostgresSourceConfig,
        team_id: int,
        with_counts: bool = False,
        names: list[str] | None = None,
        force_refresh: bool = False,
        api_version: str | None = None,
        require_ssl: bool = False,
    ) -> list[SourceSchema]:
        schemas = super().get_schemas(
            config,
            team_id,
            with_counts=with_counts,
            names=names,
            force_refresh=force_refresh,
            api_version=api_version,
            require_ssl=require_ssl,
        )

        # Vault tables must never be sync-enabled by default. They stay listed rather than
        # filtered because scheduled discovery reconciles stored rows against this listing
        # and would disable a vault sync a user deliberately opted into; default-off is
        # honored by the picker, one-shot setup, and auto-sync of newly discovered schemas.
        # Realtime's dated message partitions default off for the same reason auto-sync
        # exists: each day brings a new one, and Supabase drops it again days later, so an
        # automatically enabled partition fails for good (see
        # `_SUPABASE_REALTIME_PARTITION_MESSAGE`).
        for schema in schemas:
            if schema.source_schema == _VAULT_SCHEMA or self._is_realtime_message_partition(schema):
                schema.should_sync_default = False

        # Supabase tables carry arbitrary user columns, so the first discovered candidate
        # (column ordinal order) is often a value that never changes on update. Rank
        # update-tracking columns first so surfaces defaulting to the leading candidate
        # propose a cursor that actually advances.
        for schema in schemas:
            schema.incremental_fields = rank_incremental_fields(schema.incremental_fields)

        return schemas

    @staticmethod
    def _is_realtime_message_partition(schema: SourceSchema) -> bool:
        return schema.source_schema == _REALTIME_SCHEMA and (schema.source_table_name or "").startswith(
            _REALTIME_MESSAGES_TABLE_PREFIX
        )

    @staticmethod
    def _adjust_field(field: FieldType) -> FieldType:
        if isinstance(field, SourceFieldInputConfig) and field.name == "host":
            return field.model_copy(
                update={
                    "placeholder": "aws-0-us-east-1.pooler.supabase.com",
                    "caption": _SUPABASE_POOLER_HOST_CAPTION,
                }
            )
        return field

    @property
    def get_source_config(self) -> SourceConfig:
        fields = [self._adjust_field(field) for field in super().get_source_config.fields]

        return SourceConfig(
            name=ExternalDataSourceType.SUPABASE,
            category=DataWarehouseSourceCategory.DATABASES,
            keywords=["sql", "postgresql", "postgres"],
            featured=True,
            iconPath="/static/services/supabase.png",
            caption="Enter your Supabase credentials to automatically pull your data into the PostHog Data warehouse",
            docsUrl="https://posthog.com/tutorials/supabase-query",
            fields=fields,
            releaseStatus=ReleaseStatus.GA,
        )

    def validate_credentials(
        self,
        config: PostgresSourceConfig,
        team_id: int,
        schema_name: Optional[str] = None,
        api_version: str | None = None,
        require_ssl: bool = False,
    ) -> tuple[bool, str | None]:
        bare_host = _strip_host_scheme(config.host or "")
        if _SUPABASE_POOLER_USERNAME_HOST_RE.match(bare_host):
            return False, _SUPABASE_POOLER_USERNAME_AS_HOST_ERROR

        project_host = _SUPABASE_PROJECT_HOST_RE.match(bare_host)
        if project_host:
            # Project refs are lowercase, and the pooler username (postgres.<ref>) is
            # case-sensitive — canonicalize so the suggested values are copy-pasteable.
            ref = project_host.group("ref").lower()
            return False, (
                f"'{bare_host}' looks like your Supabase project URL, not a database "
                "host. For standard syncs use the Session pooler host (aws-0-<region>.pooler.supabase.com) with "
                f"username postgres.{ref}; for change data capture use the direct host db.{ref}.supabase.co and "
                "enable Supabase's IPv4 add-on."
            )

        # The direct host (IPv6-only by default) is the only host that supports logical
        # replication, so CDC users need it. We let the real connection attempt decide
        # reachability — it succeeds when the IPv4 add-on is enabled. Only the unreachable
        # failure is the IPv4 case, so swap in Supabase-specific pooler guidance there; other
        # failures (bad password, missing database, SSL) already have clear messages, and
        # blaming them on IPv4 would misdirect the user.
        is_direct_host = bool(_SUPABASE_DIRECT_HOST_RE.match((config.host or "").strip()))
        success, error = super().validate_credentials(config, team_id, schema_name=schema_name, require_ssl=require_ssl)
        if not success and is_direct_host and error == _HOST_UNREACHABLE_ERROR:
            return False, _SUPABASE_DIRECT_HOST_IPV4_HINT
        if not success and error == _INVALID_CREDENTIALS_VALIDATION_ERROR:
            return False, _SUPABASE_INVALID_CREDENTIALS_ERROR
        return success, error