Data sources

A data source is a Postgres database a workspace works on: your own, or the sample. Every table of it is an object, its rows records and its columns fields. Connecting, changing and disconnecting are for owners and admins, in Settings → Data sources.

What happens to your databaseCopy Anchor Link

• Rows are read and written in place, never copied. Each request is one short, parameterized transaction on your server.
• Read and write by default. Edits, new records and deletes in the app change rows, as far as your database role allows. Pick another access when you connect:

• A table needs a key to be editable: its primary key, or a unique index over columns that are never null. Without one it's read-only; an owner or admin can pick key columns in Settings → Objects, checked against the rows first.
• Only what Postgres would write is writable: the role's privileges, table by table, and whether a view is updatable. Materialized views and foreign tables are read-only.
• An object says which writes it takes, and why not: writeAccess in the API (writeRefusal in objects_get), each refusal a message and the first reason that holds: table_missing, relation_read_only, source_read_only, not_permitted or no_key.
• Timeouts: 15 s per statement (30 s for schema changes and the SQL console), 5 s waiting for a lock, 5 s idle in a transaction.
• Poolers work, in transaction mode too: no prepared statements, every setting local to its transaction. Dataembed opens at most 3 connections per source per server instance.
• If the connection breaks while a change commits, the write fails with "Lost the connection to the database while saving: the change may have been saved. Check before trying again."

ConnectCopy Anchor Link

1. Settings → Data sources → Connect PostgreSQL (or Connect on the empty workspace's first page).
2. Name, Host, Port, Database, User, Password, and the Schemas to read (comma-separated, default public, at most 20).
3. Encryption: Verify (recommended) checks the server's certificate and host name, against CA certificate (optional) when you paste one; Off is for development only and refused in production.
4. Pick the access, then Test connection: it warns about a superuser or a role that bypasses row-level security, and about Rows and schema for a role that can't create in the schemas.
5. Connect. Every table, view, materialized view, foreign table and partitioned table the role can see becomes an object: columns become fields, foreign keys references, enums and CHECK (column IN (…)) lists selects.

Changing the host, port, database, user or encryption needs the password again, so a saved password never goes to a server you didn't type it for.

A role for DataembedCopy Anchor Link

Give Dataembed a role of its own with only what it needs:

CREATE ROLE dataembed LOGIN PASSWORD 'a-long-random-password';
GRANT CONNECT ON DATABASE app TO dataembed;
GRANT USAGE ON SCHEMA public TO dataembed;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO dataembed;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO dataembed;
-- Read and write:
GRANT INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO dataembed;
-- Rows and schema:
GRANT CREATE ON SCHEMA public TO dataembed;

Dataembed reads the role's privileges, so an object offers only the edits the role can make. Row-level security applies as to any client.

When your schema changesCopy Anchor Link

Dataembed re-reads a source's tables in the background: when it's listed more than 5 minutes after the last read, and at once when a query hits a table or column that's gone. Sync on the source's page does it now.

• New tables become objects, new columns fields.
• A key a keyless table gains is picked up, which makes it editable. A key already set never changes.
• A table or column that's gone is flagged Missing in source, never deleted, so its views and history stay if it comes back.
• Hide a table you don't need: owners and admins turn off Show in the sidebar, home and search in Settings → Objects. It only declutters: a hidden table stays readable and writable, by people and agents.

With Rows and schema, owners and admins add tables and columns from the app (how).

HealthCopy Anchor Link

A source shows its state, each failure with its fix: Connected, Syncing, Sync failed (Sync), Can't connect (Test again or Edit) or Password unreadable, when the server's encryption key changed (Edit and enter it again; disconnect the sample and use it again). Agents read it from data_sources_list as health.state: ok, syncing, sync_failed, connection_failed (with a kind, such as auth or tls) or credentials_unreadable.

The sample databaseCopy Anchor Link

Use the sample database gives the workspace companies, people and deals, with a Pipeline board, in a schema and role of its own on the deployment's sample server (not on dataembed.com yet), with Rows and schema access. Change anything. It stays when you connect your own database; disconnecting it drops it. A server without a sample database says it has none.

DisconnectCopy Anchor Link

Disconnect removes the source's objects, views and activity from Dataembed. Your database isn't touched (the sample's is dropped). It can't be undone, so when an agent disconnects one, it waits for an approval.

What Dataembed storesCopy Anchor Link

Only configuration and activity, never your rows:

• the connection (host, port, database, user, schemas, encryption, CA, access) and the password, encrypted with AES-256-GCM, never sent back;
• the objects and fields it read from your tables, and their settings (labels, icons, options, hidden);
• views, page layouts and plugins;
• the activity log: each change made through Dataembed, with the values before and after, cleared after 90 days.

The copilot is the exception: rows it reads are part of the thread, kept until the thread is deleted.

LimitsCopy Anchor Link

• Public hosts only. Hosts that resolve to private or reserved addresses are refused; self-hosted development can lift this with DATA_SOURCE_ALLOW_PRIVATE_HOSTS=true. Dataembed's own database is refused.
• PostgreSQL 12+. At most 20 schemas, 2,000 tables and 500 columns per table.
• Connection attempts (testing, connecting, changing a connection): 30 per person per minute.