Problem/Motivation
The PostgreSQL database has indexes types that are only on PostgreSQL. Those indexes are called GIN and GIST. They add query improvements that are needed by Drupal in #3343634: Add "json" as core data type to Schema and Database API and #2988018: [PP-1] Performance issues with path alias generated queries on PostgreSQL .
Proposed resolution
The comment at #2988018-97: [PP-1] Performance issues with path alias generated queries on PostgreSQL proposes an interesting solution:
Yet another way would be to use an object with array access to denote it is a gist index - but this is a way bigger API change. That said at some point table specifications should move away from ArrayPI and this at least gives us a requirement.
This is what we ended up doing.
This issue is split out to address these competing options on how to allow indexes to still be specified in a driver-agnostic manner, with as little BC-break and as much forward-compatibility as possible.
There has been some bikeshedding in how those PostgreSQL specific indexes should be created, dropped and check if they exist.
Specifically, the core schema API currently provides no way for ancillary data to be communicated about an index, e.g. what Postgres index type should be used.
In #2988018-93: [PP-1] Performance issues with path alias generated queries on PostgreSQL there is a patch that makes the (very reasonable) decision to indicate the index type through a "magic" index suffix, which Postgres would use to determine the index type. Subsequent discussion centered on the fact this is frail, not easily enforced in code and easy to forget, plus you never know if someone will name an index with _gin or _gist as the suffix not intending any specific meaning.
An alternative proposal is to provide for an additional DB schema spec key, e.g. gists. This would maybe be workable if we were only talking about GIST types, however if you also need GIN then you'd need to support a second key, and it gets rather messy. It also injects Postgres-specific new keys into the spec array shape.
Remaining tasks
Reach a consensus on how those indexes should be created, dropped and check if they exist.
Most (all?) of the decision-making centers around the above questions on the method of specifying the type of the index to be created.
Done
User interface changes
None
API changes
New value object to wrap existing index definitions and also convey additional information for db drivers (e.g., Postgres index type.)
Data model changes
This doesn't change the data model but the new config object is backwards-compatible with ArrayPI.
Release notes snippet
Draft release note done.