SQL warehouses and databases
FACE reads Snowflake, Databricks SQL, PostgreSQL and MySQL through their standard drivers. A BigQuery configuration is accepted, but FACE does not run BigQuery queries yet (see BigQuery).
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 except BigQuery,
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 sample 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), 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 |
| Sample | Not implemented. Explore and fetch work. |
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 |
| Sample | Not implemented |
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.
| Value | Behaviour |
|---|---|
| (empty) | require, the default |
require | Encrypt without verifying the server certificate |
verify-ca, verify-full | Encrypt and verify |
disable | Deliberately cleartext |
prefer, allow | Refused. These modes can fall back to cleartext without saying so. |
BigQuery
| Type spellings | bigquery, bq |
| Config message | BigQueryConnectionConfig |
| Settings | project_id, dataset_id |
| Credentials | service_account_json (also credentials_json, google_credentials) |
| Test | Checks the settings and credential locally, then reports success: false with BigQuery configuration accepted, but a live check is not wired yet — the BigQuery SDK is not a dependency of this module. Nothing is contacted. |
| Execute | Not available: BigQuery queries are not executable yet: the BigQuery SDK is not a dependency of this module |
| Explore | supported=false |
Microsoft SQL Server, Amazon Redshift
There is no SQL Server connector. Amazon Redshift is recognised as a connection
type in the catalogue (it uses PostgreSQL’s settings), but no connector is
registered for it. A fetch or Test of a redshift connection is refused as an
unregistered type. FACE does not run PostgreSQL discovery against Redshift,
because Redshift answers some of those catalogue queries differently.