Skip to content
Embabel Worlds

Connect a database to this world, so it can be learned

POST
/api/v1/learn/databases
curl --request POST \
  --url http://localhost:11044/api/v1/learn/databases \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "engine": "example", "fields": { "additionalProperty": "example" }, "jdbcUrl": "example", "password": "example", "username": "example" }'

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”

The database to connect: preferably engine (an id from GET /api/v1/learn/databases/engines) with fields keyed by that engine’s field names, otherwise a ready jdbcUrl (400 when neither is given). Top-level username and password apply to either shape and, when not blank, override the same keys in fields. The password goes to the user’s wallet, never into world YAML. The database is introspected before the datasource is saved, and the world is rebuilt

Media typeapplication/json

How to reach a database, sent to POST /learn/databases: an engine and its form’s fields, as a picker sends them, or a JDBC URL a caller already has

object
engine

An engine id from GET /learn/databases/engines, e.g. postgresql, oracle, duckdb. When given, the URL is composed from fields and jdbcUrl is ignored; absent or blank means jdbcUrl is used. An id this appliance has no driver for is refused 400

string
fields
required

Values for the engine’s form, keyed by each field’s name, username and password among them. A blank value takes the field’s default; a required field left blank with no default is refused 400. Read only with engine

object
key
additional properties
string
jdbcUrl

A complete JDBC URL, for a caller that has one. Used only when engine is absent or blank, and then required

string
password
required

Stored in the user’s wallet, never echoed back and never written to world YAML. With engine, a non-blank value takes precedence over fields.password; empty means no password

string
username
required

The login the world reads the database as. With engine, a non-blank value takes precedence over fields.username

string

Example generated

{
  "engine": "example",
  "fields": {
    "additionalProperty": "example"
  },
  "jdbcUrl": "example",
  "password": "example",
  "username": "example"
}

Responses

Section titled “Responses”

400

Section titled “400”

Unknown engine, unreachable, no driver, or an empty schema

Media typeapplication/json

A refusal carrying only its explanation, with no code to branch on

object
error
required

What went wrong, written to be shown. Carries the underlying driver’s or parser’s own message where there is one

string

Example generated

{
  "error": "example"
}