How Postgres chooses which index to use

[TheOtherBrian1]

This is a copy of a troubleshooting article on Supabase's docs site. It may be missing some details from the original. View the original article.

For the curious: here is a list of all built-in indexes in Postgres

Postgres internals

How an index is chosen

Postgres, internally, contains a few components that manage query execution:

Module	Description
Parser	Converts SQL into a traversable query tree
Planner/Optimizer	Takes the query tree and uses rules and database statistics to find the optimal strategy for getting the data
Executor	Executes the plan created by the planner

The planner will consider using an index when all the columns referenced are indexed or an indexed column is present in a filter statement, such as:

• WHERE
• LIKE
• ILIKE
• DISTINCT
• SIMILAR TO
• JOIN
• ORDER BY

Otherwise, it will likely perform a full table scan (sequential scan).

In the majority of cases, the indexed column must not only be present but also must be filtered by a comparison operator (=, >, <>) that is compatible with the index.

As an example, one can create the following table:

Column Name	Data Type
id	INT
data	JSONB

On the data column, a GIN index can be applied, which is excellent for filtering JSONB datatypes:

CREATE INDEX some_arbitary_index_name ON some_table USING gin (data);

Here's a link to the list operators supported by the GIN index; notably, it does not support greater than >:

-- GIN index will never be used
select *
from some_table
where data -> val > 5;

GIN does support the @> operator:

--GIN will be considered
SELECT id FROM some_table
WHERE data @> '[ { "itemId": "p11" } ]';

In most scenarios, developers work with the default BTREE index. It is the most flexible and performant for many data types and is compatible with the following filters operators:

Comparison Operator
<
<=
=
>=
>

An operator's functional equivalents, such as IN, BETWEEN, and ANY, are also valid.

However, just because the base requirements (relevant column, filter, and operators) are present, it doesn't mean that an index will be used. Indexes tend to perform best when searching for data that is not common (represents less than 5% to 10% of a column). If the data is overrepresented, Postgres may still try to use an index, but it can start leaning more towards sequential scans.

Postgres occasionally takes random samples of tables, usually reviewing around 30,000 rows, to determine the frequency of values, and uses that to determine whether an index will be performant.

In very rare cases, these statistics can become stale, and Postgres may opt to use a slower index or sequential scan when a better option is available.

You can see the query plan with the EXPLAIN keyword:

EXPLAIN <your query>

To understand how to interpret its output, you can check out this explainer.

To reset statistics within the database, you can use the following query:

-- use judiciously
select pg_stat_reset();

Complex or composite indexes

For a more complete rundown, check the Postgres Official Docs

Multi-column indexes

If you make independent indexes on multiple columns, Postgres will likely use each of them independently to find the relevant rows and then combine the results together.

It is possible to make multi-column indexes. If you are regularly filtering against multiple columns, there can be performance benefits using them instead of several independent indexes.

-- multi-column index
create index test2_mm_idx on test2 (major, minor);

-- multi-column comparison:
select name
from test2
where major = constant and minor = constant;

Ordered indexes

If you're using an ORDER BY clause, indexes can also be pre-sorted by DESC/ASC for better performance.

-- organizes the index in a DESC order, places NULL values at the end
CREATE INDEX test3_desc_index ON test3 (id DESC NULLS LAST);

Functional indexes

Although not as common, indexes can also be leveraged against modified values, such as when using a LOWER function:

-- Index on modified column through function
create index test1_lower_col1_idx on test1 (lower(col1));

-- Index will be considered for the following query:
select * from test1 where lower(col1) = 'value';

Covering indexes

Indexes contain pointers to a specific row, but you could instruct an index to actually hold a copy of a column's value for even faster retrieval. These are known as covering indexes. Because maintaining a copy is storage-intensive, you should avoid using it for values with large data footprints. FULL VIDEO ON TOPIC

CREATE INDEX a_b_idx ON x (a,b) INCLUDE (c);

Indexes on JSONB

Although a GIN/GIST index can be used to index entire JSONB bodies, you can also target just specific Key-values with standard BTREE indexes:

-- Example table
create table person (
  id serial primary key,
  data jsonb
);

create index index_name on person ((data ->> 'name'));

[hardikkaurani]

This feels less like a minor integration bug and more like a deployment-safety issue that can impact production reliability.

Silently replacing an existing Edge Function named stripe-webhook is especially risky because that is an extremely common and predictable naming convention for Stripe webhook handlers. In production systems, webhook endpoints usually contain business-critical logic such as subscription lifecycle updates, refunds, entitlement syncing, email triggers, audit logging, and signature verification. Overwriting that function without a collision check creates a very large blast radius.

The env var behavior is also concerning. Replacing a project-wide STRIPE_SECRET_KEY with a restricted key can unintentionally break unrelated Stripe workflows across the entire application stack — checkout creation, billing portal sessions, refunds, admin actions, scheduled jobs, and any server-side Stripe SDK usage that expects full permissions.

The most important thing here is that none of this appears to have been communicated clearly during installation. The installer messaging says it will deploy Stripe-related Edge Functions, but it does not explicitly warn that it may:

• overwrite existing function slugs
• modify shared environment variables
• reconfigure active webhook endpoints
• affect existing production billing infrastructure

The suggested mitigations are very reasonable and align with standard platform safety practices:

• perform pre-install collision detection for existing Edge Function slugs
• require explicit confirmation before replacing resources
• namespace integration-owned functions (stripe-sync-webhook, stripe-sync-worker, etc.)
• avoid mutating existing env vars unless explicitly approved
• use integration-scoped secrets such as STRIPE_SYNC_SECRET_KEY
• display a full install plan before deployment (functions, env vars, webhook URLs, DB objects)

A dry-run style “resources to be created/modified” screen before installation would probably prevent most of these incidents.

Also appreciate the detailed recovery notes. The fact that you documented:

• webhook URL restoration
• env var recovery
• function renaming
• verification of signing secrets
• downstream operational impact

makes this much easier for both maintainers and other users to understand and reproduce.

For anyone building platform tooling, this is a good example of why installers should behave more like infrastructure migrations than simple one-click add-ons. Production systems need guardrails, especially around globally shared resources and payment infrastructure.

Related concepts from Stripe + webhook best practices:

• Webhook endpoint isolation: [Stripe Webhooks Docs](https://docs.stripe.com/webhooks?utm_source=chatgpt.com)
• Principle of least privilege for API keys: [Stripe Restricted API Keys](https://docs.stripe.com/keys?utm_source=chatgpt.com#limit-access)
• Deployment safety / migration-style change visibility: [Supabase Edge Functions Docs](https://supabase.com/docs/guides/functions?utm_source=chatgpt.com)

Overall this is a valuable report and definitely seems worth addressing before more teams install Sync Engine into projects that already have existing Stripe infrastructure wired up.

[TheOtherBrian1]

@hardikkaurani, I think you may have commented in the wrong discussion. I wrote this article to discuss PostgreSQL indexing strategies

[hardikkaurani]

ohh okk no issues.