Docs
Connections

Connections

Connect Google Sheets, Drive files, PostgreSQL and OpenAPI sources now; more kinds on request. How Xentropy keeps every read safe.

A connection is an authorized, read-only link to an external data source. Reads from a connection produce datasets, which charts, tables and dashboards bind to.

Source kinds

KindCategoryHow it authorizesReadsGuide
PostgreSQLDatabaseUsername and password over verified TLSSelected tables and viewsPostgreSQL
MySQLDatabaseUsername and password over verified TLSSelected tables and viewsMySQL
SQL ServerDatabaseSQL login, or a Microsoft Entra ID service principal, over verified TLSSelected tables and viewsSQL Server
SnowflakeDatabase & warehouseKey pair (generated in the browser)Selected tables and views, using warehouse creditsSnowflake
Google BigQueryDatabase & warehouseService account JSON keyTables, and SELECT queries under a cost capGoogle BigQuery
ShopifyBusiness appDev Dashboard app client credentials, or an Admin API tokenOrders, line items, customers, products, variants, inventoryShopify
HubSpotBusiness appService key (or another read-scoped token)CRM objects, custom objects, owners, pipeline stagesHubSpot
NotionBusiness appInternal Notion connection secret, read content onlyRows of shared databases (data sources)Notion
Git (GitHub, GitLab, Gitea, Bitbucket, Azure DevOps)Git, PreviewRead-only access token for the forgeRepositories, commits, pull requests, issues, releases, tags, branches, contributors, pipeline runsGit overview
S3-compatible storageStorageAccess key and secretObjects or globs: Parquet, Avro, ORC, CSV, TSV, JSON, NDJSON, XMLS3-compatible storage
File uploadFileNone (your own files)CSV, TSV, JSON, NDJSON, XML, optionally gzipFile uploads
OpenAPIAPIHeaders required by the API's security schemeSelected GET operations, JSON responsesOpenAPI
Google AnalyticsAnalyticsGoogle consent (read-only)GA4 reports for selected propertiesGoogle Analytics
Google SheetsSpreadsheetGoogle consentSelected spreadsheetsGoogle Sheets
Google DriveFileGoogle consentSelected CSV and JSON filesGoogle Drive
Raw JSON / CSVInlineNoneData you paste or send directly—

PostgreSQL, MySQL, SQL Server and Snowflake share one Database entry in New connection. Choose Database, then choose the engine. Pasting a connection string selects the engine for you: postgresql://, mysql:// or mariadb://, an ADO.NET or JDBC SQL Server string, or a snowflakecomputing.com URL. Switching the engine keeps the connection name and clears every other field, so a secret typed for one engine is never sent to another. Pasting a string for the same engine also clears any password or secret the string does not include, so enter it again for the new server. Only the engines enabled for your account are listed.

Relations you select after Test and list relations belong to that test. If you then change the connection details, test again before saving: the form keeps your selection and restores every relation the new details can still read.

REST JSON is a legacy kind. Existing REST JSON connections keep working, but you cannot create new ones. Use an OpenAPI connection instead.

Not every kind is generally available yet. On xentropy.ai, MySQL, SQL Server, Snowflake, S3-compatible storage, file uploads, Shopify, HubSpot, Notion, BigQuery and the Git forges are enabled on request: contact support@xentropy.ai. Google Analytics is not yet available on xentropy.ai (coming soon). When a kind is not enabled for your account, its reads fail with PROVIDER_DISABLED, and retrying does not help. The New connection catalogue, and the providers list that agents read, show only the kinds that are available.

Who can create and read connections

  • Each connection belongs to one user. Only that owner can see it.
  • In the console, testing or saving credentials may ask you to sign in again.
  • An agent needs an API key with connections:manage to create a connection, and the key must not be restricted to particular connections. Google connections always need the owner's consent in a browser.
  • An agent can read a source with connections:read or with that kind's own read scope: postgres:read, mysql:read, sqlserver:read, snowflake:read, s3:read, http:read (OpenAPI and REST JSON), shopify:read, hubspot:read, notion:read, git:read (all Git forges), bigquery:read, sheets:read, drive:read or analytics:read.
  • On the Free plan you can have up to 3 connections. Every kind counts, except uploads: uploaded files count toward storage instead.

Security model

Every network connector (PostgreSQL, MySQL, SQL Server, Snowflake, S3-compatible storage, OpenAPI, including OpenAPI specification fetches, and the business app and BigQuery connectors) follows one outbound policy.

Verified TLS, always

  • TLS is required. Xentropy checks the certificate chain and requires the certificate to name the host you entered. You cannot turn either check off.
  • If your server uses a private certificate authority, paste its CA certificate into the connection form. It is trusted in addition to the public roots, and only for that connection.
  • MySQL and SQL Server connections require TLS 1.2 or later. SQL Server uses TDS 8.0 strict encryption when the server supports it.
  • Snowflake connections use Snowflake's public certificate only.

Egress pinning and the private-network deny

  • Xentropy resolves the hostname once, then checks every address in the answer.
  • The connection opens to the exact address that was checked. There is no second lookup, so a DNS answer that changes in the meantime (DNS rebinding) cannot redirect it.
  • The TLS server name is always the hostname you entered.
  • Xentropy refuses private, loopback, link-local, carrier-grade NAT, benchmark, documentation, multicast and reserved ranges. For IPv4 these are 0.0.0.0/8, 10.0.0.0/8, 100.64.0.0/10, 127.0.0.0/8, 169.254.0.0/16, 172.16.0.0/12, 192.168.0.0/16, 192.0.0.0/24, 198.18.0.0/15, 224.0.0.0/4 and 240.0.0.0/4. For IPv6 they are ::, ::1, fc00::/7, fe80::/10, ff00::/8, 2001:db8::/32 and IPv4-mapped ::ffff:0:0/96.
  • If a DNS answer mixes public and private addresses, the whole answer is refused. The error is a network_policy stage error.
  • Connect to your source's public hostname. Private and internal addresses are never reachable.
  • HTTP sources must use HTTPS with no credentials in the URL. Redirects are refused, never followed, so enter the final URL. Each response has a byte limit and a time limit.
  • When the policy refuses a connection, the log records only the stage, host and provider. It never records a URL path, query, header or body.

Egress IP addresses

Shopify, HubSpot, Notion and BigQuery connect only to the vendor's own API hosts, and each connector can send only the read requests it needs to those hosts. They need no IP allowlist.

Database, storage and API forms list the outbound IP addresses that Xentropy connects from, each with a copy button. Allow them in your firewall, pg_hba.conf, MySQL user host rules, Azure SQL firewall rules, Snowflake network policies or bucket IP conditions. Agents get the same list as egressIps from GET /api/v1/data/providers. An empty list means no fixed addresses are published yet; contact support@xentropy.ai before you restrict access by IP.

Read-only enforcement

Xentropy enforces read-only access in two places: in Xentropy's own code, and with the least-privilege credentials you create at the source.

KindEnforced by Xentropy
PostgreSQLEvery query runs inside BEGIN READ ONLY. Only generated SELECT statements are sent, and identifiers are validated and quoted.
MySQLThe session and an explicit transaction are READ ONLY. Multiple statements, LOAD DATA LOCAL and the clear-text password plugin are disabled.
SQL ServerEvery session runs in a transaction that is always rolled back. Only generated SELECT statements are sent, with bound parameters.
SnowflakeOnly generated SELECT, SHOW and DESCRIBE statements are sent, one per request (MULTI_STATEMENT_COUNT = 1). The setup SQL creates a SELECT-only role.
S3-compatibleThe client can only list objects and GET byte ranges. It has no write or delete calls.
OpenAPIOnly GET operations can be bound. Pagination cannot leave the bound operation's origin and path.
GoogleThe connection requests read-only scopes. Google Analytics uses analytics.readonly.
ShopifyOnly Xentropy's own GraphQL read queries are sent, never mutations.
HubSpot, NotionOnly listed read endpoints can be called, checked before any connection opens. HubSpot batch reads and Notion search and queries are the only POST requests.
GitOnly listed read endpoints on the forge's own host can be called. Azure DevOps work item queries (WIQL) are the only POST requests. Next-page links must stay on the same host and path.
BigQueryEvery query is dry-run first and must be a single SELECT. Reads use a read-only token, and every job carries the cost cap.

The database forms show SQL for a read-only role or user that you can copy and run at the source. The business app and BigQuery forms list the read scopes or roles to grant, with a copy button.

Personal data

Shopify customer contact fields, HubSpot contact properties (name, email, phone, address) and Notion email, phone and people email fields are marked Personal data in the field picker. They are off by default. If you select one, the dataset is marked as containing personal data (containsPii), and agents must confirm it explicitly. See each guide for the exact fields.

Credentials

  • Passwords, secret keys and credential headers are encrypted at rest. They are never returned to the browser or to agents after you submit them.
  • When you replace a configuration and leave the secret empty, Xentropy keeps the stored secret only if the destination and identity have not changed:
    • databases: the same host, port, database and user (SQL Server with Entra: the same tenant and client ID; Snowflake: the same account and user);
    • S3: the same endpoint, bucket and access key ID;
    • OpenAPI: the same server origin, and only for headers that the selected security scheme still requires.
  • Disconnecting a credential connection deletes its stored secret.

Disconnect and remove

  • Disconnect a connection from its page, or from the ⋯ menu on its card in Connected. Agents lose access at once. The connection moves to the Disconnected view, where you can open it and reconnect.
  • Remove permanently a disconnected connection from the ⋯ menu on its card in the Disconnected view. This deletes the connection and its saved settings, removes it from API keys that were limited to it, and can't be undone.
  • You can't remove a connection while datasets still read it. The dialog lists those datasets. Delete them, or bind them to another connection, then remove the connection.
  • A source shows Not available yet in Browse when it can't be connected yet. Its card has no Connect action until it is available.
  • Error messages name only what you typed, such as host, port, database, user or relation. Driver text, resolved addresses and secrets never appear in them.

Read limits

Every read is bounded. A read either returns complete data or fails. Results are never silently truncated.

LimitValue
Fields per dataset100
Rows per read50,000
Normalized data per read5 MiB
Relations listed for a database500
Objects listed in a bucket5,000 keys
Operations in an OpenAPI specification1,000
Pages per read (Shopify, HubSpot, Notion, BigQuery)Free 100, Pro 600
Read deadline (Shopify, HubSpot, Notion, BigQuery)30 s interactive, 300 s scheduled
BigQuery bytes billed per readDefault 1 GiB, at most 100 GiB

HubSpot and Notion pages hold 100 records, so on the Free plan their reads stop at about 10,000 rows. A larger source fails with INCOMPLETE_DATA or LIMIT_EXCEEDED. Select a smaller view, prefix or operation, or filter it at the source. Each kind's page lists its own limits.

Health and recovery

Testing a connection

Test runs the same checks as a save, stage by stage, and reports the first stage that fails:

StageWhat failedWhat to do
dnsThe hostname does not resolveCheck the spelling, and use the public hostname
network_policyThe host resolves to a private or reserved addressUse a public endpoint, or ask your administrator to allow the host
tcpNothing answered on that portCheck the port, and allow Xentropy's egress IPs in the firewall
tlsTLS is off, or the certificate does not verify for this hostEnable TLS, paste your private CA, or fix the certificate's names
authThe credentials or login rules were rejectedCheck the user, password, key or host rules
permissionA selected relation cannot be readGrant SELECT, or remove the relation from the selection
warehouseSnowflake only, on reads: the warehouse cannot run (missing USAGE, or suspended by a resource monitor). The form labels it Compute warehouseGrant USAGE on the warehouse, or resume it

Shopify, HubSpot, Notion and BigQuery use the stages auth (the token or key was rejected) and permissions (a scope or role is missing; missingScopes names it). BigQuery adds jobs (the service account cannot run query jobs). Their errors carry the code PROVIDER_ACCESS_DENIED with details.stage.

Database errors are coded POSTGRES_<STAGE>, MYSQL_<STAGE>, SQLSERVER_<STAGE> or SNOWFLAKE_<STAGE>, for example MYSQL_TLS or SNOWFLAKE_WAREHOUSE. Object storage has its own stages, such as S3_ACCESS_DENIED. See S3-compatible storage.

Errors during a read

CodeMeaningRetry?
PROVIDER_UNAVAILABLEThe source was unreachable or failed (HTTP 503). details.provider and details.stage say whereYes, later
RATE_LIMITEDThe source's rate limit or quota is used up. details.retryAt says when to retry, and scheduled refreshes wait until thenAfter retryAt
BUDGET_EXCEEDEDThe read ran past its time limitSelect less data
INCOMPLETE_DATAThe source has more than the limits allow, or pagination could not be proven completeNo; narrow the source
LIMIT_EXCEEDEDA size, row, field or object limit was exceededNo; narrow the source
SOURCE_CHANGEDThe object or file changed during the read, or after the dataset revision was savedYes, or read the current revision
SCHEMA_CHANGEDThe source's fields no longer match the saved definitionReview and save the dataset again
TYPE_MISMATCHA value does not match its saved field typeFix the data or the field's type
PERMISSION_DENIEDThe resource is no longer selected, or the network policy refused the hostReselect it, or fix the host
PROVIDER_ACCESS_DENIEDThe source denied access: Google Analytics to the property, or a business app or BigQuery to the token, key or scope. details.stage and details.missingScopes say whyNo; restore access first
PROVIDER_PLAN_REQUIREDThe source needs a paid plan or add-on for this data (for example a frozen Shopify store)No; resolve it at the source
NOT_FOUNDThe source no longer has the resource, or no longer shares it (a Notion database not shared with the connection)No; restore it at the source
SOURCE_RESULT_LIMITNotion returns at most 10,000 rows for one query, and the data source has moreNo; add a filter in Notion
COST_LIMIT_EXCEEDEDA BigQuery query would bill more than the connection's cap. Nothing was billedNo; narrow the query or raise the cap
QUERY_NOT_READ_ONLYA BigQuery query is not a single SELECTNo; rewrite it
PROVIDER_DISABLEDThe kind is not enabled for your accountNo; contact support
CONNECTION_TYPE_UNSUPPORTEDThe stored connection is a kind Xentropy can no longer readNo; recreate it

A read that completes can carry warnings, for example RELATION_TRUNCATED (Notion), VALUE_TRUNCATED (Notion text over 10,000 characters), NONFINITE_NULLED (BigQuery NaN) or API_VERSION_MISMATCH (Shopify).

A failed read never replaces earlier data. Live charts keep their previous capture, and the failure shows on the connection and dataset views.

Recovering

  1. Fix the cause at the source: the firewall rule, certificate, password, grant or bucket policy.
  2. Open the connection's detail view and choose Replace configuration. Leave the secret empty to keep the stored one (subject to the rules above), then test and save.
  3. For Google connections, reconnect and approve consent again. For Shopify, HubSpot, Notion and BigQuery, paste a new token, secret or key.
  4. Refresh the affected datasets or artifacts.

If a connection is in use and you rotate its password, the next read fails at the auth stage until you replace the configuration.

Folders

Connections can be organised in folders with Move to… on a connection card. A folder does not change a connection's credentials, access or what it can read. Agents with data:write or connections:write can move connections with folders_items_move.

On this page