Keep the data of a partner's compositions in a Neon database of its own

Points the partner at a Neon database of its own. From then on, what visitors leave in the compositions of the partner’s managed users, and of the compositions made in the partner’s own account (the votes, ratings, answers and form submissions of the widgets that collect them), is stored in that database and nowhere else. Widgetic’s own database is not used for them any more, and nothing of it is copied there.

What to give. The connection string of a Neon database and a role made for this, as Neon shows it under Connect (postgresql://<role>:<password>@ep-<name>.<region>.aws.neon.tech/<database>). Only Neon databases are accepted; a string for any other host is refused with 400. What the database needs:

• an empty database of its own, so that nothing else of yours shares it. Widgetic makes one schema in it for each composition (named comp_ followed by the composition’s id). In that schema go the tables the widget declares for what its visitors leave, and two small tables of Widgetic’s own, whose names start with _widgetic_: the context a host page sent with an entry, and how far Widgetic has read the entries to tell you about new ones. It touches nothing else;
• a role that may create schemas and tables in it (the CREATE privilege on the database). The role Neon makes with a project has it. A role made in the Neon console can also read and write every other database of the same project, so if you keep other data in Neon give Widgetic a project of its own, or make the role with SQL (CREATE ROLE ... LOGIN PASSWORD ...) and grant it only the CREATE privilege on this database;
• connections from anywhere: Widgetic’s addresses are not fixed, so a Neon project that only accepts connections from an allow list of addresses cannot be used. A suspended compute is fine: it wakes on the first request.

It is checked before it is saved. Widgetic makes a schema in your database, creates a table in it, writes a row, reads it back, and removes the schema again, all in one step, so that nothing is left if anything fails. If it cannot be done nothing is saved and the answer is 422 PARTNER_DATABASE_UNVERIFIED: details.reason says why (INVALID_CREDENTIALS, DATABASE_NOT_FOUND, ACCESS_DENIED, ACCESS_BLOCKED, ENDPOINT_NOT_FOUND, ENDPOINT_UNREACHABLE, TIMEOUT, READ_ONLY, RATE_LIMITED, DATABASE_UNAVAILABLE, PROBE_MISMATCH or DATABASE_ERROR) and message says what to do.

Existing data does not move. The data of a composition lives in one database. If any composition of the partner already keeps data somewhere else (in Widgetic’s database, or in the database you had set), and the new database does not hold it, the change is refused with 409 PARTNER_DATABASE_HOLDS_DATA and nothing is changed: those compositions would read as empty from then on. details.compositionsWithData says how many. Set your database before your customers collect data, or delete the compositions you no longer need. Saving the same database again (a new password) moves nothing and is never refused.

It is never a fallback. Once a database is set, a request that needs it while it cannot be used (the password was changed, the project was deleted) is refused with 503 PARTNER_DATABASE_UNAVAILABLE. What the visitor sent is not stored with Widgetic instead. Fix the connection and set the database again, or check it with verifyPartnerDataDatabase.

When it takes effect. A change reaches every part of Widgetic within about a minute.

What Widgetic keeps. The connection string is stored encrypted and is never returned or logged; a response shows the host, the database and the role, never the password. Widgetic’s servers open it to read and write the data of your compositions while they handle a request for it. To cut that off, change the role’s password in Neon: the compositions stop saving until you set the new string.

This needs an API key with full access. The caller must be the person who administers the partner, or a Widgetic administrator. A retry is harmless: saving the same database twice only refreshes when it was checked and saved.

PUT /partners/{partnerId}/data-database

TypeScript SDK

TypeScript

import { Configuration, PartnersApi } from '@widgetic/api-sdk-ts';

const partnersApi = new PartnersApi(new Configuration({ apiKey: 'YOUR_API_KEY' }));

const { data: database } = await partnersApi.setPartnerDataDatabase({
  partnerId,
  setPartnerDataDatabaseRequest: {
    connectionString: 'postgresql://widgetic_data:[e-mail]/neondb',
  },
});
console.log(database.host, database.databaseName, database.verifiedAt);

200

{
  "success": true,
  "data": {
    "partnerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "host": "ep-cool-name-123456.eu-central-1.aws.neon.tech",
    "databaseName": "neondb",
    "roleName": "widgetic_data",
    "verifiedAt": "2026-01-15T09:30:00.000Z",
    "lastVerificationError": "Example lastVerificationError",
    "lastVerificationFailedAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z"
  },
  "meta": {
    "page": 1,
    "size": 20,
    "total": 135,
    "limit": 20,
    "offset": 0,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "nextCursor": "<string>",
    "warnings": [
      "<string>"
    ]
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

partnerId · string<uuid> · required

The partner whose database to set

Body

application/json

connectionString · string<password> · required · write-only

The connection string of a Neon database and role you made for this, as Neon shows it under Connect: postgresql://<role>:<password>@ep-<name>.<region>.aws.neon.tech/<database>. Either the direct or the pooled host works. Everything after the database name (?sslmode=...) is ignored. It is stored encrypted and is never returned or logged.

Example:

"postgresql://widgetic_data:[e-mail]/neondb"

Response

200

application/json

The database passed the check and was saved

success · boolean · required

Always true on a success.

Example:

true

data · object · required

The Neon database your compositions keep what visitors leave in them (votes, ratings, answers, form submissions). The connection string and its password are never part of this: they are given once, when the database is set.

Show child attributes

Example:

{
  "partnerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "host": "ep-cool-name-123456.eu-central-1.aws.neon.tech",
  "databaseName": "neondb",
  "roleName": "widgetic_data",
  "verifiedAt": "2026-01-15T09:30:00.000Z",
  "lastVerificationError": "Example lastVerificationError",
  "lastVerificationFailedAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z"
}

meta · object

Extra information about the answer: where a page sits in a list, the cursor of the next page, or warnings about a call that succeeded with a caveat.

Show child attributes