mirror of
https://github.com/neondatabase/neon.git
synced 2026-01-04 12:02:55 +00:00
3532ae76ef
Adds endpoint to install extensions:
**POST** `/extensions`
```
{"extension":"pg_sessions_jwt","database":"neondb","version":"1.0.0"}
```
Will be used by `local-proxy`.
Example, for the JWT authentication to work the database needs to have
the pg_session_jwt extension and also to enable JWT to work in RLS
policies.
---------
Co-authored-by: Conrad Ludgate <conradludgate@gmail.com>
600 lines
15 KiB
YAML
600 lines
15 KiB
YAML
openapi: "3.0.2"
|
|
info:
|
|
title: Compute node control API
|
|
version: "1.0"
|
|
|
|
servers:
|
|
- url: "http://localhost:3080"
|
|
|
|
paths:
|
|
/status:
|
|
get:
|
|
tags:
|
|
- Info
|
|
summary: Get compute node internal status.
|
|
description: ""
|
|
operationId: getComputeStatus
|
|
responses:
|
|
200:
|
|
description: ComputeState
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ComputeState"
|
|
|
|
/metrics.json:
|
|
get:
|
|
tags:
|
|
- Info
|
|
summary: Get compute node startup metrics in JSON format.
|
|
description: ""
|
|
operationId: getComputeMetricsJSON
|
|
responses:
|
|
200:
|
|
description: ComputeMetrics
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ComputeMetrics"
|
|
|
|
/insights:
|
|
get:
|
|
tags:
|
|
- Info
|
|
summary: Get current compute insights in JSON format.
|
|
description: |
|
|
Note, that this doesn't include any historical data.
|
|
operationId: getComputeInsights
|
|
responses:
|
|
200:
|
|
description: Compute insights
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ComputeInsights"
|
|
|
|
/installed_extensions:
|
|
get:
|
|
tags:
|
|
- Info
|
|
summary: Get installed extensions.
|
|
description: ""
|
|
operationId: getInstalledExtensions
|
|
responses:
|
|
200:
|
|
description: List of installed extensions
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/InstalledExtensions"
|
|
/info:
|
|
get:
|
|
tags:
|
|
- Info
|
|
summary: Get info about the compute pod / VM.
|
|
description: ""
|
|
operationId: getInfo
|
|
responses:
|
|
200:
|
|
description: Info
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Info"
|
|
|
|
/dbs_and_roles:
|
|
get:
|
|
tags:
|
|
- Info
|
|
summary: Get databases and roles in the catalog.
|
|
description: ""
|
|
operationId: getDbsAndRoles
|
|
responses:
|
|
200:
|
|
description: Compute schema objects
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/DbsAndRoles"
|
|
|
|
/database_schema:
|
|
get:
|
|
tags:
|
|
- Info
|
|
summary: Get schema dump
|
|
parameters:
|
|
- name: database
|
|
in: query
|
|
description: Database name to dump.
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: "postgres"
|
|
description: Get schema dump in SQL format.
|
|
operationId: getDatabaseSchema
|
|
responses:
|
|
200:
|
|
description: Schema dump
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Schema dump in SQL format.
|
|
404:
|
|
description: Non existing database.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GenericError"
|
|
|
|
/grants:
|
|
post:
|
|
tags:
|
|
- Grants
|
|
summary: Apply grants to the database.
|
|
description: ""
|
|
operationId: setRoleGrants
|
|
requestBody:
|
|
description: Grants request.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SetRoleGrantsRequest"
|
|
responses:
|
|
200:
|
|
description: Grants applied.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SetRoleGrantsResponse"
|
|
412:
|
|
description: |
|
|
Compute is not in the right state for processing the request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GenericError"
|
|
500:
|
|
description: Error occurred during grants application.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GenericError"
|
|
|
|
/check_writability:
|
|
post:
|
|
tags:
|
|
- Check
|
|
summary: Check that we can write new data on this compute.
|
|
description: ""
|
|
operationId: checkComputeWritability
|
|
responses:
|
|
200:
|
|
description: Check result
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Error text or 'true' if check passed.
|
|
example: "true"
|
|
|
|
/extensions:
|
|
post:
|
|
tags:
|
|
- Extensions
|
|
summary: Install extension if possible.
|
|
description: ""
|
|
operationId: installExtension
|
|
requestBody:
|
|
description: Extension name and database to install it to.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ExtensionInstallRequest"
|
|
responses:
|
|
200:
|
|
description: Result from extension installation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ExtensionInstallResult"
|
|
412:
|
|
description: |
|
|
Compute is in the wrong state for processing the request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GenericError"
|
|
500:
|
|
description: Error during extension installation.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GenericError"
|
|
|
|
/configure:
|
|
post:
|
|
tags:
|
|
- Configure
|
|
summary: Perform compute node configuration.
|
|
description: |
|
|
This is a blocking API endpoint, i.e. it blocks waiting until
|
|
compute is finished configuration and is in `Running` state.
|
|
Optional non-blocking mode could be added later.
|
|
operationId: configureCompute
|
|
requestBody:
|
|
description: Configuration request.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- spec
|
|
properties:
|
|
spec:
|
|
# XXX: I don't want to explain current spec in the OpenAPI format,
|
|
# as it could be changed really soon. Consider doing it later.
|
|
type: object
|
|
responses:
|
|
200:
|
|
description: Compute configuration finished.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ComputeState"
|
|
400:
|
|
description: Provided spec is invalid.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GenericError"
|
|
412:
|
|
description: |
|
|
It's not possible to do live-configuration of the compute.
|
|
It's either in the wrong state, or compute doesn't use pull
|
|
mode of configuration.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GenericError"
|
|
500:
|
|
description: |
|
|
Compute configuration request was processed, but error
|
|
occurred. Compute will likely shutdown soon.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GenericError"
|
|
/extension_server:
|
|
post:
|
|
tags:
|
|
- Extension
|
|
summary: Download extension from S3 to local folder.
|
|
description: ""
|
|
operationId: downloadExtension
|
|
responses:
|
|
200:
|
|
description: Extension downloaded
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Error text or 'OK' if download succeeded.
|
|
example: "OK"
|
|
400:
|
|
description: Request is invalid.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GenericError"
|
|
500:
|
|
description: Extension download request failed.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GenericError"
|
|
|
|
/terminate:
|
|
post:
|
|
tags:
|
|
- Terminate
|
|
summary: Terminate Postgres and wait for it to exit
|
|
description: ""
|
|
operationId: terminate
|
|
responses:
|
|
200:
|
|
description: Result
|
|
412:
|
|
description: "wrong state"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GenericError"
|
|
500:
|
|
description: "Unexpected error"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GenericError"
|
|
|
|
components:
|
|
securitySchemes:
|
|
JWT:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
|
|
schemas:
|
|
ComputeMetrics:
|
|
type: object
|
|
description: Compute startup metrics.
|
|
required:
|
|
- wait_for_spec_ms
|
|
- sync_safekeepers_ms
|
|
- basebackup_ms
|
|
- config_ms
|
|
- total_startup_ms
|
|
properties:
|
|
wait_for_spec_ms:
|
|
type: integer
|
|
sync_safekeepers_ms:
|
|
type: integer
|
|
basebackup_ms:
|
|
type: integer
|
|
config_ms:
|
|
type: integer
|
|
total_startup_ms:
|
|
type: integer
|
|
|
|
Info:
|
|
type: object
|
|
description: Information about VM/Pod.
|
|
required:
|
|
- num_cpus
|
|
properties:
|
|
num_cpus:
|
|
type: integer
|
|
|
|
DbsAndRoles:
|
|
type: object
|
|
description: Databases and Roles
|
|
required:
|
|
- roles
|
|
- databases
|
|
properties:
|
|
roles:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Role"
|
|
databases:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Database"
|
|
|
|
Database:
|
|
type: object
|
|
description: Database
|
|
required:
|
|
- name
|
|
- owner
|
|
- restrict_conn
|
|
- invalid
|
|
properties:
|
|
name:
|
|
type: string
|
|
owner:
|
|
type: string
|
|
options:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/GenericOption"
|
|
restrict_conn:
|
|
type: boolean
|
|
invalid:
|
|
type: boolean
|
|
|
|
Role:
|
|
type: object
|
|
description: Role
|
|
required:
|
|
- name
|
|
properties:
|
|
name:
|
|
type: string
|
|
encrypted_password:
|
|
type: string
|
|
options:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/GenericOption"
|
|
|
|
GenericOption:
|
|
type: object
|
|
description: Schema Generic option
|
|
required:
|
|
- name
|
|
- vartype
|
|
properties:
|
|
name:
|
|
type: string
|
|
value:
|
|
type: string
|
|
vartype:
|
|
type: string
|
|
|
|
ComputeState:
|
|
type: object
|
|
required:
|
|
- start_time
|
|
- status
|
|
properties:
|
|
start_time:
|
|
type: string
|
|
description: |
|
|
Time when compute was started. If initially compute was started in the `empty`
|
|
state and then provided with valid spec, `start_time` will be reset to the
|
|
moment, when spec was received.
|
|
example: "2022-10-12T07:20:50.52Z"
|
|
status:
|
|
$ref: "#/components/schemas/ComputeStatus"
|
|
last_active:
|
|
type: string
|
|
description: |
|
|
The last detected compute activity timestamp in UTC and RFC3339 format.
|
|
It could be empty if compute was never used by user since start.
|
|
example: "2022-10-12T07:20:50.52Z"
|
|
error:
|
|
type: string
|
|
description: Text of the error during compute startup or reconfiguration, if any.
|
|
example: ""
|
|
tenant:
|
|
type: string
|
|
description: Identifier of the current tenant served by compute node, if any.
|
|
example: c9269c359e9a199fad1ea0981246a78f
|
|
timeline:
|
|
type: string
|
|
description: Identifier of the current timeline served by compute node, if any.
|
|
example: ece7de74d4b8cbe5433a68ce4d1b97b4
|
|
|
|
ComputeInsights:
|
|
type: object
|
|
properties:
|
|
pg_stat_statements:
|
|
description: Contains raw output from pg_stat_statements in JSON format.
|
|
type: array
|
|
items:
|
|
type: object
|
|
|
|
ComputeStatus:
|
|
type: string
|
|
enum:
|
|
- empty
|
|
- init
|
|
- failed
|
|
- running
|
|
- configuration_pending
|
|
- configuration
|
|
example: running
|
|
|
|
ExtensionInstallRequest:
|
|
type: object
|
|
required:
|
|
- extension
|
|
- database
|
|
- version
|
|
properties:
|
|
extension:
|
|
type: string
|
|
description: Extension name.
|
|
example: "pg_session_jwt"
|
|
version:
|
|
type: string
|
|
description: Version of the extension.
|
|
example: "1.0.0"
|
|
database:
|
|
type: string
|
|
description: Database name.
|
|
example: "neondb"
|
|
|
|
ExtensionInstallResult:
|
|
type: object
|
|
properties:
|
|
extension:
|
|
description: Name of the extension.
|
|
type: string
|
|
example: "pg_session_jwt"
|
|
version:
|
|
description: Version of the extension.
|
|
type: string
|
|
example: "1.0.0"
|
|
|
|
InstalledExtensions:
|
|
type: object
|
|
properties:
|
|
extensions:
|
|
description: Contains list of installed extensions.
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
extname:
|
|
type: string
|
|
versions:
|
|
type: array
|
|
items:
|
|
type: string
|
|
n_databases:
|
|
type: integer
|
|
|
|
SetRoleGrantsRequest:
|
|
type: object
|
|
required:
|
|
- database
|
|
- schema
|
|
- privileges
|
|
- role
|
|
properties:
|
|
database:
|
|
type: string
|
|
description: Database name.
|
|
example: "neondb"
|
|
schema:
|
|
type: string
|
|
description: Schema name.
|
|
example: "public"
|
|
privileges:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: List of privileges to set.
|
|
example: ["SELECT", "INSERT"]
|
|
role:
|
|
type: string
|
|
description: Role name.
|
|
example: "neon"
|
|
|
|
SetRoleGrantsResponse:
|
|
type: object
|
|
required:
|
|
- database
|
|
- schema
|
|
- privileges
|
|
- role
|
|
properties:
|
|
database:
|
|
type: string
|
|
description: Database name.
|
|
example: "neondb"
|
|
schema:
|
|
type: string
|
|
description: Schema name.
|
|
example: "public"
|
|
privileges:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: List of privileges set.
|
|
example: ["SELECT", "INSERT"]
|
|
role:
|
|
type: string
|
|
description: Role name.
|
|
example: "neon"
|
|
|
|
#
|
|
# Errors
|
|
#
|
|
|
|
GenericError:
|
|
type: object
|
|
required:
|
|
- error
|
|
properties:
|
|
error:
|
|
type: string
|
|
|
|
security:
|
|
- JWT: []
|