From 2c81402fbb8445f264c981a3a689ed4dfab08040 Mon Sep 17 00:00:00 2001 From: alexfrancoeur Date: Fri, 8 Aug 2025 12:11:15 -0400 Subject: [PATCH 1/6] extensions page --- docs/extensions/index.mdx | 102 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 docs/extensions/index.mdx diff --git a/docs/extensions/index.mdx b/docs/extensions/index.mdx new file mode 100644 index 0000000..cf3e60a --- /dev/null +++ b/docs/extensions/index.mdx @@ -0,0 +1,102 @@ +--- +title: PostgreSQL Extensions +description: Available PostgreSQL extensions in Xata +--- + +# PostgreSQL Extensions + +All extensions listed below are currently available for PostgreSQL 17. These extensions provide additional functionality to enhance your database, from spatial data processing to text search and monitoring tools. + +## Available Extensions + +| Extension | Description | Version | Documentation | +|-----------|-------------|---------|---------------| +| [address_standardizer](https://postgis.net/docs/Extras.html#Address_Standardizer) | Standardizes address data using rules-based parsing | 3.5.3 | [PostGIS Docs](https://postgis.net/docs/Extras.html#Address_Standardizer) | +| [address_standardizer_data_us](https://postgis.net/docs/Extras.html#Address_Standardizer_Tables) | US address data for address_standardizer | 3.5.3 | [PostGIS Docs](https://postgis.net/docs/Extras.html#Address_Standardizer_Tables) | +| [amcheck](https://www.postgresql.org/docs/current/amcheck.html) | Functions for verifying relation integrity | 1.4 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/amcheck.html) | +| [anon](https://postgresql-anonymizer.readthedocs.io/) | Data anonymization and masking | - | [Documentation](https://postgresql-anonymizer.readthedocs.io/) | +| [auto_explain](https://www.postgresql.org/docs/current/auto-explain.html) | Automatic query plan logging | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/auto-explain.html) | +| [autoinc](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.8) | Functions for automatic increment of fields | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.8) | +| [bloom](https://www.postgresql.org/docs/current/bloom.html) | Bloom index access method | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/bloom.html) | +| [btree_gin](https://www.postgresql.org/docs/current/btree-gin.html) | Support for indexing common datatypes in GIN | 1.3 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/btree-gin.html) | +| [btree_gist](https://www.postgresql.org/docs/current/btree-gist.html) | Support for indexing common datatypes in GiST | 1.7 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/btree-gist.html) | +| [citext](https://www.postgresql.org/docs/current/citext.html) | Case-insensitive text data type | 1.6 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/citext.html) | +| [cube](https://www.postgresql.org/docs/current/cube.html) | Multi-dimensional cube data type | 1.5 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/cube.html) | +| [dblink](https://www.postgresql.org/docs/current/dblink.html) | Cross-database queries | 1.2 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/dblink.html) | +| [dict_int](https://www.postgresql.org/docs/current/dict-int.html) | Text search dictionary template for integers | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/dict-int.html) | +| [dict_xsyn](https://www.postgresql.org/docs/current/dict-xsyn.html) | Text search dictionary template for synonyms | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/dict-xsyn.html) | +| [earthdistance](https://www.postgresql.org/docs/current/earthdistance.html) | Earth distance calculations | 1.2 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/earthdistance.html) | +| [file_fdw](https://www.postgresql.org/docs/current/file-fdw.html) | Foreign data wrapper for flat file access | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/file-fdw.html) | +| [fuzzystrmatch](https://www.postgresql.org/docs/current/fuzzystrmatch.html) | Determine similarities and distance between strings | 1.2 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/fuzzystrmatch.html) | +| [hll](https://github.com/citusdata/postgresql-hll) | HyperLogLog data type for cardinality estimation | 2.18 | [GitHub](https://github.com/citusdata/postgresql-hll) | +| [hstore](https://www.postgresql.org/docs/current/hstore.html) | Key-value store data type | 1.8 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/hstore.html) | +| [hypopg](https://hypopg.readthedocs.io/) | Hypothetical indexes for query planning | 1.4.2 | [Documentation](https://hypopg.readthedocs.io/) | +| [intagg](https://www.postgresql.org/docs/current/intagg.html) | Integer aggregator (deprecated in favor of array_agg) | 1.1 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/intagg.html) | +| [intarray](https://www.postgresql.org/docs/current/intarray.html) | Functions for 1-D arrays of integers | 1.5 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/intarray.html) | +| [insert_username](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.9) | Automatic username insertion | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.9) | +| [ip4r](https://github.com/RhodiumToad/ip4r) | IPv4 and IPv6 types and functions | 2.4 | [GitHub](https://github.com/RhodiumToad/ip4r) | +| [isn](https://www.postgresql.org/docs/current/isn.html) | International Standard Number data types | 1.2 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/isn.html) | +| [lo](https://www.postgresql.org/docs/current/lo.html) | Large Object maintenance functions | 1.1 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/lo.html) | +| [ltree](https://www.postgresql.org/docs/current/ltree.html) | Tree-like structures data type | 1.3 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/ltree.html) | +| [moddatetime](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.10) | Automatic timestamp updates | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.10) | +| [pageinspect](https://www.postgresql.org/docs/current/pageinspect.html) | Low-level page inspection | 1.12 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pageinspect.html) | +| [pg_buffercache](https://www.postgresql.org/docs/current/pgbuffercache.html) | Buffer cache inspection | 1.5 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pgbuffercache.html) | +| [pg_cron](https://github.com/citusdata/pg_cron) | Job scheduler for PostgreSQL | 1.6 | [GitHub](https://github.com/citusdata/pg_cron) | +| [pg_freespacemap](https://www.postgresql.org/docs/current/pgfreespacemap.html) | Free space map examination | 1.2 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pgfreespacemap.html) | +| [pg_hint_plan](https://github.com/ossc-db/pg_hint_plan) | Query execution plan hinting | 1.7.0 | [GitHub](https://github.com/ossc-db/pg_hint_plan) | +| [pg_partman](https://github.com/pgpartman/pg_partman) | Partition management extension for PostgreSQL | 5.2.4 | [GitHub](https://github.com/pgpartman/pg_partman) | +| [pg_prewarm](https://www.postgresql.org/docs/current/pgprewarm.html) | Database prewarming | 1.2 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pgprewarm.html) | +| [pg_repack](https://github.com/reorg/pg_repack) | Remove bloat from tables and indexes without exclusive lock | 1.5.2 | [GitHub](https://github.com/reorg/pg_repack) | +| [pg_surgery](https://www.postgresql.org/docs/current/pgsurgery.html) | Row surgery functions for modifying rows | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pgsurgery.html) | +| [pg_trgm](https://www.postgresql.org/docs/current/pgtrgm.html) | Trigram matching for similarity searches | 1.6 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pgtrgm.html) | +| [pg_visibility](https://www.postgresql.org/docs/current/pgvisibility.html) | Visibility map examination | 1.2 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pgvisibility.html) | +| [pg_walinspect](https://www.postgresql.org/docs/current/pgwalinspect.html) | WAL inspection functions | 1.1 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pgwalinspect.html) | +| [pg_stat_statements](https://www.postgresql.org/docs/current/pgstatstatements.html) | Query execution statistics | 1.11 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pgstatstatements.html) | +| [pg_stattuple](https://www.postgresql.org/docs/current/pgstattuple.html) | Functions to show tuple-level statistics | 1.5 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pgstattuple.html) | +| [pgaudit](https://github.com/pgaudit/pgaudit) | Audit logging extension for PostgreSQL | 17.1 | [GitHub](https://github.com/pgaudit/pgaudit) | +| [pgcrypto](https://www.postgresql.org/docs/current/pgcrypto.html) | Cryptographic functions | 1.3 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pgcrypto.html) | +| [pgrouting](https://docs.pgrouting.org/) | Routing functionality for PostGIS/PostgreSQL | 3.8.0 | [Documentation](https://docs.pgrouting.org/) | +| [pglogical](https://github.com/2ndQuadrant/pglogical) | Logical replication extension for PostgreSQL | 2.4.5 | [GitHub](https://github.com/2ndQuadrant/pglogical) | +| [pgtap](https://pgtap.org/) | Unit testing framework for PostgreSQL | 1.3.3 | [Documentation](https://pgtap.org/) | +| [plpgsql](https://www.postgresql.org/docs/current/plpgsql.html) | PL/pgSQL procedural language | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/plpgsql.html) | +| [postgres_fdw](https://www.postgresql.org/docs/current/postgres-fdw.html) | Foreign data wrapper for PostgreSQL | 1.1 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/postgres-fdw.html) | +| [postgis](https://postgis.net/) | PostGIS geometry and geography spatial types and functions | 3.5.3 | [Documentation](https://postgis.net/) | +| [postgis_raster](https://postgis.net/docs/RT_reference.html) | PostGIS raster extension | 3.5.3 | [PostGIS Docs](https://postgis.net/docs/RT_reference.html) | +| [postgis_sfcgal](https://postgis.net/docs/SFCGAL_User_Manual.html) | PostGIS SFCGAL support | 3.5.3 | [PostGIS Docs](https://postgis.net/docs/SFCGAL_User_Manual.html) | +| [postgis_tiger_geocoder](https://postgis.net/docs/Extras.html#Tiger_Geocoder) | PostGIS tiger geocoder and reverse geocoder | 3.5.3 | [PostGIS Docs](https://postgis.net/docs/Extras.html#Tiger_Geocoder) | +| [postgis_topology](https://postgis.net/docs/Topology.html) | PostGIS topology spatial types and functions | 3.5.3 | [PostGIS Docs](https://postgis.net/docs/Topology.html) | +| [prefix](https://github.com/dimitri/prefix) | Prefix matching operator | 1.2.0 | [GitHub](https://github.com/dimitri/prefix) | +| [refint](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.11) | Referential integrity triggers (example) | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.11) | +| [seg](https://www.postgresql.org/docs/current/seg.html) | Floating-point intervals | 1.4 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/seg.html) | +| [sslinfo](https://www.postgresql.org/docs/current/sslinfo.html) | Information about SSL connections | 1.2 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/sslinfo.html) | +| [tablefunc](https://www.postgresql.org/docs/current/tablefunc.html) | Functions that manipulate whole tables, including crosstab | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/tablefunc.html) | +| [tcn](https://www.postgresql.org/docs/current/tcn.html) | Triggered change notifications | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/tcn.html) | +| [tsm_system_rows](https://www.postgresql.org/docs/current/tsm-system-rows.html) | TABLESAMPLE method which accepts number of rows | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/tsm-system-rows.html) | +| [tsm_system_time](https://www.postgresql.org/docs/current/tsm-system-time.html) | TABLESAMPLE method which accepts time in milliseconds | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/tsm-system-time.html) | +| [unaccent](https://www.postgresql.org/docs/current/unaccent.html) | Text search dictionary that removes accents | 1.1 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/unaccent.html) | +| [uuid-ossp](https://www.postgresql.org/docs/current/uuid-ossp.html) | UUID generation functions | 1.1 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/uuid-ossp.html) | +| [vector](https://github.com/pgvector/pgvector) | Vector similarity search for PostgreSQL | 0.8.0 | [GitHub](https://github.com/pgvector/pgvector) | +| [wal2json](https://github.com/eulerto/wal2json) | Logical replication output plugin for JSON | 2.6 | [GitHub](https://github.com/eulerto/wal2json) | +| [xml2](https://www.postgresql.org/docs/current/xml2.html) | XPath querying and XSLT support | 1.1 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/xml2.html) | + +## Request an Extension + +**Need an extension we don't have?** 📩 [Request an extension](https://xata.canny.io/xata-postgres-extensions) + +We're always looking to expand our extension offerings. If you need an extension that's not currently available, please let us know through our feature request portal. We'll review your request and respond there. + +## Getting Help + +If you need help with a specific extension, we recommend checking the official documentation linked in the table above. For general PostgreSQL extension support, you can also refer to the [PostgreSQL documentation](https://www.postgresql.org/docs/current/). + +If you run into an issue or discover a bug with an extension, we recommend reporting it to the extension's upstream maintainers. If a fix is released, we're happy to update to the latest version of the extension. + +For additional support, you can also [contact our support team](https://support.xata.io/hc/en-us/requests/new). + +## Custom Extensions + +We don't actively maintain third-party extension code, but we're happy to help you get the extensions you need. If you require a custom extension that's not listed above, we encourage you to [contact our support team](https://support.xata.io/hc/en-us/requests/new) to discuss. + +### BYOC for Custom Extensions + +If you need to install custom extensions that aren't available in our standard offering, consider our [Bring Your Own Cloud (BYOC) deployment model](/docs/deployment#bring-your-own-cloud-byoc). This allows you to run the entire Xata dataplane in your own Kubernetes cluster, giving you full control over which extensions are installed and configured. From 81906b73c1cb76080358b96298bed13c9db981e5 Mon Sep 17 00:00:00 2001 From: alexfrancoeur Date: Fri, 8 Aug 2025 12:14:09 -0400 Subject: [PATCH 2/6] adding to nav --- docs/config.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/config.json b/docs/config.json index 5ea6c6d..b6fe2e8 100644 --- a/docs/config.json +++ b/docs/config.json @@ -162,7 +162,7 @@ ] }, { - "title": "Migration Guides", + "title": "Migration guides", "href": "/migrations", "file": "docs/migrations/migrations.mdx", "items": [ @@ -223,6 +223,11 @@ } ] }, + { + "title": "Supported extensions", + "href": "/extensions", + "file": "docs/extensions/index.mdx" + }, { "title": "Command-line Interface", "href": "/cli", From 014ef29f8c8c583d05c35f8bdf651ac7ec69cb98 Mon Sep 17 00:00:00 2001 From: alexfrancoeur Date: Fri, 8 Aug 2025 12:19:27 -0400 Subject: [PATCH 3/6] small tweaks --- docs/extensions/index.mdx | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/docs/extensions/index.mdx b/docs/extensions/index.mdx index cf3e60a..a30d638 100644 --- a/docs/extensions/index.mdx +++ b/docs/extensions/index.mdx @@ -1,13 +1,9 @@ --- -title: PostgreSQL Extensions -description: Available PostgreSQL extensions in Xata +title: Supported extensions +description: All extensions listed below are currently available for PostgreSQL 17. These extensions provide additional functionality to enhance your database, from spatial data processing to text search and monitoring tools. --- -# PostgreSQL Extensions - -All extensions listed below are currently available for PostgreSQL 17. These extensions provide additional functionality to enhance your database, from spatial data processing to text search and monitoring tools. - -## Available Extensions +## Available PostgreSQL extensions | Extension | Description | Version | Documentation | |-----------|-------------|---------|---------------| @@ -79,13 +75,13 @@ All extensions listed below are currently available for PostgreSQL 17. These ext | [wal2json](https://github.com/eulerto/wal2json) | Logical replication output plugin for JSON | 2.6 | [GitHub](https://github.com/eulerto/wal2json) | | [xml2](https://www.postgresql.org/docs/current/xml2.html) | XPath querying and XSLT support | 1.1 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/xml2.html) | -## Request an Extension +## Request an extension **Need an extension we don't have?** 📩 [Request an extension](https://xata.canny.io/xata-postgres-extensions) We're always looking to expand our extension offerings. If you need an extension that's not currently available, please let us know through our feature request portal. We'll review your request and respond there. -## Getting Help +## Getting help If you need help with a specific extension, we recommend checking the official documentation linked in the table above. For general PostgreSQL extension support, you can also refer to the [PostgreSQL documentation](https://www.postgresql.org/docs/current/). @@ -93,10 +89,10 @@ If you run into an issue or discover a bug with an extension, we recommend repor For additional support, you can also [contact our support team](https://support.xata.io/hc/en-us/requests/new). -## Custom Extensions +## Custom extensions We don't actively maintain third-party extension code, but we're happy to help you get the extensions you need. If you require a custom extension that's not listed above, we encourage you to [contact our support team](https://support.xata.io/hc/en-us/requests/new) to discuss. -### BYOC for Custom Extensions +### BYOC for custom extensions If you need to install custom extensions that aren't available in our standard offering, consider our [Bring Your Own Cloud (BYOC) deployment model](/docs/deployment#bring-your-own-cloud-byoc). This allows you to run the entire Xata dataplane in your own Kubernetes cluster, giving you full control over which extensions are installed and configured. From b076473a94ef8e5d888b979f527014706782eae0 Mon Sep 17 00:00:00 2001 From: alexfrancoeur Date: Fri, 8 Aug 2025 12:26:58 -0400 Subject: [PATCH 4/6] cleaning up --- docs/extensions/index.mdx | 140 +++++++++++++++++++------------------- 1 file changed, 70 insertions(+), 70 deletions(-) diff --git a/docs/extensions/index.mdx b/docs/extensions/index.mdx index a30d638..1837a34 100644 --- a/docs/extensions/index.mdx +++ b/docs/extensions/index.mdx @@ -5,75 +5,75 @@ description: All extensions listed below are currently available for PostgreSQL ## Available PostgreSQL extensions -| Extension | Description | Version | Documentation | -|-----------|-------------|---------|---------------| -| [address_standardizer](https://postgis.net/docs/Extras.html#Address_Standardizer) | Standardizes address data using rules-based parsing | 3.5.3 | [PostGIS Docs](https://postgis.net/docs/Extras.html#Address_Standardizer) | -| [address_standardizer_data_us](https://postgis.net/docs/Extras.html#Address_Standardizer_Tables) | US address data for address_standardizer | 3.5.3 | [PostGIS Docs](https://postgis.net/docs/Extras.html#Address_Standardizer_Tables) | -| [amcheck](https://www.postgresql.org/docs/current/amcheck.html) | Functions for verifying relation integrity | 1.4 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/amcheck.html) | -| [anon](https://postgresql-anonymizer.readthedocs.io/) | Data anonymization and masking | - | [Documentation](https://postgresql-anonymizer.readthedocs.io/) | -| [auto_explain](https://www.postgresql.org/docs/current/auto-explain.html) | Automatic query plan logging | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/auto-explain.html) | -| [autoinc](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.8) | Functions for automatic increment of fields | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.8) | -| [bloom](https://www.postgresql.org/docs/current/bloom.html) | Bloom index access method | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/bloom.html) | -| [btree_gin](https://www.postgresql.org/docs/current/btree-gin.html) | Support for indexing common datatypes in GIN | 1.3 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/btree-gin.html) | -| [btree_gist](https://www.postgresql.org/docs/current/btree-gist.html) | Support for indexing common datatypes in GiST | 1.7 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/btree-gist.html) | -| [citext](https://www.postgresql.org/docs/current/citext.html) | Case-insensitive text data type | 1.6 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/citext.html) | -| [cube](https://www.postgresql.org/docs/current/cube.html) | Multi-dimensional cube data type | 1.5 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/cube.html) | -| [dblink](https://www.postgresql.org/docs/current/dblink.html) | Cross-database queries | 1.2 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/dblink.html) | -| [dict_int](https://www.postgresql.org/docs/current/dict-int.html) | Text search dictionary template for integers | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/dict-int.html) | -| [dict_xsyn](https://www.postgresql.org/docs/current/dict-xsyn.html) | Text search dictionary template for synonyms | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/dict-xsyn.html) | -| [earthdistance](https://www.postgresql.org/docs/current/earthdistance.html) | Earth distance calculations | 1.2 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/earthdistance.html) | -| [file_fdw](https://www.postgresql.org/docs/current/file-fdw.html) | Foreign data wrapper for flat file access | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/file-fdw.html) | -| [fuzzystrmatch](https://www.postgresql.org/docs/current/fuzzystrmatch.html) | Determine similarities and distance between strings | 1.2 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/fuzzystrmatch.html) | -| [hll](https://github.com/citusdata/postgresql-hll) | HyperLogLog data type for cardinality estimation | 2.18 | [GitHub](https://github.com/citusdata/postgresql-hll) | -| [hstore](https://www.postgresql.org/docs/current/hstore.html) | Key-value store data type | 1.8 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/hstore.html) | -| [hypopg](https://hypopg.readthedocs.io/) | Hypothetical indexes for query planning | 1.4.2 | [Documentation](https://hypopg.readthedocs.io/) | -| [intagg](https://www.postgresql.org/docs/current/intagg.html) | Integer aggregator (deprecated in favor of array_agg) | 1.1 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/intagg.html) | -| [intarray](https://www.postgresql.org/docs/current/intarray.html) | Functions for 1-D arrays of integers | 1.5 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/intarray.html) | -| [insert_username](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.9) | Automatic username insertion | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.9) | -| [ip4r](https://github.com/RhodiumToad/ip4r) | IPv4 and IPv6 types and functions | 2.4 | [GitHub](https://github.com/RhodiumToad/ip4r) | -| [isn](https://www.postgresql.org/docs/current/isn.html) | International Standard Number data types | 1.2 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/isn.html) | -| [lo](https://www.postgresql.org/docs/current/lo.html) | Large Object maintenance functions | 1.1 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/lo.html) | -| [ltree](https://www.postgresql.org/docs/current/ltree.html) | Tree-like structures data type | 1.3 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/ltree.html) | -| [moddatetime](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.10) | Automatic timestamp updates | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.10) | -| [pageinspect](https://www.postgresql.org/docs/current/pageinspect.html) | Low-level page inspection | 1.12 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pageinspect.html) | -| [pg_buffercache](https://www.postgresql.org/docs/current/pgbuffercache.html) | Buffer cache inspection | 1.5 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pgbuffercache.html) | -| [pg_cron](https://github.com/citusdata/pg_cron) | Job scheduler for PostgreSQL | 1.6 | [GitHub](https://github.com/citusdata/pg_cron) | -| [pg_freespacemap](https://www.postgresql.org/docs/current/pgfreespacemap.html) | Free space map examination | 1.2 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pgfreespacemap.html) | -| [pg_hint_plan](https://github.com/ossc-db/pg_hint_plan) | Query execution plan hinting | 1.7.0 | [GitHub](https://github.com/ossc-db/pg_hint_plan) | -| [pg_partman](https://github.com/pgpartman/pg_partman) | Partition management extension for PostgreSQL | 5.2.4 | [GitHub](https://github.com/pgpartman/pg_partman) | -| [pg_prewarm](https://www.postgresql.org/docs/current/pgprewarm.html) | Database prewarming | 1.2 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pgprewarm.html) | -| [pg_repack](https://github.com/reorg/pg_repack) | Remove bloat from tables and indexes without exclusive lock | 1.5.2 | [GitHub](https://github.com/reorg/pg_repack) | -| [pg_surgery](https://www.postgresql.org/docs/current/pgsurgery.html) | Row surgery functions for modifying rows | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pgsurgery.html) | -| [pg_trgm](https://www.postgresql.org/docs/current/pgtrgm.html) | Trigram matching for similarity searches | 1.6 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pgtrgm.html) | -| [pg_visibility](https://www.postgresql.org/docs/current/pgvisibility.html) | Visibility map examination | 1.2 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pgvisibility.html) | -| [pg_walinspect](https://www.postgresql.org/docs/current/pgwalinspect.html) | WAL inspection functions | 1.1 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pgwalinspect.html) | -| [pg_stat_statements](https://www.postgresql.org/docs/current/pgstatstatements.html) | Query execution statistics | 1.11 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pgstatstatements.html) | -| [pg_stattuple](https://www.postgresql.org/docs/current/pgstattuple.html) | Functions to show tuple-level statistics | 1.5 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pgstattuple.html) | -| [pgaudit](https://github.com/pgaudit/pgaudit) | Audit logging extension for PostgreSQL | 17.1 | [GitHub](https://github.com/pgaudit/pgaudit) | -| [pgcrypto](https://www.postgresql.org/docs/current/pgcrypto.html) | Cryptographic functions | 1.3 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/pgcrypto.html) | -| [pgrouting](https://docs.pgrouting.org/) | Routing functionality for PostGIS/PostgreSQL | 3.8.0 | [Documentation](https://docs.pgrouting.org/) | -| [pglogical](https://github.com/2ndQuadrant/pglogical) | Logical replication extension for PostgreSQL | 2.4.5 | [GitHub](https://github.com/2ndQuadrant/pglogical) | -| [pgtap](https://pgtap.org/) | Unit testing framework for PostgreSQL | 1.3.3 | [Documentation](https://pgtap.org/) | -| [plpgsql](https://www.postgresql.org/docs/current/plpgsql.html) | PL/pgSQL procedural language | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/plpgsql.html) | -| [postgres_fdw](https://www.postgresql.org/docs/current/postgres-fdw.html) | Foreign data wrapper for PostgreSQL | 1.1 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/postgres-fdw.html) | -| [postgis](https://postgis.net/) | PostGIS geometry and geography spatial types and functions | 3.5.3 | [Documentation](https://postgis.net/) | -| [postgis_raster](https://postgis.net/docs/RT_reference.html) | PostGIS raster extension | 3.5.3 | [PostGIS Docs](https://postgis.net/docs/RT_reference.html) | -| [postgis_sfcgal](https://postgis.net/docs/SFCGAL_User_Manual.html) | PostGIS SFCGAL support | 3.5.3 | [PostGIS Docs](https://postgis.net/docs/SFCGAL_User_Manual.html) | -| [postgis_tiger_geocoder](https://postgis.net/docs/Extras.html#Tiger_Geocoder) | PostGIS tiger geocoder and reverse geocoder | 3.5.3 | [PostGIS Docs](https://postgis.net/docs/Extras.html#Tiger_Geocoder) | -| [postgis_topology](https://postgis.net/docs/Topology.html) | PostGIS topology spatial types and functions | 3.5.3 | [PostGIS Docs](https://postgis.net/docs/Topology.html) | -| [prefix](https://github.com/dimitri/prefix) | Prefix matching operator | 1.2.0 | [GitHub](https://github.com/dimitri/prefix) | -| [refint](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.11) | Referential integrity triggers (example) | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.11) | -| [seg](https://www.postgresql.org/docs/current/seg.html) | Floating-point intervals | 1.4 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/seg.html) | -| [sslinfo](https://www.postgresql.org/docs/current/sslinfo.html) | Information about SSL connections | 1.2 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/sslinfo.html) | -| [tablefunc](https://www.postgresql.org/docs/current/tablefunc.html) | Functions that manipulate whole tables, including crosstab | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/tablefunc.html) | -| [tcn](https://www.postgresql.org/docs/current/tcn.html) | Triggered change notifications | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/tcn.html) | -| [tsm_system_rows](https://www.postgresql.org/docs/current/tsm-system-rows.html) | TABLESAMPLE method which accepts number of rows | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/tsm-system-rows.html) | -| [tsm_system_time](https://www.postgresql.org/docs/current/tsm-system-time.html) | TABLESAMPLE method which accepts time in milliseconds | 1.0 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/tsm-system-time.html) | -| [unaccent](https://www.postgresql.org/docs/current/unaccent.html) | Text search dictionary that removes accents | 1.1 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/unaccent.html) | -| [uuid-ossp](https://www.postgresql.org/docs/current/uuid-ossp.html) | UUID generation functions | 1.1 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/uuid-ossp.html) | -| [vector](https://github.com/pgvector/pgvector) | Vector similarity search for PostgreSQL | 0.8.0 | [GitHub](https://github.com/pgvector/pgvector) | -| [wal2json](https://github.com/eulerto/wal2json) | Logical replication output plugin for JSON | 2.6 | [GitHub](https://github.com/eulerto/wal2json) | -| [xml2](https://www.postgresql.org/docs/current/xml2.html) | XPath querying and XSLT support | 1.1 | [PostgreSQL Docs](https://www.postgresql.org/docs/current/xml2.html) | +| Extension | Description | Version | +|-----------|-------------|---------| +| [address_standardizer](https://postgis.net/docs/Extras.html#Address_Standardizer) | Standardizes address data using rules-based parsing | 3.5.3 | +| [address_standardizer_data_us](https://postgis.net/docs/Extras.html#Address_Standardizer_Tables) | US address data for address_standardizer | 3.5.3 | +| [amcheck](https://www.postgresql.org/docs/current/amcheck.html) | Functions for verifying relation integrity | 1.4 | +| [auto_explain](https://www.postgresql.org/docs/current/auto-explain.html) | Automatic query plan logging | 1.0 | +| [autoinc](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.8) | Functions for automatic increment of fields | 1.0 | +| [bloom](https://www.postgresql.org/docs/current/bloom.html) | Bloom index access method | 1.0 | +| [btree_gin](https://www.postgresql.org/docs/current/btree-gin.html) | Support for indexing common datatypes in GIN | 1.3 | +| [btree_gist](https://www.postgresql.org/docs/current/btree-gist.html) | Support for indexing common datatypes in GiST | 1.7 | +| [citext](https://www.postgresql.org/docs/current/citext.html) | Case-insensitive text data type | 1.6 | +| [cube](https://www.postgresql.org/docs/current/cube.html) | Multi-dimensional cube data type | 1.5 | +| [dblink](https://www.postgresql.org/docs/current/dblink.html) | Cross-database queries | 1.2 | +| [dict_int](https://www.postgresql.org/docs/current/dict-int.html) | Text search dictionary template for integers | 1.0 | +| [dict_xsyn](https://www.postgresql.org/docs/current/dict-xsyn.html) | Text search dictionary template for synonyms | 1.0 | +| [earthdistance](https://www.postgresql.org/docs/current/earthdistance.html) | Earth distance calculations | 1.2 | +| [file_fdw](https://www.postgresql.org/docs/current/file-fdw.html) | Foreign data wrapper for flat file access | 1.0 | +| [fuzzystrmatch](https://www.postgresql.org/docs/current/fuzzystrmatch.html) | Determine similarities and distance between strings | 1.2 | +| [hll](https://github.com/citusdata/postgresql-hll) | HyperLogLog data type for cardinality estimation | 2.18 | +| [hstore](https://www.postgresql.org/docs/current/hstore.html) | Key-value store data type | 1.8 | +| [hypopg](https://hypopg.readthedocs.io/) | Hypothetical indexes for query planning | 1.4.2 | +| [intagg](https://www.postgresql.org/docs/current/intagg.html) | Integer aggregator (deprecated in favor of array_agg) | 1.1 | +| [intarray](https://www.postgresql.org/docs/current/intarray.html) | Functions for 1-D arrays of integers | 1.5 | +| [insert_username](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.9) | Automatic username insertion | 1.0 | +| [ip4r](https://github.com/RhodiumToad/ip4r) | IPv4 and IPv6 types and functions | 2.4 | +| [isn](https://www.postgresql.org/docs/current/isn.html) | International Standard Number data types | 1.2 | +| [lo](https://www.postgresql.org/docs/current/lo.html) | Large Object maintenance functions | 1.1 | +| [ltree](https://www.postgresql.org/docs/current/ltree.html) | Tree-like structures data type | 1.3 | +| [moddatetime](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.10) | Automatic timestamp updates | 1.0 | +| [pageinspect](https://www.postgresql.org/docs/current/pageinspect.html) | Low-level page inspection | 1.12 | +| [pg_buffercache](https://www.postgresql.org/docs/current/pgbuffercache.html) | Buffer cache inspection | 1.5 | +| [pg_cron](https://github.com/citusdata/pg_cron) | Job scheduler for PostgreSQL | 1.6 | +| [pg_freespacemap](https://www.postgresql.org/docs/current/pgfreespacemap.html) | Free space map examination | 1.2 | +| [pg_hint_plan](https://github.com/ossc-db/pg_hint_plan) | Query execution plan hinting | 1.7.0 | +| [pg_partman](https://github.com/pgpartman/pg_partman) | Partition management extension for PostgreSQL | 5.2.4 | +| [pg_prewarm](https://www.postgresql.org/docs/current/pgprewarm.html) | Database prewarming | 1.2 | +| [pg_repack](https://github.com/reorg/pg_repack) | Remove bloat from tables and indexes without exclusive lock | 1.5.2 | +| [pg_surgery](https://www.postgresql.org/docs/current/pgsurgery.html) | Row surgery functions for modifying rows | 1.0 | +| [pg_trgm](https://www.postgresql.org/docs/current/pgtrgm.html) | Trigram matching for similarity searches | 1.6 | +| [pg_visibility](https://www.postgresql.org/docs/current/pgvisibility.html) | Visibility map examination | 1.2 | +| [pg_walinspect](https://www.postgresql.org/docs/current/pgwalinspect.html) | WAL inspection functions | 1.1 | +| [pgrowlocks](https://www.postgresql.org/docs/current/pgrowlocks.html) | Row locking information | 1.2 | +| [pg_stat_statements](https://www.postgresql.org/docs/current/pgstatstatements.html) | Query execution statistics | 1.11 | +| [pg_stattuple](https://www.postgresql.org/docs/current/pgstattuple.html) | Functions to show tuple-level statistics | 1.5 | +| [pgaudit](https://github.com/pgaudit/pgaudit) | Audit logging extension for PostgreSQL | 17.1 | +| [pgcrypto](https://www.postgresql.org/docs/current/pgcrypto.html) | Cryptographic functions | 1.3 | +| [pgrouting](https://docs.pgrouting.org/) | Routing functionality for PostGIS/PostgreSQL | 3.8.0 | +| [pglogical](https://github.com/2ndQuadrant/pglogical) | Logical replication extension for PostgreSQL | 2.4.5 | +| [pgtap](https://pgtap.org/) | Unit testing framework for PostgreSQL | 1.3.3 | +| [plpgsql](https://www.postgresql.org/docs/current/plpgsql.html) | PL/pgSQL procedural language | 1.0 | +| [postgres_fdw](https://www.postgresql.org/docs/current/postgres-fdw.html) | Foreign data wrapper for PostgreSQL | 1.1 | +| [postgis](https://postgis.net/) | PostGIS geometry and geography spatial types and functions | 3.5.3 | +| [postgis_raster](https://postgis.net/docs/RT_reference.html) | PostGIS raster extension | 3.5.3 | +| [postgis_sfcgal](https://postgis.net/docs/SFCGAL_User_Manual.html) | PostGIS SFCGAL support | 3.5.3 | +| [postgis_tiger_geocoder](https://postgis.net/docs/Extras.html#Tiger_Geocoder) | PostGIS tiger geocoder and reverse geocoder | 3.5.3 | +| [postgis_topology](https://postgis.net/docs/Topology.html) | PostGIS topology spatial types and functions | 3.5.3 | +| [prefix](https://github.com/dimitri/prefix) | Prefix matching operator | 1.2.0 | +| [refint](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.11) | Referential integrity triggers (example) | 1.0 | +| [seg](https://www.postgresql.org/docs/current/seg.html) | Floating-point intervals | 1.4 | +| [sslinfo](https://www.postgresql.org/docs/current/sslinfo.html) | Information about SSL connections | 1.2 | +| [tablefunc](https://www.postgresql.org/docs/current/tablefunc.html) | Functions that manipulate whole tables, including crosstab | 1.0 | +| [tcn](https://www.postgresql.org/docs/current/tcn.html) | Triggered change notifications | 1.0 | +| [tsm_system_rows](https://www.postgresql.org/docs/current/tsm-system-rows.html) | TABLESAMPLE method which accepts number of rows | 1.0 | +| [tsm_system_time](https://www.postgresql.org/docs/current/tsm-system-time.html) | TABLESAMPLE method which accepts time in milliseconds | 1.0 | +| [unaccent](https://www.postgresql.org/docs/current/unaccent.html) | Text search dictionary that removes accents | 1.1 | +| [uuid-ossp](https://www.postgresql.org/docs/current/uuid-ossp.html) | UUID generation functions | 1.1 | +| [vector](https://github.com/pgvector/pgvector) | Vector similarity search for PostgreSQL | 0.8.0 | +| [wal2json](https://github.com/eulerto/wal2json) | Logical replication output plugin for JSON | 2.6 | +| [xml2](https://www.postgresql.org/docs/current/xml2.html) | XPath querying and XSLT support | 1.1 | ## Request an extension @@ -95,4 +95,4 @@ We don't actively maintain third-party extension code, but we're happy to help y ### BYOC for custom extensions -If you need to install custom extensions that aren't available in our standard offering, consider our [Bring Your Own Cloud (BYOC) deployment model](/docs/deployment#bring-your-own-cloud-byoc). This allows you to run the entire Xata dataplane in your own Kubernetes cluster, giving you full control over which extensions are installed and configured. +If you need to install custom extensions that aren't available in our standard offering, consider our [Bring Your Own Cloud (BYOC) deployment model](/docs/deployment#bring-your-own-cloud-byoc). This allows you to run the entire Xata dataplane in your own Kubernetes cluster, giving you full control over which extensions are installed and configured. \ No newline at end of file From 56b6f51fdc7c7e6949e84342b8646e7b4778b1ba Mon Sep 17 00:00:00 2001 From: alexfrancoeur Date: Sun, 10 Aug 2025 16:32:07 -0400 Subject: [PATCH 5/6] cleaning up REST API docs --- docs/api/api-keys.mdx | 358 ++++++++++++++++++++++++++++--- docs/api/branches.mdx | 424 ++++++++++++++++++++++++++----------- docs/api/index.mdx | 2 - docs/api/metrics.mdx | 139 ++++++++++-- docs/api/organizations.mdx | 164 ++++++++++++-- docs/api/projects.mdx | 210 ++++++++++++++---- docs/api/users.mdx | 140 +++++++++++- 7 files changed, 1196 insertions(+), 241 deletions(-) diff --git a/docs/api/api-keys.mdx b/docs/api/api-keys.mdx index 619aa5a..b2d402e 100644 --- a/docs/api/api-keys.mdx +++ b/docs/api/api-keys.mdx @@ -3,7 +3,17 @@ title: API Keys API description: Manage API keys for authentication --- -The API Keys API allows you to manage API keys for users and organizations, including creating, listing, and deleting API keys. +The API Keys API allows you to manage API keys for users and organizations, including creating, listing, and deleting API keys. All endpoints require authentication via API key or OIDC. + +## Authentication + +All endpoints require authentication. You can authenticate using: +- **API Key**: Include your API key in the `Authorization` header: `Authorization: Bearer ` +- **OIDC**: Use OIDC tokens for authentication + +Required scopes for different operations: +- **api_key:read**: Read API key information and list keys +- **api_key:write**: Create and delete API keys ## List API keys @@ -15,21 +25,22 @@ Retrieves a list of API keys for a user or organization. GET /api-keys ``` -### List organization API keys - -```bash -GET /api-keys -``` +### Summary +Returns a paginated list of all API keys associated with the authenticated user, including metadata such as name, creation date, expiry, scopes, and access permissions. ### Query parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| organization | string | Filter by organization ID (optional) | -| user | string | Filter by user ID (optional) | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| organization | string | No | Filter by organization ID (optional) | +| user | string | No | Filter by user ID (optional) | +| page | integer | No | Page number for pagination (default: 1) | +| size | integer | No | Number of items per page (default: 20, max: 100) | ### Response +**Status:** `200 OK` + ```json { "keys": [ @@ -46,10 +57,38 @@ GET /api-keys "projects": ["proj_123"], "branches": ["br_123"] } - ] + ], + "pagination": { + "page": 1, + "size": 20, + "total": 45, + "pages": 3 + } } ``` +### Response schema + +| Field | Type | Description | +|-------|------|-------------| +| keys | array | Array of API key objects | +| pagination | object | Pagination information | +| pagination.page | integer | Current page number | +| pagination.size | integer | Number of items per page | +| pagination.total | integer | Total number of items | +| pagination.pages | integer | Total number of pages | +| id | string | Unique identifier for the API key | +| name | string | Human-readable name for the API key | +| preview | string | Preview of the API key (first few characters) | +| created_at | string (date-time) | Timestamp when the API key was created | +| created_by | string | ID of the user that created this API key | +| created_by_key | string | ID of the API key that created this API key | +| expiry | string (date-time) | Date when the API key expires (null if no expiry) | +| last_used | string (date-time) | Timestamp of the last time the key was used | +| scopes | array | List of scopes granted to this API key | +| projects | array | List of project IDs the key has access to | +| branches | array | List of branch IDs the key has access to | + ## Create API key Creates a new API key for a user or organization. @@ -58,6 +97,9 @@ Creates a new API key for a user or organization. POST /api-keys ``` +### Summary +Creates a new API key with specified permissions, scopes, and access restrictions. The full key is only returned once upon creation. + ### Request body ```json @@ -72,21 +114,24 @@ POST /api-keys ### Request body parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| name | string | Human-readable name for the API key | -| expiry | string (date-time) | Optional expiration date for the API key | -| scopes | array | List of scopes for the API key | -| projects | array | List of project IDs the key has access to | -| branches | array | List of branch IDs the key has access to | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| name | string | Yes | Human-readable name for the API key | +| expiry | string (date-time) | No | Optional expiration date for the API key | +| scopes | array | Yes | List of scopes for the API key | +| projects | array | No | List of project IDs the key has access to | +| branches | array | No | List of branch IDs the key has access to | ### Response +**Status:** `201 Created` + ```json { "id": "key_123", "name": "New API Key", - "key": "xata_live_abc123...", + "key": "xata_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz567890", + "preview": "xata_...", "created_at": "2024-01-01T00:00:00Z", "created_by": "user_123", "created_by_key": null, @@ -97,22 +142,45 @@ POST /api-keys } ``` +**Note:** The `key` field is only returned once upon creation. Store this securely as it cannot be retrieved later. + +### Response schema + +| Field | Type | Description | +|-------|------|-------------| +| id | string | Unique identifier for the created API key | +| key | string | The full API key (only returned once) | +| name | string | Name of the API key | +| preview | string | Preview of the API key (first few characters) | +| created_at | string (date-time) | Timestamp when the API key was created | +| created_by | string | ID of the user that created this API key | +| created_by_key | string | ID of the API key that created this API key | +| expiry | string (date-time) | Date when the API key expires | +| scopes | array | List of scopes granted to this API key | +| projects | array | List of project IDs the key has access to | +| branches | array | List of branch IDs the key has access to | + ## Get API key -Retrieves details about a specific API key. +Retrieves detailed information about a specific API key. ```bash -GET /api-keys/{apiKeyID} +GET /api-keys/{keyID} ``` +### Summary +Returns comprehensive information about an API key including all metadata, permissions, and access details. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| apiKeyID | string | Unique identifier for the API key | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| keyID | string | Yes | Unique identifier for the API key | ### Response +**Status:** `200 OK` + ```json { "id": "key_123", @@ -129,20 +197,252 @@ GET /api-keys/{apiKeyID} } ``` +### Response schema + +| Field | Type | Description | +|-------|------|-------------| +| id | string | Unique identifier for the API key | +| name | string | Human-readable name for the API key | +| preview | string | Preview of the API key (first few characters) | +| created_at | string (date-time) | Timestamp when the API key was created | +| created_by | string | ID of the user that created this API key | +| created_by_key | string | ID of the API key that created this API key | +| expiry | string (date-time) | Date when the API key expires (null if no expiry) | +| last_used | string (date-time) | Timestamp of the last time the key was used | +| scopes | array | List of scopes granted to this API key | +| projects | array | List of project IDs the key has access to | +| branches | array | List of branch IDs the key has access to | + ## Delete API key Permanently deletes an API key. ```bash -DELETE /api-keys/{apiKeyID} +DELETE /api-keys/{keyID} ``` +### Summary +Permanently removes an API key. This action cannot be undone and will immediately revoke all access for the specified key. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| apiKeyID | string | Unique identifier for the API key | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| keyID | string | Yes | Unique identifier for the API key | ### Response -Returns a 204 status code with no content on success. \ No newline at end of file +**Status:** `204 No Content` + +No response body is returned on successful deletion. + +## Error Handling + +The API uses standard HTTP status codes and returns error responses in the following format: + +```json +{ + "id": "error_identifier", + "message": "Human-readable error message explaining the issue" +} +``` + +### Common error responses + +| Status | Error Type | Description | +|--------|------------|-------------| +| 400 | GenericError | Request was malformed or contained invalid parameters | +| 401 | AuthorizationError | Authentication failed or is missing | +| 403 | AuthorizationError | API key lacks required scopes for the operation | +| 404 | GenericError | Requested API key does not exist | +| 429 | RateLimitError | Rate limit exceeded | +| 5XX | GenericError | Server error occurred | + +### Error examples + +**400 Bad Request - Invalid scope** +```json +{ + "id": "invalid_scope", + "message": "Invalid scope 'invalid_scope_name' provided. Valid scopes are: read, write, admin, metrics:read, credentials:read, branch:read, branch:write, project:read, project:write, user:read, user:write, api_key:read, api_key:write" +} +``` + +**401 Unauthorized - Invalid API key** +```json +{ + "id": "invalid_api_key", + "message": "Invalid or expired API key provided" +} +``` + +**403 Forbidden - Insufficient scopes** +```json +{ + "id": "insufficient_scopes", + "message": "API key lacks required scope 'api_key:write' for this operation" +} +``` + +**404 Not Found - API key not found** +```json +{ + "id": "api_key_not_found", + "message": "API key with ID 'key_999' not found" +} +``` + +**429 Too Many Requests - Rate limit exceeded** +```json +{ + "id": "rate_limit_exceeded", + "message": "Rate limit exceeded. Please try again in 60 seconds" +} +``` + +### Error resolution guidance + +- **400 Bad Request**: Check request body format and parameter values +- **401 Unauthorized**: Verify API key is valid and has required scopes +- **403 Forbidden**: Ensure your API key has the necessary scopes for the operation +- **404 Not Found**: Confirm API key ID is correct +- **429 Too Many Requests**: Wait for the rate limit window to reset or implement exponential backoff +- **5XX Server Error**: Retry the request or contact support if persistent + +## Rate Limiting + +API requests are subject to rate limiting. The current limits are: + +- 100 requests per minute per API key +- 1000 requests per hour per API key + +Rate limit headers are included in all responses: + +- `X-RateLimit-Limit`: The maximum number of requests allowed per time window +- `X-RateLimit-Remaining`: The number of requests remaining in the current time window +- `X-RateLimit-Reset`: The time when the current rate limit window resets (Unix timestamp) + +When rate limits are exceeded, the API returns a `429 Too Many Requests` status with appropriate error details. + +## Schema Reference + +### Core Data Models + +#### APIKeyPreview +Basic API key information returned when listing keys. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| id | string | Yes | Unique identifier for the API key | +| name | string | Yes | Human-readable name for the API key | +| preview | string | Yes | Preview of the API key (first few characters) | +| created_at | string (date-time) | Yes | Timestamp when the API key was created | +| expiry | string (date-time) | Yes | Date when the API key expires (null if no expiry) | +| last_used | string (date-time) | Yes | Timestamp of the last time the key was used | +| scopes | array | Yes | List of scopes granted to this API key | +| projects | array | Yes | List of project IDs the key has access to | +| branches | array | Yes | List of branch IDs the key has access to | +| created_by | string | No | ID of the user that created this API key | +| created_by_key | string | No | ID of the API key that created this API key | + +#### APIKeyCreationRequest +Request body for creating a new API key. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| name | string | Yes | Human-readable name for the API key | +| expiry | string (date-time) | No | Optional expiration date for the API key | +| scopes | array | Yes | List of scopes for the API key | +| projects | array | No | List of project IDs the key has access to | +| branches | array | No | List of branch IDs the key has access to | + +#### APIKey +Complete API key information including all metadata and permissions. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| id | string | Yes | Unique identifier for the API key | +| name | string | Yes | Human-readable name for the API key | +| preview | string | Yes | Preview of the API key (first few characters) | +| created_at | string (date-time) | Yes | Timestamp when the API key was created | +| expiry | string (date-time) | Yes | Date when the API key expires (null if no expiry) | +| last_used | string (date-time) | Yes | Timestamp of the last time the key was used | +| scopes | array | Yes | List of scopes granted to this API key | +| projects | array | Yes | List of project IDs the key has access to | +| branches | array | Yes | List of branch IDs the key has access to | +| created_by | string | No | ID of the user that created this API key | +| created_by_key | string | No | ID of the API key that created this API key | + +#### PaginationInfo +Pagination metadata for list responses. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| page | integer | Yes | Current page number | +| size | integer | Yes | Number of items per page | +| total | integer | Yes | Total number of items | +| pages | integer | Yes | Total number of pages | + +## Scopes + +API keys can have the following scopes that control access to different resources and operations: + +### Data Access Scopes +- **read**: Read access to database records and metadata +- **write**: Write access to create, update, and delete database records +- **admin**: Full administrative access to all resources + +### Monitoring and Metrics +- **metrics:read**: Access to performance metrics, query statistics, and monitoring data + +### Infrastructure Access +- **credentials:read**: Access to database connection credentials and connection strings +- **branch:read**: Read access to branch information and configuration +- **branch:write**: Write access to create, update, and delete branches +- **project:read**: Read access to project information and settings +- **project:write**: Write access to create, update, and delete projects + +### User Management +- **user:read**: Read access to user information and profiles +- **user:write**: Write access to create, update, and delete users + +### API Key Management +- **api_key:read**: Read access to API key information and list keys +- **api_key:write**: Write access to create and delete API keys + +### Scope Combinations + +Common scope combinations for different use cases: + +- **Read-only access**: `["read"]` +- **Full database access**: `["read", "write"]` +- **Developer access**: `["read", "write", "branch:read", "project:read"]` +- **Admin access**: `["admin"]` +- **Monitoring access**: `["metrics:read", "credentials:read"]` + +## Best Practices + +### Security +- Store API keys securely and never commit them to version control +- Use environment variables or secure secret management systems +- Rotate API keys regularly, especially for production environments +- Set appropriate expiry dates for temporary or testing keys +- Use the principle of least privilege - only grant necessary scopes + +### Key Management +- Use descriptive names for API keys to easily identify their purpose +- Create separate keys for different environments (development, staging, production) +- Monitor key usage and set up alerts for unusual activity +- Regularly audit and clean up unused or expired keys + +### Rate Limiting +- Implement exponential backoff when hitting rate limits +- Cache responses when possible to reduce API calls +- Monitor rate limit headers to optimize request patterns +- Consider implementing request queuing for high-volume operations + +### Error Handling +- Always check HTTP status codes and handle errors gracefully +- Implement retry logic with exponential backoff for transient errors +- Log error details for debugging and monitoring +- Provide user-friendly error messages in your applications \ No newline at end of file diff --git a/docs/api/branches.mdx b/docs/api/branches.mdx index 8c25190..359b18d 100644 --- a/docs/api/branches.mdx +++ b/docs/api/branches.mdx @@ -3,7 +3,19 @@ title: Branches API description: Manage database branches and their settings --- -The Branches API allows you to manage your database branches, including listing, creating, updating, and deleting branches. +The Branches API allows you to manage your database branches, including listing, creating, updating, and deleting branches. All endpoints require authentication via API key or OIDC. + +## Authentication + +All endpoints require authentication. You can authenticate using: +- **API Key**: Include your API key in the `Authorization` header: `Authorization: Bearer ` +- **OIDC**: Use OIDC tokens for authentication + +Required scopes for different operations: +- **branch:read**: Read branch information and list branches +- **branch:write**: Create, update, and delete branches +- **credentials:read**: Access branch credentials +- **metrics:read**: Access branch metrics ## List branches @@ -13,15 +25,20 @@ Retrieves a list of all branches within a project. GET /organizations/{organizationID}/projects/{projectID}/branches ``` +### Summary +Returns a paginated list of branches in a project with basic metadata including ID, name, creation date, region, and public access settings. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| organizationID | string | Unique identifier for the organization | -| projectID | string | Unique identifier for the project | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| organizationID | string | Yes | Unique identifier for the organization | +| projectID | string | Yes | Unique identifier for the project | ### Response +**Status:** `200 OK` + ```json { "branches": [ @@ -32,13 +49,27 @@ GET /organizations/{organizationID}/projects/{projectID}/branches "updatedAt": "2024-01-01T00:00:00Z", "region": "us-east-1", "publicAccess": false, - "description": "Main branch", + "description": "Main production branch", "parentID": null } ] } ``` +### Response schema + +| Field | Type | Description | +|-------|------|-------------| +| branches | array | Array of branch objects | +| id | string | Unique identifier for the branch | +| name | string | Human-readable name for the branch | +| createdAt | string (date-time) | Timestamp when the branch was created | +| updatedAt | string (date-time) | Timestamp when the branch was last updated | +| region | string | Geographic region where the branch is deployed | +| publicAccess | boolean | Whether the branch allows public access without authentication | +| description | string | Optional description of the branch purpose or contents | +| parentID | string | Identifier of the parent branch if derived, null otherwise | + ## Create branch Creates a new branch within a project. Branches can be created from scratch or derived from an existing parent branch. @@ -47,26 +78,28 @@ Creates a new branch within a project. Branches can be created from scratch or d POST /organizations/{organizationID}/projects/{projectID}/branches ``` +### Summary +Creates a new database branch with specified configuration. If a parent branch is specified, the new branch inherits the parent's configuration and data. Otherwise, a new cluster is created with the specified configuration. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| organizationID | string | Unique identifier for the organization | -| projectID | string | Unique identifier for the project | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| organizationID | string | Yes | Unique identifier for the organization | +| projectID | string | Yes | Unique identifier for the project | ### Request body ```json { - "name": "new-branch", - "description": "Development branch", + "name": "staging-branch", + "description": "Staging environment for testing", "parentID": "br_123", "configuration": { - "image": "postgresql:16", - "instanceType": "standard", + "image": "postgresql:17", + "instanceType": "small", "instances": 1, - "region": "us-east-1", - "storage": 10 + "region": "us-east-1" }, "scaleToZero": { "enabled": true, @@ -77,30 +110,46 @@ POST /organizations/{organizationID}/projects/{projectID}/branches ### Request body parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| name | string | Human-readable name for the new branch | -| description | string | Optional description for the branch purpose or contents (max 50 characters) | -| parentID | string | If present, the branch will inherit the parent branch configuration and data | -| configuration | object | Configuration for the underlying database cluster if not inheriting from a parent | -| scaleToZero | object | Scale to zero configuration for the branch | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| name | string | Yes | Human-readable name for the new branch (max 50 characters, pattern: `^[a-zA-Z0-9]+[a-zA-Z0-9- ]*$`) | +| description | string | No | Optional description for the branch purpose or contents (max 50 characters) | +| parentID | string | No | If present, the branch will inherit the parent branch configuration and data | +| configuration | ClusterConfiguration | No | Configuration for the underlying database cluster if not inheriting from a parent | +| scaleToZero | ScaleToZeroConfiguration | No | Scale to zero configuration for the branch | ### Response +**Status:** `201 Created` + ```json { "id": "br_456", - "name": "new-branch", + "name": "staging-branch", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z", "region": "us-east-1", "publicAccess": false, - "description": "Development branch", + "description": "Staging environment for testing", "parentID": "br_123", - "connectionString": "postgresql://..." + "connectionString": "postgresql://xata_user:password@host:port/database" } ``` +### Response schema + +| Field | Type | Description | +|-------|------|-------------| +| id | string | Unique identifier for the created branch | +| name | string | Name of the branch | +| createdAt | string (date-time) | Timestamp when the branch was created | +| updatedAt | string (date-time) | Timestamp when the branch was last updated | +| region | string | Geographic region where the branch is deployed | +| publicAccess | boolean | Whether the branch allows public access | +| description | string | Description of the branch | +| parentID | string | Identifier of the parent branch if derived | +| connectionString | string | Database connection string for the branch | + ## Get branch Retrieves detailed information about a specific branch. @@ -109,16 +158,21 @@ Retrieves detailed information about a specific branch. GET /organizations/{organizationID}/projects/{projectID}/branches/{branchID} ``` +### Summary +Returns comprehensive information about a branch including its configuration, status, connection details, and operational state. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| organizationID | string | Unique identifier for the organization | -| projectID | string | Unique identifier for the project | -| branchID | string | Unique identifier for the branch | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| organizationID | string | Yes | Unique identifier for the organization | +| projectID | string | Yes | Unique identifier for the project | +| branchID | string | Yes | Unique identifier for the branch | ### Response +**Status:** `200 OK` + ```json { "id": "br_123", @@ -127,15 +181,14 @@ GET /organizations/{organizationID}/projects/{projectID}/branches/{branchID} "updatedAt": "2024-01-01T00:00:00Z", "region": "us-east-1", "publicAccess": false, - "description": "Main branch", + "description": "Main production branch", "parentID": null, - "connectionString": "postgresql://...", + "connectionString": "postgresql://xata_user:password@host:port/database", "configuration": { - "image": "postgresql:16", - "instanceType": "standard", + "image": "postgresql:17", + "instanceType": "small", "instances": 1, - "region": "us-east-1", - "storage": 10 + "region": "us-east-1" }, "status": { "instanceCount": 1, @@ -160,6 +213,23 @@ GET /organizations/{organizationID}/projects/{projectID}/branches/{branchID} } ``` +### Response schema + +| Field | Type | Description | +|-------|------|-------------| +| id | string | Unique identifier for the branch | +| name | string | Human-readable name for the branch | +| createdAt | string (date-time) | Timestamp when the branch was created | +| updatedAt | string (date-time) | Timestamp when the branch was last updated | +| region | string | Geographic region where the branch is deployed | +| publicAccess | boolean | Whether the branch allows public access | +| description | string | Description of the branch | +| parentID | string | Identifier of the parent branch if derived | +| connectionString | string | Database connection string for the branch | +| configuration | ClusterConfiguration | Configuration details for the underlying database cluster | +| status | BranchStatus | Current operational status of the branch | +| scaleToZero | ScaleToZeroConfiguration | Scale to zero configuration for the branch | + ## Update branch Updates the configuration of a branch. @@ -168,58 +238,75 @@ Updates the configuration of a branch. PATCH /organizations/{organizationID}/projects/{projectID}/branches/{branchID} ``` +### Summary +Updates branch metadata such as name and description. Note that cluster configuration changes require creating a new branch. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| organizationID | string | Unique identifier for the organization | -| projectID | string | Unique identifier for the project | -| branchID | string | Unique identifier for the branch | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| organizationID | string | Yes | Unique identifier for the organization | +| projectID | string | Yes | Unique identifier for the project | +| branchID | string | Yes | Unique identifier for the branch | ### Request body ```json { - "name": "updated-branch", - "description": "Updated description" + "name": "updated-branch-name", + "description": "Updated description for the branch" } ``` +### Request body parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| name | string | No | New name for the branch | +| description | string | No | New description for the branch | + ### Response +**Status:** `200 OK` + ```json { "id": "br_123", - "name": "updated-branch", + "name": "updated-branch-name", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z", "region": "us-east-1", "publicAccess": false, - "description": "Updated description", + "description": "Updated description for the branch", "parentID": null, - "connectionString": "postgresql://..." + "connectionString": "postgresql://xata_user:password@host:port/database" } ``` ## Delete branch -Permanently deletes a branch and all its associated data. This action cannot be undone. +Permanently deletes a branch and all its associated data. ```bash DELETE /organizations/{organizationID}/projects/{projectID}/branches/{branchID} ``` +### Summary +Permanently removes a branch and all associated data. This action cannot be undone and will terminate all active connections. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| organizationID | string | Unique identifier for the organization | -| projectID | string | Unique identifier for the project | -| branchID | string | Unique identifier for the branch | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| organizationID | string | Yes | Unique identifier for the organization | +| projectID | string | Yes | Unique identifier for the project | +| branchID | string | Yes | Unique identifier for the branch | ### Response -Returns a 204 status code with no content on success. +**Status:** `204 No Content` + +No response body is returned on successful deletion. ## Get branch credentials @@ -229,22 +316,27 @@ Retrieves credentials for accessing a branch database. GET /organizations/{organizationID}/projects/{projectID}/branches/{branchID}/credentials ``` +### Summary +Returns database credentials (username and password) for connecting to a specific branch. These credentials can be used with the connection string returned by the branch details endpoint. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| organizationID | string | Unique identifier for the organization | -| projectID | string | Unique identifier for the project | -| branchID | string | Unique identifier for the branch | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| organizationID | string | Yes | Unique identifier for the organization | +| projectID | string | Yes | Unique identifier for the project | +| branchID | string | Yes | Unique identifier for the branch | ### Query parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| username | string | Username that the credentials are requested for (optional) | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| username | string | No | Username that the credentials are requested for (optional) | ### Response +**Status:** `200 OK` + ```json { "username": "xata_user", @@ -252,79 +344,159 @@ GET /organizations/{organizationID}/projects/{projectID}/branches/{branchID}/cre } ``` -## Get branch metrics +### Response schema -Retrieves metrics for a specific branch over a time period. +| Field | Type | Description | +|-------|------|-------------| +| username | string | Username for accessing the branch database | +| password | string | Password for accessing the branch database | -```bash -POST /organizations/{organizationID}/projects/{projectID}/branches/{branchID}/metrics -``` +## Branch Metrics -### Path parameters +For detailed metrics and monitoring data for branches, see the [Metrics API](/api/metrics) documentation. -| Parameter | Type | Description | -|-----------|------|-------------| -| organizationID | string | Unique identifier for the organization | -| projectID | string | Unique identifier for the project | -| branchID | string | Unique identifier for the branch | +The Metrics API provides comprehensive performance monitoring including CPU, memory, and disk usage across branch instances with support for multiple aggregation types and time-series data. -### Request body +## Error Handling -```json -{ - "start": "2024-01-01T00:00:00Z", - "end": "2024-01-01T23:59:59Z", - "metric": "cpu", - "instances": ["inst_123", "inst_456"], - "aggregations": ["avg", "max", "min"] -} -``` - -### Request body parameters - -| Parameter | Type | Description | -|-----------|------|-------------| -| start | string (date-time) | Start time for the metrics query | -| end | string (date-time) | End time for the metrics query | -| metric | string | Metric name to query. Options: `cpu`, `memory`, `disk` | -| instances | array | List of instance IDs to query | -| aggregations | array | List of aggregations to apply. Options: `avg`, `max`, `min` | - -### Response +The API uses standard HTTP status codes and returns error responses in the following format: ```json { - "start": "2024-01-01T00:00:00Z", - "end": "2024-01-01T23:59:59Z", - "metric": "cpu", - "unit": "percentage", - "series": [ - { - "instance": "inst_123", - "aggregation": "avg", - "data": [ - { - "timestamp": "2024-01-01T00:00:00Z", - "value": 25.5 - }, - { - "timestamp": "2024-01-01T01:00:00Z", - "value": 30.2 - } - ] - } - ] + "id": "error_identifier", + "message": "Human-readable error message explaining the issue" } ``` -### Metric types - -- **cpu**: CPU usage percentage -- **memory**: Memory usage in bytes -- **disk**: Disk usage in bytes - -### Aggregation types - -- **avg**: Average value over the time interval -- **max**: Maximum value over the time interval -- **min**: Minimum value over the time interval \ No newline at end of file +### Common error responses + +| Status | Error Type | Description | +|--------|------------|-------------| +| 400 | BadRequestError | Request was malformed or contained invalid parameters | +| 401 | AuthorizationError | Authentication failed or is missing | +| 404 | GenericError | Requested resource does not exist | +| 5XX | GenericError | Server error occurred | + +## Schema Reference + +### Core Data Models + +#### BranchListMetadata +Basic branch information returned when listing branches. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| id | string | Yes | Unique identifier for the branch | +| name | string | Yes | Human-readable name for the branch | +| createdAt | string (date-time) | Yes | Timestamp when the branch was created | +| updatedAt | string (date-time) | Yes | Timestamp when the branch was last updated | +| region | string | Yes | Geographic region where the branch is deployed | +| publicAccess | boolean | Yes | Whether the branch allows public access without authentication | +| description | string | No | Optional description of the branch purpose or contents | +| parentID | string | No | Identifier of the parent branch if this is a derived branch, null otherwise | + +#### BranchMetadata +Complete branch information including configuration and status details. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| id | string | Yes | Unique identifier for the branch | +| name | string | Yes | Human-readable name for the branch | +| createdAt | string (date-time) | Yes | Timestamp when the branch was created | +| updatedAt | string (date-time) | Yes | Timestamp when the branch was last updated | +| region | string | Yes | Geographic region where the branch is deployed | +| status | BranchStatus | Yes | Current operational status of the branch | +| connectionString | string | Yes | Database connection string for accessing this branch | +| configuration | ClusterConfiguration | Yes | Configuration details for the underlying database cluster | +| publicAccess | boolean | Yes | Whether the branch allows public access without authentication | +| scaleToZero | ScaleToZeroConfiguration | Yes | Scale to zero configuration for the branch | +| description | string | No | Optional description of the branch purpose or contents | +| parentID | string | No | Identifier of the parent branch if this is a derived branch, null otherwise | + +#### BranchShortMetadata +Simplified branch information returned for create/update operations. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| id | string | Yes | Unique identifier for the branch | +| name | string | Yes | Human-readable name for the branch | +| createdAt | string (date-time) | Yes | Timestamp when the branch was created | +| updatedAt | string (date-time) | Yes | Timestamp when the branch was last updated | +| region | string | Yes | Geographic region where the branch is deployed | +| publicAccess | boolean | Yes | Whether the branch allows public access without authentication | +| connectionString | string | No | Database connection string for accessing this branch | +| description | string | No | Optional description of the branch purpose or contents | +| parentID | string | No | Identifier of the parent branch if this is a derived branch, null otherwise | + +#### ClusterConfiguration +Database cluster configuration including image, instance type, and region. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| image | string | Yes | Database image to use (e.g., "postgresql:17") | +| instanceType | string | Yes | Instance type for the database cluster | +| instances | integer | Yes | Number of database instances | +| region | string | Yes | Geographic region for deployment | + +#### ScaleToZeroConfiguration +Configuration for automatic scaling to zero when branches are idle. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| enabled | boolean | Yes | Whether scale to zero is enabled | +| idleTime | integer | Yes | Time in seconds before scaling to zero when idle | + +#### BranchStatus +Operational status information including instance counts and lifecycle state. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| instanceCount | integer | Yes | Total number of instances for the branch | +| instanceReadyCount | integer | Yes | Number of instances that are ready | +| instances | array | Yes | Array of instance objects with status information | +| lifecycle | object | Yes | Lifecycle information including phase and message | + +#### BranchCredentials +Database access credentials for a specific branch. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| username | string | Yes | Username for accessing the branch database | +| password | string | Yes | Password for accessing the branch database | + +#### BranchCreationDetails +Details required when creating a new branch. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| name | string | Yes | Human-readable name for the new branch | +| description | string | No | Optional description for the branch purpose or contents (max 50 characters, pattern: `^[a-zA-Z0-9]+[a-zA-Z0-9- ]*$`) | +| parentID | string | No | If present, the branch will inherit the parent branch configuration and data | +| configuration | ClusterConfiguration | No | Configuration for the underlying database cluster if not inheriting from a parent | +| scaleToZero | ScaleToZeroConfiguration | No | Scale to zero configuration for the branch | + +#### BranchUpdateDetails +Details that can be updated for an existing branch. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| name | string | No | New name for the branch | +| description | string | No | New description for the branch | + +#### InstanceMetadata +Information about a specific database instance. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| id | string | Yes | Unique identifier for the instance | +| status | string | Yes | Current status of the instance | +| region | string | Yes | Geographic region where the instance is deployed | +| createdAt | string (date-time) | Yes | Timestamp when the instance was created | + +#### LifecycleInfo +Lifecycle information for a branch. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| phase | string | Yes | Current lifecycle phase (e.g., "running", "starting", "stopping") | +| message | string | Yes | Human-readable message describing the current state | \ No newline at end of file diff --git a/docs/api/index.mdx b/docs/api/index.mdx index 08f170f..ebfd432 100644 --- a/docs/api/index.mdx +++ b/docs/api/index.mdx @@ -57,8 +57,6 @@ The API is organized into the following sections: - [Get branch details](/api/branches#get-branch) - [Update branch](/api/branches#update-branch) - [Delete branch](/api/branches#delete-branch) -- [Get branch credentials](/api/branches#get-branch-credentials) -- [Get branch metrics](/api/branches#get-branch-metrics) #### Metrics - [Get branch metrics](/api/metrics#get-branch-metrics) diff --git a/docs/api/metrics.mdx b/docs/api/metrics.mdx index 06d8b50..91d60af 100644 --- a/docs/api/metrics.mdx +++ b/docs/api/metrics.mdx @@ -3,7 +3,16 @@ title: Metrics API description: Retrieve metrics and monitoring data for branches --- -The Metrics API allows you to retrieve performance and monitoring metrics for your database branches, including CPU, memory, and disk usage. +The Metrics API allows you to retrieve performance and monitoring metrics for your database branches, including CPU, memory, and disk usage. All endpoints require authentication via API key or OIDC. + +## Authentication + +All endpoints require authentication. You can authenticate using: +- **API Key**: Include your API key in the `Authorization` header: `Authorization: Bearer ` +- **OIDC**: Use OIDC tokens for authentication + +Required scopes for different operations: +- **metrics:read**: Access to metrics and monitoring data ## Get branch metrics @@ -13,13 +22,16 @@ Retrieves metrics for a specific branch over a time period. POST /organizations/{organizationID}/projects/{projectID}/branches/{branchID}/metrics ``` +### Summary +Returns time-series metrics data for CPU, memory, and disk usage across branch instances. Supports multiple aggregation types and can filter by specific instances. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| organizationID | string | Unique identifier for the organization | -| projectID | string | Unique identifier for the project | -| branchID | string | Unique identifier for the branch | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| organizationID | string | Yes | Unique identifier for the organization | +| projectID | string | Yes | Unique identifier for the project | +| branchID | string | Yes | Unique identifier for the branch | ### Request body @@ -35,16 +47,18 @@ POST /organizations/{organizationID}/projects/{projectID}/branches/{branchID}/me ### Request body parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| start | string (date-time) | Start time for the metrics query | -| end | string (date-time) | End time for the metrics query | -| metric | string | Metric name to query. Options: `cpu`, `memory`, `disk` | -| instances | array | List of instance IDs to query | -| aggregations | array | List of aggregations to apply. Options: `avg`, `max`, `min` | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| start | string (date-time) | Yes | Start time for the metrics query | +| end | string (date-time) | Yes | End time for the metrics query | +| metric | string | Yes | Metric name to query. Options: `cpu`, `memory`, `disk` | +| instances | array | Yes | List of instance IDs to query | +| aggregations | array | Yes | List of aggregations to apply. Options: `avg`, `max`, `min` | ### Response +**Status:** `200 OK` + ```json { "start": "2024-01-01T00:00:00Z", @@ -84,7 +98,7 @@ POST /organizations/{organizationID}/projects/{projectID}/branches/{branchID}/me } ``` -### Response fields +### Response schema | Field | Type | Description | |-------|------|-------------| @@ -104,4 +118,99 @@ POST /organizations/{organizationID}/projects/{projectID}/branches/{branchID}/me - **avg**: Average value over the time interval - **max**: Maximum value over the time interval -- **min**: Minimum value over the time interval \ No newline at end of file +- **min**: Minimum value over the time interval + +## Error Handling + +The API uses standard HTTP status codes and returns error responses in the following format: + +```json +{ + "id": "error_identifier", + "message": "Human-readable error message explaining the issue" +} +``` + +### Common error responses + +| Status | Error Type | Description | +|--------|------------|-------------| +| 400 | GenericError | Request was malformed or contained invalid parameters | +| 401 | AuthorizationError | Authentication failed or is missing | +| 404 | GenericError | Requested organization, project, or branch does not exist | +| 5XX | GenericError | Server error occurred | + +## Schema Reference + +### Core Data Models + +#### BranchMetrics +Time-series metrics data for monitoring branch performance. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| start | string (date-time) | Yes | Start time of the metrics period | +| end | string (date-time) | Yes | End time of the metrics period | +| metric | string | Yes | The metric type that was queried | +| unit | string | Yes | The unit of measurement (percentage, bytes, ms, etc.) | +| series | array | Yes | Array of metric series, one per instance and aggregation | + +#### BranchMetricsRequest +Parameters for querying branch metrics over a time period. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| start | string (date-time) | Yes | Start time for the metrics query | +| end | string (date-time) | Yes | End time for the metrics query | +| metric | string | Yes | Metric name to query. Options: `cpu`, `memory`, `disk` | +| instances | array | Yes | List of instance IDs to query | +| aggregations | array | Yes | List of aggregations to apply. Options: `avg`, `max`, `min` | + +#### MetricSeries +Individual metric series data for a specific instance and aggregation. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| instance | string | Yes | Instance ID for this metric series | +| aggregation | string | Yes | Aggregation type applied (avg, max, min) | +| data | array | Yes | Array of timestamp-value pairs | + +#### MetricDataPoint +Individual data point in a metric series. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| timestamp | string (date-time) | Yes | Timestamp for this data point | +| value | number | Yes | Metric value at this timestamp | + +## Usage Examples + +### Monitor CPU usage over time + +```bash +curl -X POST "https://api.xata.tech/organizations/org_123/projects/proj_456/branches/br_789/metrics" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "start": "2024-01-01T00:00:00Z", + "end": "2024-01-01T23:59:59Z", + "metric": "cpu", + "instances": ["inst_123"], + "aggregations": ["avg", "max"] + }' +``` + +### Check memory usage for multiple instances + +```bash +curl -X POST "https://api.xata.tech/organizations/org_123/projects/proj_456/branches/br_789/metrics" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "start": "2024-01-01T00:00:00Z", + "end": "2024-01-01T23:59:59Z", + "metric": "memory", + "instances": ["inst_123", "inst_456"], + "aggregations": ["avg"] + }' +``` \ No newline at end of file diff --git a/docs/api/organizations.mdx b/docs/api/organizations.mdx index bb1c97a..820f4b3 100644 --- a/docs/api/organizations.mdx +++ b/docs/api/organizations.mdx @@ -3,7 +3,16 @@ title: Organizations API description: Manage organizations and their settings --- -The Organizations API allows you to manage your Xata organizations, including listing, creating, updating, and deleting organizations. +The Organizations API allows you to manage your Xata organizations, including listing, creating, updating, and deleting organizations. All endpoints require authentication via API key or OIDC. + +## Authentication + +All endpoints require authentication. You can authenticate using: +- **API Key**: Include your API key in the `Authorization` header: `Authorization: Bearer ` +- **OIDC**: Use OIDC tokens for authentication + +Required scopes for different operations: +- **project:read**: Read organization information and list available regions ## List organizations @@ -13,8 +22,13 @@ Retrieves a list of all organizations you have access to. GET /organizations ``` +### Summary +Returns a list of all organizations that the authenticated user has access to, including basic metadata such as ID, name, and creation/update timestamps. + ### Response +**Status:** `200 OK` + ```json { "organizations": [ @@ -28,6 +42,16 @@ GET /organizations } ``` +### Response schema + +| Field | Type | Description | +|-------|------|-------------| +| organizations | array | Array of organization objects | +| id | string | Unique identifier for the organization | +| name | string | Human-readable name for the organization | +| createdAt | string (date-time) | Timestamp when the organization was created | +| updatedAt | string (date-time) | Timestamp when the organization was last updated | + ## Get organization Retrieves detailed information about a specific organization. @@ -36,14 +60,19 @@ Retrieves detailed information about a specific organization. GET /organizations/{organizationID} ``` +### Summary +Returns comprehensive information about a specific organization by its ID, including all metadata and settings. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| organizationID | string | Unique identifier for the organization | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| organizationID | string | Yes | Unique identifier for the organization | ### Response +**Status:** `200 OK` + ```json { "id": "org_123", @@ -53,6 +82,15 @@ GET /organizations/{organizationID} } ``` +### Response schema + +| Field | Type | Description | +|-------|------|-------------| +| id | string | Unique identifier for the organization | +| name | string | Human-readable name for the organization | +| createdAt | string (date-time) | Timestamp when the organization was created | +| updatedAt | string (date-time) | Timestamp when the organization was last updated | + ## Update organization Updates the name of an organization. @@ -61,11 +99,14 @@ Updates the name of an organization. PATCH /organizations/{organizationID} ``` +### Summary +Updates the organization's name. This is the only field that can be modified for an existing organization. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| organizationID | string | Unique identifier for the organization | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| organizationID | string | Yes | Unique identifier for the organization | ### Request body @@ -75,8 +116,16 @@ PATCH /organizations/{organizationID} } ``` +### Request body parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| name | string | Yes | New name for the organization | + ### Response +**Status:** `200 OK` + ```json { "id": "org_123", @@ -86,6 +135,15 @@ PATCH /organizations/{organizationID} } ``` +### Response schema + +| Field | Type | Description | +|-------|------|-------------| +| id | string | Unique identifier for the organization | +| name | string | Updated name for the organization | +| createdAt | string (date-time) | Timestamp when the organization was created | +| updatedAt | string (date-time) | Timestamp when the organization was last updated | + ## Delete organization Permanently deletes an organization and all its associated data. This action cannot be undone. @@ -94,51 +152,117 @@ Permanently deletes an organization and all its associated data. This action can DELETE /organizations/{organizationID} ``` +### Summary +Permanently removes an organization and all associated projects, branches, and data. This is a destructive operation that cannot be reversed. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| organizationID | string | Unique identifier for the organization | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| organizationID | string | Yes | Unique identifier for the organization | ### Response -Returns a 204 status code with no content on success. +**Status:** `204 No Content` + +No response body is returned on successful deletion. ## Get available regions -Retrieves a list of all regions where new branches can be deployed for the specified organization. +Retrieves a list of all regions where new projects can be deployed within an organization. ```bash GET /organizations/{organizationID}/regions ``` +### Summary +Returns a list of available geographic regions where new projects and branches can be deployed, along with information about public access capabilities for each region. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| organizationID | string | Unique identifier for the organization | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| organizationID | string | Yes | Unique identifier for the organization | ### Response +**Status:** `200 OK` + ```json { "regions": [ { "id": "us-east-1", - "publicAccess": true + "publicAccess": false }, { "id": "eu-west-1", - "publicAccess": false + "publicAccess": true } ] } ``` -### Response fields +### Response schema | Field | Type | Description | |-------|------|-------------| -| regions | array | Array of available regions with their properties | +| regions | array | Array of available regions | | id | string | Unique identifier for the region | -| publicAccess | boolean | Whether data plane is public-facing to the internet in this region | \ No newline at end of file +| publicAccess | boolean | Whether data plane is public-facing to the internet in this region | + +## Error Handling + +The API uses standard HTTP status codes and returns error responses in the following format: + +```json +{ + "id": "error_identifier", + "message": "Human-readable error message explaining the issue" +} +``` + +### Common error responses + +| Status | Error Type | Description | +|--------|------------|-------------| +| 400 | GenericError | Request was malformed or contained invalid parameters | +| 401 | AuthorizationError | Authentication failed or is missing | +| 404 | GenericError | Requested organization does not exist | +| 5XX | GenericError | Server error occurred | + +## Schema Reference + +### Core Data Models + +#### Organization +Basic organization information. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| id | string | Yes | Unique identifier for the organization | +| name | string | Yes | Human-readable name for the organization | +| createdAt | string (date-time) | Yes | Timestamp when the organization was created | +| updatedAt | string (date-time) | Yes | Timestamp when the organization was last updated | + +#### OrganizationID +Unique identifier for an organization. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| value | string | Yes | The organization ID string | + +#### Region +Information about an available deployment region. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| id | string | Yes | Unique identifier for the region | +| publicAccess | boolean | Yes | Whether data plane is public-facing to the internet in this region | + +#### OrganizationUpdateRequest +Request body for updating organization details. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| name | string | Yes | New name for the organization | \ No newline at end of file diff --git a/docs/api/projects.mdx b/docs/api/projects.mdx index b1fe6b5..0389ee3 100644 --- a/docs/api/projects.mdx +++ b/docs/api/projects.mdx @@ -3,7 +3,17 @@ title: Projects API description: Manage projects and their settings --- -The Projects API allows you to manage your Xata projects, including listing, creating, updating, and deleting projects. +The Projects API allows you to manage your Xata projects, including listing, creating, updating, and deleting projects. All endpoints require authentication via API key or OIDC. + +## Authentication + +All endpoints require authentication. You can authenticate using: +- **API Key**: Include your API key in the `Authorization` header: `Authorization: Bearer ` +- **OIDC**: Use OIDC tokens for authentication + +Required scopes for different operations: +- **project:read**: Read project information and list projects +- **project:write**: Create, update, and delete projects ## List projects @@ -13,14 +23,19 @@ Retrieves a list of all projects within an organization. GET /organizations/{organizationID}/projects ``` +### Summary +Returns a paginated list of projects in an organization with basic metadata including ID, name, creation date, and update timestamp. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| organizationID | string | Unique identifier for the organization | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| organizationID | string | Yes | Unique identifier for the organization | ### Response +**Status:** `200 OK` + ```json { "projects": [ @@ -34,6 +49,16 @@ GET /organizations/{organizationID}/projects } ``` +### Response schema + +| Field | Type | Description | +|-------|------|-------------| +| projects | array | Array of project objects | +| id | string | Unique identifier for the project | +| name | string | Human-readable name for the project | +| createdAt | string (date-time) | Timestamp when the project was created | +| updatedAt | string (date-time) | Timestamp when the project was last updated | + ## Create project Creates a new project within an organization. @@ -42,11 +67,14 @@ Creates a new project within an organization. POST /organizations/{organizationID}/projects ``` +### Summary +Creates a new project with the specified name. The project will be created in the organization's default region. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| organizationID | string | Unique identifier for the organization | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| organizationID | string | Yes | Unique identifier for the organization | ### Request body @@ -58,12 +86,14 @@ POST /organizations/{organizationID}/projects ### Request body parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| name | string | Human-readable name for the new project | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| name | string | Yes | Human-readable name for the new project | ### Response +**Status:** `201 Created` + ```json { "id": "proj_123", @@ -73,6 +103,15 @@ POST /organizations/{organizationID}/projects } ``` +### Response schema + +| Field | Type | Description | +|-------|------|-------------| +| id | string | Unique identifier for the created project | +| name | string | Name of the project | +| createdAt | string (date-time) | Timestamp when the project was created | +| updatedAt | string (date-time) | Timestamp when the project was last updated | + ## Get project Retrieves detailed information about a specific project. @@ -81,15 +120,20 @@ Retrieves detailed information about a specific project. GET /organizations/{organizationID}/projects/{projectID} ``` +### Summary +Returns comprehensive information about a project including all metadata and settings. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| organizationID | string | Unique identifier for the organization | -| projectID | string | Unique identifier for the project | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| organizationID | string | Yes | Unique identifier for the organization | +| projectID | string | Yes | Unique identifier for the project | ### Response +**Status:** `200 OK` + ```json { "id": "proj_123", @@ -99,20 +143,32 @@ GET /organizations/{organizationID}/projects/{projectID} } ``` +### Response schema + +| Field | Type | Description | +|-------|------|-------------| +| id | string | Unique identifier for the project | +| name | string | Human-readable name for the project | +| createdAt | string (date-time) | Timestamp when the project was created | +| updatedAt | string (date-time) | Timestamp when the project was last updated | + ## Update project -Updates the name of a project. +Updates the configuration of a project. ```bash PATCH /organizations/{organizationID}/projects/{projectID} ``` +### Summary +Updates project metadata such as name. Note that most project configuration changes require creating a new project. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| organizationID | string | Unique identifier for the organization | -| projectID | string | Unique identifier for the project | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| organizationID | string | Yes | Unique identifier for the organization | +| projectID | string | Yes | Unique identifier for the project | ### Request body @@ -124,12 +180,14 @@ PATCH /organizations/{organizationID}/projects/{projectID} ### Request body parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| name | string | New name for the project | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| name | string | No | New name for the project | ### Response +**Status:** `200 OK` + ```json { "id": "proj_123", @@ -139,60 +197,136 @@ PATCH /organizations/{organizationID}/projects/{projectID} } ``` +### Response schema + +| Field | Type | Description | +|-------|------|-------------| +| id | string | Unique identifier for the project | +| name | string | Updated name for the project | +| createdAt | string (date-time) | Timestamp when the project was created | +| updatedAt | string (date-time) | Timestamp when the project was last updated | + ## Delete project -Permanently deletes a project and all its associated data. This action cannot be undone. +Permanently deletes a project and all its associated data. ```bash DELETE /organizations/{organizationID}/projects/{projectID} ``` +### Summary +Permanently removes a project and all associated branches and data. This action cannot be undone and will terminate all active connections. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| organizationID | string | Unique identifier for the organization | -| projectID | string | Unique identifier for the project | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| organizationID | string | Yes | Unique identifier for the organization | +| projectID | string | Yes | Unique identifier for the project | ### Response -Returns a 204 status code with no content on success. +**Status:** `204 No Content` + +No response body is returned on successful deletion. ## Get available regions -Retrieves a list of all regions where new branches can be deployed for the specified organization. +Retrieves a list of all regions where new branches can be deployed within a project. ```bash -GET /organizations/{organizationID}/regions +GET /organizations/{organizationID}/projects/{projectID}/regions ``` +### Summary +Returns a list of available geographic regions where new branches can be deployed within the specified project, along with information about public access capabilities for each region. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| organizationID | string | Unique identifier for the organization | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| organizationID | string | Yes | Unique identifier for the organization | +| projectID | string | Yes | Unique identifier for the project | ### Response +**Status:** `200 OK` + ```json { "regions": [ { "id": "us-east-1", - "publicAccess": true + "publicAccess": false }, { "id": "eu-west-1", - "publicAccess": false + "publicAccess": true } ] } ``` -### Response fields +### Response schema | Field | Type | Description | |-------|------|-------------| -| regions | array | Array of available regions with their properties | +| regions | array | Array of available regions | | id | string | Unique identifier for the region | -| publicAccess | boolean | Whether data plane is public-facing to the internet in this region | \ No newline at end of file +| publicAccess | boolean | Whether data plane is public-facing to the internet in this region | + +## Error Handling + +The API uses standard HTTP status codes and returns error responses in the following format: + +```json +{ + "id": "error_identifier", + "message": "Human-readable error message explaining the issue" +} +``` + +### Common error responses + +| Status | Error Type | Description | +|--------|------------|-------------| +| 400 | GenericError | Request was malformed or contained invalid parameters | +| 401 | AuthorizationError | Authentication failed or is missing | +| 404 | GenericError | Requested organization or project does not exist | +| 5XX | GenericError | Server error occurred | + +## Schema Reference + +### Core Data Models + +#### Project +Basic project information. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| id | string | Yes | Unique identifier for the project | +| name | string | Yes | Human-readable name for the project | +| createdAt | string (date-time) | Yes | Timestamp when the project was created | +| updatedAt | string (date-time) | Yes | Timestamp when the project was last updated | + +#### ProjectCreationRequest +Request body for creating a new project. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| name | string | Yes | Human-readable name for the new project | + +#### ProjectUpdateRequest +Request body for updating project details. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| name | string | No | New name for the project | + +#### Region +Information about an available deployment region. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| id | string | Yes | Unique identifier for the region | +| publicAccess | boolean | Yes | Whether data plane is public-facing to the internet in this region | \ No newline at end of file diff --git a/docs/api/users.mdx b/docs/api/users.mdx index c1bb482..02fd442 100644 --- a/docs/api/users.mdx +++ b/docs/api/users.mdx @@ -3,7 +3,17 @@ title: Users API description: Manage user accounts and profiles --- -The Users API allows you to manage user accounts within your Xata organization, including listing, retrieving, updating, and deleting user accounts. +The Users API allows you to manage user accounts within your Xata organization, including listing, retrieving, updating, and deleting user accounts. All endpoints require authentication via API key or OIDC. + +## Authentication + +All endpoints require authentication. You can authenticate using: +- **API Key**: Include your API key in the `Authorization` header: `Authorization: Bearer ` +- **OIDC**: Use OIDC tokens for authentication + +Required scopes for different operations: +- **user:read**: Read user information and list users +- **user:write**: Update and delete user accounts ## List users @@ -13,8 +23,13 @@ Retrieves a list of all users in an organization. GET /users ``` +### Summary +Returns a list of all users in the authenticated user's organization, including basic profile information such as ID, email, name, and timestamps. + ### Response +**Status:** `200 OK` + ```json { "users": [ @@ -29,6 +44,17 @@ GET /users } ``` +### Response schema + +| Field | Type | Description | +|-------|------|-------------| +| users | array | Array of user objects | +| id | string | Unique identifier for the user | +| email | string | Email address of the user | +| name | string | Human-readable name for the user | +| createdAt | string (date-time) | Timestamp when the user account was created | +| updatedAt | string (date-time) | Timestamp when the user account was last updated | + ## Get user Retrieves detailed information about a specific user. @@ -37,14 +63,19 @@ Retrieves detailed information about a specific user. GET /users/{userID} ``` +### Summary +Returns comprehensive information about a specific user by their ID, including all profile details and account metadata. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| userID | string | Unique identifier for the user | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| userID | string | Yes | Unique identifier for the user | ### Response +**Status:** `200 OK` + ```json { "id": "user_123", @@ -55,6 +86,16 @@ GET /users/{userID} } ``` +### Response schema + +| Field | Type | Description | +|-------|------|-------------| +| id | string | Unique identifier for the user | +| email | string | Email address of the user | +| name | string | Human-readable name for the user | +| createdAt | string (date-time) | Timestamp when the user account was created | +| updatedAt | string (date-time) | Timestamp when the user account was last updated | + ## Update user Updates user information within an organization. @@ -63,11 +104,14 @@ Updates user information within an organization. PATCH /users/{userID} ``` +### Summary +Updates the user's profile information such as name and email address. Note that some fields may be restricted based on the authenticated user's permissions. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| userID | string | Unique identifier for the user | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| userID | string | Yes | Unique identifier for the user | ### Request body @@ -78,8 +122,17 @@ PATCH /users/{userID} } ``` +### Request body parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| name | string | No | New name for the user | +| email | string | No | New email address for the user | + ### Response +**Status:** `200 OK` + ```json { "id": "user_123", @@ -90,6 +143,16 @@ PATCH /users/{userID} } ``` +### Response schema + +| Field | Type | Description | +|-------|------|-------------| +| id | string | Unique identifier for the user | +| email | string | Updated email address of the user | +| name | string | Updated name for the user | +| createdAt | string (date-time) | Timestamp when the user account was created | +| updatedAt | string (date-time) | Timestamp when the user account was last updated | + ## Delete user Removes a user from an organization. @@ -98,12 +161,67 @@ Removes a user from an organization. DELETE /users/{userID} ``` +### Summary +Permanently removes a user from the organization. This action cannot be undone and will revoke all access for the specified user. + ### Path parameters -| Parameter | Type | Description | -|-----------|------|-------------| -| userID | string | Unique identifier for the user | +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| userID | string | Yes | Unique identifier for the user | ### Response -Returns a 204 status code with no content on success. \ No newline at end of file +**Status:** `204 No Content` + +No response body is returned on successful deletion. + +## Error Handling + +The API uses standard HTTP status codes and returns error responses in the following format: + +```json +{ + "id": "error_identifier", + "message": "Human-readable error message explaining the issue" +} +``` + +### Common error responses + +| Status | Error Type | Description | +|--------|------------|-------------| +| 400 | GenericError | Request was malformed or contained invalid parameters | +| 401 | AuthorizationError | Authentication failed or is missing | +| 404 | GenericError | Requested user does not exist | +| 5XX | GenericError | Server error occurred | + +## Schema Reference + +### Core Data Models + +#### User +Basic user information. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| id | string | Yes | Unique identifier for the user | +| email | string | Yes | Email address of the user | +| name | string | Yes | Human-readable name for the user | +| createdAt | string (date-time) | Yes | Timestamp when the user account was created | +| updatedAt | string (date-time) | Yes | Timestamp when the user account was last updated | + +#### UserID +Unique identifier for a user account. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| value | string | Yes | The user ID string | + +#### UserUpdateRequest +Request body for updating user details. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| name | string | No | New name for the user | +| email | string | No | New email address for the user | \ No newline at end of file From add3773cc6ed1f4707e3998db5b6615428a9fcb4 Mon Sep 17 00:00:00 2001 From: alexfrancoeur Date: Mon, 11 Aug 2025 09:55:24 -0400 Subject: [PATCH 6/6] notice to contact support for preload extensions --- docs/extensions/index.mdx | 138 +++++++++++++++++++------------------- 1 file changed, 69 insertions(+), 69 deletions(-) diff --git a/docs/extensions/index.mdx b/docs/extensions/index.mdx index 1837a34..195c9a0 100644 --- a/docs/extensions/index.mdx +++ b/docs/extensions/index.mdx @@ -5,75 +5,75 @@ description: All extensions listed below are currently available for PostgreSQL ## Available PostgreSQL extensions -| Extension | Description | Version | -|-----------|-------------|---------| -| [address_standardizer](https://postgis.net/docs/Extras.html#Address_Standardizer) | Standardizes address data using rules-based parsing | 3.5.3 | -| [address_standardizer_data_us](https://postgis.net/docs/Extras.html#Address_Standardizer_Tables) | US address data for address_standardizer | 3.5.3 | -| [amcheck](https://www.postgresql.org/docs/current/amcheck.html) | Functions for verifying relation integrity | 1.4 | -| [auto_explain](https://www.postgresql.org/docs/current/auto-explain.html) | Automatic query plan logging | 1.0 | -| [autoinc](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.8) | Functions for automatic increment of fields | 1.0 | -| [bloom](https://www.postgresql.org/docs/current/bloom.html) | Bloom index access method | 1.0 | -| [btree_gin](https://www.postgresql.org/docs/current/btree-gin.html) | Support for indexing common datatypes in GIN | 1.3 | -| [btree_gist](https://www.postgresql.org/docs/current/btree-gist.html) | Support for indexing common datatypes in GiST | 1.7 | -| [citext](https://www.postgresql.org/docs/current/citext.html) | Case-insensitive text data type | 1.6 | -| [cube](https://www.postgresql.org/docs/current/cube.html) | Multi-dimensional cube data type | 1.5 | -| [dblink](https://www.postgresql.org/docs/current/dblink.html) | Cross-database queries | 1.2 | -| [dict_int](https://www.postgresql.org/docs/current/dict-int.html) | Text search dictionary template for integers | 1.0 | -| [dict_xsyn](https://www.postgresql.org/docs/current/dict-xsyn.html) | Text search dictionary template for synonyms | 1.0 | -| [earthdistance](https://www.postgresql.org/docs/current/earthdistance.html) | Earth distance calculations | 1.2 | -| [file_fdw](https://www.postgresql.org/docs/current/file-fdw.html) | Foreign data wrapper for flat file access | 1.0 | -| [fuzzystrmatch](https://www.postgresql.org/docs/current/fuzzystrmatch.html) | Determine similarities and distance between strings | 1.2 | -| [hll](https://github.com/citusdata/postgresql-hll) | HyperLogLog data type for cardinality estimation | 2.18 | -| [hstore](https://www.postgresql.org/docs/current/hstore.html) | Key-value store data type | 1.8 | -| [hypopg](https://hypopg.readthedocs.io/) | Hypothetical indexes for query planning | 1.4.2 | -| [intagg](https://www.postgresql.org/docs/current/intagg.html) | Integer aggregator (deprecated in favor of array_agg) | 1.1 | -| [intarray](https://www.postgresql.org/docs/current/intarray.html) | Functions for 1-D arrays of integers | 1.5 | -| [insert_username](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.9) | Automatic username insertion | 1.0 | -| [ip4r](https://github.com/RhodiumToad/ip4r) | IPv4 and IPv6 types and functions | 2.4 | -| [isn](https://www.postgresql.org/docs/current/isn.html) | International Standard Number data types | 1.2 | -| [lo](https://www.postgresql.org/docs/current/lo.html) | Large Object maintenance functions | 1.1 | -| [ltree](https://www.postgresql.org/docs/current/ltree.html) | Tree-like structures data type | 1.3 | -| [moddatetime](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.10) | Automatic timestamp updates | 1.0 | -| [pageinspect](https://www.postgresql.org/docs/current/pageinspect.html) | Low-level page inspection | 1.12 | -| [pg_buffercache](https://www.postgresql.org/docs/current/pgbuffercache.html) | Buffer cache inspection | 1.5 | -| [pg_cron](https://github.com/citusdata/pg_cron) | Job scheduler for PostgreSQL | 1.6 | -| [pg_freespacemap](https://www.postgresql.org/docs/current/pgfreespacemap.html) | Free space map examination | 1.2 | -| [pg_hint_plan](https://github.com/ossc-db/pg_hint_plan) | Query execution plan hinting | 1.7.0 | -| [pg_partman](https://github.com/pgpartman/pg_partman) | Partition management extension for PostgreSQL | 5.2.4 | -| [pg_prewarm](https://www.postgresql.org/docs/current/pgprewarm.html) | Database prewarming | 1.2 | -| [pg_repack](https://github.com/reorg/pg_repack) | Remove bloat from tables and indexes without exclusive lock | 1.5.2 | -| [pg_surgery](https://www.postgresql.org/docs/current/pgsurgery.html) | Row surgery functions for modifying rows | 1.0 | -| [pg_trgm](https://www.postgresql.org/docs/current/pgtrgm.html) | Trigram matching for similarity searches | 1.6 | -| [pg_visibility](https://www.postgresql.org/docs/current/pgvisibility.html) | Visibility map examination | 1.2 | -| [pg_walinspect](https://www.postgresql.org/docs/current/pgwalinspect.html) | WAL inspection functions | 1.1 | -| [pgrowlocks](https://www.postgresql.org/docs/current/pgrowlocks.html) | Row locking information | 1.2 | -| [pg_stat_statements](https://www.postgresql.org/docs/current/pgstatstatements.html) | Query execution statistics | 1.11 | -| [pg_stattuple](https://www.postgresql.org/docs/current/pgstattuple.html) | Functions to show tuple-level statistics | 1.5 | -| [pgaudit](https://github.com/pgaudit/pgaudit) | Audit logging extension for PostgreSQL | 17.1 | -| [pgcrypto](https://www.postgresql.org/docs/current/pgcrypto.html) | Cryptographic functions | 1.3 | -| [pgrouting](https://docs.pgrouting.org/) | Routing functionality for PostGIS/PostgreSQL | 3.8.0 | -| [pglogical](https://github.com/2ndQuadrant/pglogical) | Logical replication extension for PostgreSQL | 2.4.5 | -| [pgtap](https://pgtap.org/) | Unit testing framework for PostgreSQL | 1.3.3 | -| [plpgsql](https://www.postgresql.org/docs/current/plpgsql.html) | PL/pgSQL procedural language | 1.0 | -| [postgres_fdw](https://www.postgresql.org/docs/current/postgres-fdw.html) | Foreign data wrapper for PostgreSQL | 1.1 | -| [postgis](https://postgis.net/) | PostGIS geometry and geography spatial types and functions | 3.5.3 | -| [postgis_raster](https://postgis.net/docs/RT_reference.html) | PostGIS raster extension | 3.5.3 | -| [postgis_sfcgal](https://postgis.net/docs/SFCGAL_User_Manual.html) | PostGIS SFCGAL support | 3.5.3 | -| [postgis_tiger_geocoder](https://postgis.net/docs/Extras.html#Tiger_Geocoder) | PostGIS tiger geocoder and reverse geocoder | 3.5.3 | -| [postgis_topology](https://postgis.net/docs/Topology.html) | PostGIS topology spatial types and functions | 3.5.3 | -| [prefix](https://github.com/dimitri/prefix) | Prefix matching operator | 1.2.0 | -| [refint](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.11) | Referential integrity triggers (example) | 1.0 | -| [seg](https://www.postgresql.org/docs/current/seg.html) | Floating-point intervals | 1.4 | -| [sslinfo](https://www.postgresql.org/docs/current/sslinfo.html) | Information about SSL connections | 1.2 | -| [tablefunc](https://www.postgresql.org/docs/current/tablefunc.html) | Functions that manipulate whole tables, including crosstab | 1.0 | -| [tcn](https://www.postgresql.org/docs/current/tcn.html) | Triggered change notifications | 1.0 | -| [tsm_system_rows](https://www.postgresql.org/docs/current/tsm-system-rows.html) | TABLESAMPLE method which accepts number of rows | 1.0 | -| [tsm_system_time](https://www.postgresql.org/docs/current/tsm-system-time.html) | TABLESAMPLE method which accepts time in milliseconds | 1.0 | -| [unaccent](https://www.postgresql.org/docs/current/unaccent.html) | Text search dictionary that removes accents | 1.1 | -| [uuid-ossp](https://www.postgresql.org/docs/current/uuid-ossp.html) | UUID generation functions | 1.1 | -| [vector](https://github.com/pgvector/pgvector) | Vector similarity search for PostgreSQL | 0.8.0 | -| [wal2json](https://github.com/eulerto/wal2json) | Logical replication output plugin for JSON | 2.6 | -| [xml2](https://www.postgresql.org/docs/current/xml2.html) | XPath querying and XSLT support | 1.1 | +| Extension | Description | Version | Prerequisites | +|-----------|-------------|---------|---------------| +| [address_standardizer](https://postgis.net/docs/Extras.html#Address_Standardizer) | Standardizes address data using rules-based parsing | 3.5.3 | | +| [address_standardizer_data_us](https://postgis.net/docs/Extras.html#Address_Standardizer_Tables) | US address data for address_standardizer | 3.5.3 | | +| [amcheck](https://www.postgresql.org/docs/current/amcheck.html) | Functions for verifying relation integrity | 1.4 | | +| [auto_explain](https://www.postgresql.org/docs/current/auto-explain.html) | Automatic query plan logging | 1.0 | This extension must be enabled by Xata support. Please [open a support ticket](https://support.xata.io/hc/en-us/requests/new) with your branch id for the request. | +| [autoinc](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.8) | Functions for automatic increment of fields | 1.0 | | +| [bloom](https://www.postgresql.org/docs/current/bloom.html) | Bloom index access method | 1.0 | | +| [btree_gin](https://www.postgresql.org/docs/current/btree-gin.html) | Support for indexing common datatypes in GIN | 1.3 | | +| [btree_gist](https://www.postgresql.org/docs/current/btree-gist.html) | Support for indexing common datatypes in GiST | 1.7 | | +| [citext](https://www.postgresql.org/docs/current/citext.html) | Case-insensitive text data type | 1.6 | | +| [cube](https://www.postgresql.org/docs/current/cube.html) | Multi-dimensional cube data type | 1.5 | | +| [dblink](https://www.postgresql.org/docs/current/dblink.html) | Cross-database queries | 1.2 | | +| [dict_int](https://www.postgresql.org/docs/current/dict-int.html) | Text search dictionary template for integers | 1.0 | | +| [dict_xsyn](https://www.postgresql.org/docs/current/dict-xsyn.html) | Text search dictionary template for synonyms | 1.0 | | +| [earthdistance](https://www.postgresql.org/docs/current/earthdistance.html) | Earth distance calculations | 1.2 | | +| [file_fdw](https://www.postgresql.org/docs/current/file-fdw.html) | Foreign data wrapper for flat file access | 1.0 | | +| [fuzzystrmatch](https://www.postgresql.org/docs/current/fuzzystrmatch.html) | Determine similarities and distance between strings | 1.2 | | +| [hll](https://github.com/citusdata/postgresql-hll) | HyperLogLog data type for cardinality estimation | 2.18 | | +| [hstore](https://www.postgresql.org/docs/current/hstore.html) | Key-value store data type | 1.8 | | +| [hypopg](https://hypopg.readthedocs.io/) | Hypothetical indexes for query planning | 1.4.2 | | +| [intagg](https://www.postgresql.org/docs/current/intagg.html) | Integer aggregator (deprecated in favor of array_agg) | 1.1 | | +| [intarray](https://www.postgresql.org/docs/current/intarray.html) | Functions for 1-D arrays of integers | 1.5 | | +| [insert_username](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.9) | Automatic username insertion | 1.0 | | +| [ip4r](https://github.com/RhodiumToad/ip4r) | IPv4 and IPv6 types and functions | 2.4 | | +| [isn](https://www.postgresql.org/docs/current/isn.html) | International Standard Number data types | 1.2 | | +| [lo](https://www.postgresql.org/docs/current/lo.html) | Large Object maintenance functions | 1.1 | | +| [ltree](https://www.postgresql.org/docs/current/ltree.html) | Tree-like structures data type | 1.3 | | +| [moddatetime](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.10) | Automatic timestamp updates | 1.0 | | +| [pageinspect](https://www.postgresql.org/docs/current/pageinspect.html) | Low-level page inspection | 1.12 | | +| [pg_buffercache](https://www.postgresql.org/docs/current/pgbuffercache.html) | Buffer cache inspection | 1.5 | | +| [pg_cron](https://github.com/citusdata/pg_cron) | Job scheduler for PostgreSQL | 1.6 | This extension must be enabled by Xata support. Please [open a support ticket](https://support.xata.io/hc/en-us/requests/new) with your branch id for the request. | +| [pg_freespacemap](https://www.postgresql.org/docs/current/pgfreespacemap.html) | Free space map examination | 1.2 | | +| [pg_hint_plan](https://github.com/ossc-db/pg_hint_plan) | Query execution plan hinting | 1.7.0 | This extension must be enabled by Xata support. Please [open a support ticket](https://support.xata.io/hc/en-us/requests/new) with your branch id for the request. | +| [pg_partman](https://github.com/pgpartman/pg_partman) | Partition management extension for PostgreSQL | 5.2.4 | | +| [pg_prewarm](https://www.postgresql.org/docs/current/pgprewarm.html) | Database prewarming | 1.2 | This extension must be enabled by Xata support. Please [open a support ticket](https://support.xata.io/hc/en-us/requests/new) with your branch id for the request. | +| [pg_repack](https://github.com/reorg/pg_repack) | Remove bloat from tables and indexes without exclusive lock | 1.5.2 | | +| [pg_surgery](https://www.postgresql.org/docs/current/pgsurgery.html) | Row surgery functions for modifying rows | 1.0 | | +| [pg_trgm](https://www.postgresql.org/docs/current/pgtrgm.html) | Trigram matching for similarity searches | 1.6 | | +| [pg_visibility](https://www.postgresql.org/docs/current/pgvisibility.html) | Visibility map examination | 1.2 | | +| [pg_walinspect](https://www.postgresql.org/docs/current/pgwalinspect.html) | WAL inspection functions | 1.1 | | +| [pgrowlocks](https://www.postgresql.org/docs/current/pgrowlocks.html) | Row locking information | 1.2 | | +| [pg_stat_statements](https://www.postgresql.org/docs/current/pgstatstatements.html) | Query execution statistics | 1.11 | This extension must be enabled by Xata support. Please [open a support ticket](https://support.xata.io/hc/en-us/requests/new) with your branch id for the request. | +| [pg_stattuple](https://www.postgresql.org/docs/current/pgstattuple.html) | Functions to show tuple-level statistics | 1.5 | | +| [pgaudit](https://github.com/pgaudit/pgaudit) | Audit logging extension for PostgreSQL | 17.1 | This extension must be enabled by Xata support. Please [open a support ticket](https://support.xata.io/hc/en-us/requests/new) with your branch id for the request. | +| [pgcrypto](https://www.postgresql.org/docs/current/pgcrypto.html) | Cryptographic functions | 1.3 | | +| [pgrouting](https://docs.pgrouting.org/) | Routing functionality for PostGIS/PostgreSQL | 3.8.0 | | +| [pglogical](https://github.com/2ndQuadrant/pglogical) | Logical replication extension for PostgreSQL | 2.4.5 | This extension must be enabled by Xata support. Please [open a support ticket](https://support.xata.io/hc/en-us/requests/new) with your branch id for the request. | +| [pgtap](https://pgtap.org/) | Unit testing framework for PostgreSQL | 1.3.3 | | +| [plpgsql](https://www.postgresql.org/docs/current/plpgsql.html) | PL/pgSQL procedural language | 1.0 | | +| [postgres_fdw](https://www.postgresql.org/docs/current/postgres-fdw.html) | Foreign data wrapper for PostgreSQL | 1.1 | | +| [postgis](https://postgis.net/) | PostGIS geometry and geography spatial types and functions | 3.5.3 | | +| [postgis_raster](https://postgis.net/docs/RT_reference.html) | PostGIS raster extension | 3.5.3 | | +| [postgis_sfcgal](https://postgis.net/docs/SFCGAL_User_Manual.html) | PostGIS SFCGAL support | 3.5.3 | | +| [postgis_tiger_geocoder](https://postgis.net/docs/Extras.html#Tiger_Geocoder) | PostGIS tiger geocoder and reverse geocoder | 3.5.3 | | +| [postgis_topology](https://postgis.net/docs/Topology.html) | PostGIS topology spatial types and functions | 3.5.3 | | +| [prefix](https://github.com/dimitri/prefix) | Prefix matching operator | 1.2.0 | | +| [refint](https://www.postgresql.org/docs/current/contrib-spi.html#id-1.11.7.47.11) | Referential integrity triggers (example) | 1.0 | | +| [seg](https://www.postgresql.org/docs/current/seg.html) | Floating-point intervals | 1.4 | | +| [sslinfo](https://www.postgresql.org/docs/current/sslinfo.html) | Information about SSL connections | 1.2 | | +| [tablefunc](https://www.postgresql.org/docs/current/tablefunc.html) | Functions that manipulate whole tables, including crosstab | 1.0 | | +| [tcn](https://www.postgresql.org/docs/current/tcn.html) | Triggered change notifications | 1.0 | | +| [tsm_system_rows](https://www.postgresql.org/docs/current/tsm-system-rows.html) | TABLESAMPLE method which accepts number of rows | 1.0 | | +| [tsm_system_time](https://www.postgresql.org/docs/current/tsm-system-time.html) | TABLESAMPLE method which accepts time in milliseconds | 1.0 | | +| [unaccent](https://www.postgresql.org/docs/current/unaccent.html) | Text search dictionary that removes accents | 1.1 | | +| [uuid-ossp](https://www.postgresql.org/docs/current/uuid-ossp.html) | UUID generation functions | 1.1 | | +| [vector](https://github.com/pgvector/pgvector) | Vector similarity search for PostgreSQL | 0.8.0 | | +| [wal2json](https://github.com/eulerto/wal2json) | Logical replication output plugin for JSON | 2.6 | | +| [xml2](https://www.postgresql.org/docs/current/xml2.html) | XPath querying and XSLT support | 1.1 | | ## Request an extension