Using the API Interface

This tutorial illustrates how to use the API interface. pglift provides a API that can be started (in development mode) as follows:

$ uvicorn pglift_api:app --port 8000
INFO:     Started server process [1843683]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

There are several endpoints corresponding to various objects handled by pglift. Currently, only instances and database objects are available. When the API is run in development mode, as shown above, users can access the basic documentation and schemas for the handle object at https://127.0.0.1:8000/docs.

Site configuration

Before actually using pglift to manage PostgreSQL instances, it is often needed to configure the site. The main documentation includes a detailed chapter on the topic.

Asynchronous tasks

To prevent long-running blocking requests, all operations involving the creation, updating or deletion off pglift objects are processed asynchronously.

When a user triggers one of these actions, the API does not wait for the operation to complete. Instead, pglift API immediately returns a unique Task UUID and processes the task in background.

The /tasks endpoint can be used to list all tasks, and the /tasks/<uuid> endpoint can provide more information about a specific task.

Creating an instance

$ curl -X POST \
  'http://127.0.0.1:8000/instances/' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"name": "myinstance", "version": "18"}'

08b455a1-2994-49de-9429-0f912ded4795

$ curl http://127.0.0.1:8000/tasks/ | jq
[
  {
    "id": "08b455a1-2994-49de-9429-0f912ded4795",
    "state": "completed",
    "description": "create instance 18-myinstance"
  }
]

$ curl http://127.0.0.1:8000/tasks/08b455a1-2994-49de-9429-0f912ded4795 | jq .
{
  "description": "create instance 18-myinstance",
  "created_at": "2026-07-07T11:12:35.771388",
  "completed_at": "2026-07-07T11:12:38.435660",
  "state": "completed",
  "error": false,
  "exception": null,
  "logs": []
}

There are many more fields to the instances endpoints commands, some built in and some depending on the activation of satellite components.

Listing instances

$ curl http://127.0.0.1:8000/instances/ | jq .
[
  {
    "name": "myinstance",
    "version": "18",
    "port": 5432,
    "datadir": "/srv/pglift/srv/pgsql/18/myinstance/data",
    "status": "running"
  }
]

Altering an instance

$ curl -X PUT http://127.0.0.1:8000/instances/18/myinstance \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "myinstance",
    "version": "18",
    "settings": {"max_connections": 80},
    "restart_on_changes": true
  }'

854d111f-48ac-47e4-af28-e97b953cb274

$ curl http://127.0.0.1:8000/tasks/854d111f-48ac-47e4-af28-e97b953cb274| jq .
{
  "description": "update instance 18-myinstance",
  "created_at": "2026-07-07T11:12:35.771388",
  "completed_at": "2026-07-07T11:24:33.971825",
  "state": "completed",
  "error": false,
  "exception": null,
  "logs": []
}

Getting instance information

$ curl http://127.0.0.1:8000/instances/18/myinstance | jq .
{
  "name": "myinstance",
  "version": "18",
  "standby": null,
  "port": 5432,
  "settings": {
    "max_connections": 80,
    "unix_socket_directories": "/run/user/1000/pglift/postgresql",
    "shared_buffers": "8 GB",
    "effective_cache_size": "22 GB",
    "log_destination": "stderr",
    "logging_collector": true,
    "log_directory": "/srv/pglift/log/postgresql",
    "log_filename": "18-myinstance-%Y-%m-%d_%H%M%S.log",
    "cluster_name": "myinstance",
    "lc_messages": "C",
    "lc_monetary": "C",
    "lc_numeric": "C",
    "lc_time": "C"
  },
  "data_checksums": true,
  "locale": "C",
  "encoding": "UTF8",
  "pending_restart": false,
  "state": "started",
  "replication_slots": [],
  "data_directory": "/srv/pglift/srv/pgsql/18/myinstance/data",
  "wal_directory": "/srv/pglift/srv/pgsql/18/myinstance/wal"
}

Adding and manipulating instance objects

users can use the POST method on the databases endpoint with the relevant JSON to trigger a database creation task.

$ curl -X POST http://127.0.0.1:8000/instances/18/myinstance/databases \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"name": "mydb"}'

653d3d74-7f24-4283-9c33-297366af5a00

$ curl http://127.0.0.1:8000/tasks/653d3d74-7f24-4283-9c33-297366af5a00 | jq .
{
  "description": "create database mydb",
  "created_at": "2026-07-07T11:12:35.771388",
  "completed_at": "2026-07-07T15:15:47.148565",
  "state": "completed",
  "error": false,
  "exception": null,
  "logs": []
}

$ curl http://127.0.0.1:8000/instances/18/myinstance/databases | jq .
[
  {
    "name": "mydb",
    "owner": "postgres",
    "encoding": "UTF8",
    "collation": "C",
    "ctype": "C",
    "acls": [],
    "size": 7774735,
    "description": null,
    "tablespace": {
      "name": "pg_default",
      "location": "",
      "size": 31289756
    }
  },
  {
    "name": "postgres",
    "owner": "postgres",
    "encoding": "UTF8",
    "collation": "C",
    "ctype": "C",
    "acls": [],
    "size": 7861951,
    "description": "default administrative connection database",
    "tablespace": {
      "name": "pg_default",
      "location": "",
      "size": 31289756
    }
  },
  {
    "name": "template1",
    "owner": "postgres",
    "encoding": "UTF8",
    "collation": "C",
    "ctype": "C",
    "acls": [
      "=c/postgres",
      "postgres=CTc/postgres"
    ],
    "size": 7935679,
    "description": "default template for new databases",
    "tablespace": {
      "name": "pg_default",
      "location": "",
      "size": 31289756
    }
  }
]

Users can also access information about a database by requesting the dedicated endpoint:

curl http://127.0.0.1:8000/instances/18/myinstance/databases/mydb | jq .
{
  "name": "mydb",
  "owner": "postgres",
  "settings": null,
  "schemas": [
    {
      "name": "public",
      "owner": "pg_database_owner"
    }
  ],
  "extensions": [],
  "locale": "C",
  "publications": [],
  "subscriptions": [],
  "tablespace": "pg_default"
}

Alternatively, users can delete the database with the DELETE method:

$ curl -X DELETE http://127.0.0.1:8000/instances/18/myinstance/databases/mydb
003fbe0b-0359-4f2d-b705-41ee0a8beb47

$ curl http://127.0.0.1:8000/tasks/003fbe0b-0359-4f2d-b705-41ee0a8beb47 | jq .
{
  "description": "delete database mydb",
  "created_at": "2026-07-07T11:12:35.771388",
  "completed_at": "2026-07-07T15:20:15.089717",
  "state": "completed",
  "error": false,
  "exception": null,
  "logs": []
}