Sync a database connection's objects

Uses: Python · TypeScript · CLI · REST API

Applications that expose selectable objects - databases especially - need one extra step after connecting: telling Engini which tables or entities to work with. You can check whether an app needs this via supportsObjectSelection on the application, or useSelectDBObjects on the connection. The sequence is refresh → poll → browse → select → poll again.

cURL samples assume BASE=https://api.engini.io/v1 and AUTH="x-api-key: $ENGINI_API_KEY" - the setup from the REST walkthrough. Steps 1-2 are shown raw first because the polling contract is where the surprises live; the SDK and CLI wrap both steps in one call (the CodeGroup in step 2).

1. Trigger a refresh

Refresh is asynchronous. An empty 200 means accepted, not finished.

curl -s -X POST "$BASE/connections/42/refresh-objects" -H "$AUTH" -o /dev/null -w "%{http_code}\n"

Async triggers can return a gateway 502/503/504 while the job is still accepted server-side. Don’t treat that as failure - the status poll is the source of truth. Both SDKs already tolerate this.

2. Poll until it settles

until [ "$(curl -s "$BASE/connections/42/refresh-status" -H "$AUTH" | jq -r '.statusDescription')" != "InProgress" ]; do
  sleep 2
done
curl -s "$BASE/connections/42/refresh-status" -H "$AUTH" | jq '{status, statusDescription, error, lastRefreshDate}'

Branch on statusDescription and error, not the numeric status enum. The enum is Ok = 0, Error = 1, InProgress = 2, but a finished refresh has been observed reporting status: 0 with descriptive text carrying the real meaning - so the text plus error is the reliable signal. The SDKs’ wait_for_refresh already encodes this.

client.connections.refresh(42)
status = client.connections.wait_for_refresh(42)   # 300s timeout, 2s interval

await client.connections.refresh(42);
const status = await client.connections.waitForRefresh(42);

# waits by default; --no-wait returns immediately with status "pending"
engini connections refresh 42 --timeout 600

3. Browse what’s available

objs = client.connections.objects(42)                  # full catalog
orders = client.connections.objects(42, name="order")  # server-side name filter

const objs = await client.connections.objects(42);
const orders = await client.connections.objects(42, { name: "order" });

engini connections objects 42
engini connections objects 42 --name order

curl -s "$BASE/connections/42/objects?top=100" -H "$AUTH" \
  | jq -r '.items[] | "\(.objectId)\t\(.name)\t\(.type)\t\(.isSelected)"'

curl -s "$BASE/connections/42/objects?name=order" -H "$AUTH" | jq '.totalCount'

Large schemas paginate like any other list (offset/top, up to 1000 per page) - see paging large catalogs. The SDKs and CLI page for you.

4. Select

Selecting replaces the entire selection - it isn’t additive. To add one object, send the existing selected ids plus the new one, or you’ll silently deselect everything else.

Selecting triggers another refresh, so wait for refresh-status again before assuming the new objects are queryable:

objs = client.connections.objects(42)
keep = [o.object_id for o in objs if o.name.startswith("dim_")]
client.connections.select_objects(42, keep)
client.connections.wait_for_refresh(42)

const objs = await client.connections.objects(42);
const keep = objs.filter((o) => o.name.startsWith("dim_")).map((o) => o.objectId);
await client.connections.selectObjects(42, keep);
await client.connections.waitForRefresh(42);

engini connections select-objects 42 --object 12 --object 15 --object 19

curl -s -X POST "$BASE/connections/42/select-objects" -H "$AUTH" \
  -H "Content-Type: application/json" -d '{"objectIds":[12,15,19]}'
# then poll refresh-status as in step 2

Adding to an existing selection

current = [o.object_id for o in client.connections.objects(42) if o.is_selected]
client.connections.select_objects(42, current + [77])
client.connections.wait_for_refresh(42)

const current = (await client.connections.objects(42))
  .filter((o) => o.isSelected)
  .map((o) => o.objectId);
await client.connections.selectObjects(42, [...current, 77]);
await client.connections.waitForRefresh(42);

A useful side effect

A completed refresh is the strongest health signal a connection can give you - stronger than check, which can return an inconclusive empty 200. A refresh that finishes proves the credential actually authenticated against the provider. If you only run one verification after creating a connection, make it this one.

The whole thing in one command

engini connect postgres                          # walks credentials -> check -> refresh -> object selection
engini connections objects 42 --name orders      # inspect later
engini connections select-objects 42 --object 12 --object 15

Start here

Connect apps

Run tools

Build agents

Automate

Sync a database connection's objects

1. Trigger a refresh

2. Poll until it settles

3. Browse what’s available

4. Select

Adding to an existing selection

A useful side effect

The whole thing in one command

​1. Trigger a refresh

​2. Poll until it settles

​3. Browse what’s available

​4. Select

​Adding to an existing selection

​A useful side effect

​The whole thing in one command

1. Trigger a refresh

2. Poll until it settles

3. Browse what’s available

4. Select

Adding to an existing selection

A useful side effect

The whole thing in one command