SQL warehouses and databases
FACE reads Snowflake, Databricks SQL, PostgreSQL and MySQL through their standard drivers.
Common behaviour
- Queries are read-only. Every statement must start with
SELECT,WITH,SHOW,DESCRIBE,DESCorEXPLAIN. A statement that contains restricted keywords is refused. Unclosed comments and string literals are refused. - Parameters are bound. Values in
paramsare passed to the driver as bound parameters, never interpolated into the SQL. A positional parameter list may accompany only a single statement. - Multi-statement batches report partial failure. If some statements in a batch are refused by the engine, the read still returns the rows from the others. The message states how many statements failed. It lists up to 8 reasons, and the count is never truncated.
- Credentials come from the credential bundle, never from the record. See Connections and credentials.
- Test dials the source. For every engine on this page,
Test opens a connection and runs the driver’s
Ping. A success means the endpoint answered and the credential was accepted. It does not mean the role can read any particular table. - How queries arrive. In a fetch, Snowflake and Databricks run FACE’s
built-in fetch template for that engine. PostgreSQL and MySQL read the
business tables they expose (a sweep of their tables). Both run on the
selected runner. Outside a fetch,
SqlService.ExecuteandExecuteSelectaccept an explicitsqlandparamsagainst a storedconnection_id(see /docs/api/). - A failure is reported as a failure. When an engine cannot be reached, the
fetch reports
<type> Execution Failed for <name>: …, with personal data masked. No other data is substituted.
Snowflake
| Type spellings | snowflake |
| Config message | SnowflakeConnectionConfig |
| Settings | account (required), warehouse, database, schema, role, user |
| Credentials | password (or pat / token for a programmatic access token). user or username may also come from the bundle. |
| Connection string | connection_string in the form user[:password]@account/database[/schema][?param=value…], parsed at save time |
| Transport | HTTPS through FACE’s hardened transport. The address policy applies, and internal addresses are refused unless allow_internal_network=true is set. |
| Test | A live dial (driver ping) |
| Explore | INFORMATION_SCHEMA.TABLES and .COLUMNS, scoped to database and to schema when set. Includes the table kind, column order, the account’s own type spelling, declared nullability, and ROW_COUNT (left unstated for views). |
| Sample | SAMPLE (n ROWS). Default 10 rows, at most 100, cells capped at 512 bytes. |
Optional runner-deploy settings (none of them is a credential) are compute_pool,
image_repository, runner_image (pinned by digest, …@sha256:<hex>),
network_rule, external_access_integration. See Runners.
Databricks
| Type spellings | databricks |
| Config message | DatabricksConnectionConfig |
| Settings | host (the workspace host, required; https:// is assumed, and http:// is refused), http_path (required: the /sql/1.0/warehouses/… path of one SQL warehouse or cluster) |
| Scope properties | catalog (or databricks_catalog, unity_catalog), schema (or databricks_schema) |
| Credentials | personal_access_token (or token) |
| Connection string | connection_string, parsed at save time |
| Transport | Port 443, through FACE’s hardened transport. The address policy applies, and internal addresses are refused unless opted in. |
| Test | A live dial (driver ping) |
| Explore | system.information_schema columns joined to tables (metastore-wide, or one catalog when catalog is set). Declared units and PII classes come from column tags. Complete vocabularies come from CHECK (col IN (…)) constraints. |
| Sample | Default 25 rows, at most 1000 (a larger value is refused). Cells are capped at 4096 bytes. Method: FIRST_ROWS. |
Optional runner-deploy settings (none of them is a credential) are cluster_policy_id,
node_type_id, spark_version, runner_artifact, runner_artifact_sha256,
runner_scope (the name of a secret scope), service_principal (an
application id, not its secret).
PostgreSQL
| Type spellings | postgres, postgresql |
| Config message | PostgresConnectionConfig |
| Settings | host, port (default 5432), database, username, ssl_mode |
| Credentials | password; username may also come from the bundle |
| Test | A live dial (driver ping) |
| Explore | information_schema tables and columns (up to 500 tables) and declared keys from pg_catalog.pg_constraint |
MySQL
| Type spellings | mysql |
| Config message | MySqlConnectionConfig |
| Settings | host, port (default 3306), database, username; ssl_mode as a property |
| Credentials | password |
| Test | A live dial (driver ping) |
| Explore | information_schema tables and columns, and declared keys from TABLE_CONSTRAINTS joined to KEY_COLUMN_USAGE |
Multi-statement mode is off at the driver.
Database TLS (ssl_mode)
PostgreSQL reads the typed ssl_mode field. MySQL reads the ssl_mode property.
Every PostgreSQL and MySQL connection must state it, and must have a username and a
password credential. See Security requirements.
| Value | Behaviour |
|---|---|
| (empty) | Refused. The setting must be stated, so that it can be audited. |
require | Encrypt without verifying the server certificate |
verify-ca, verify-full | Encrypt and verify |
disable, prefer, allow | Refused. These modes send data without TLS, or can fall back to it silently. |