Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.formal.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Requirements

​
Networking

Certain ports must be accessible to connect to Formal Resources. You can listen on multiple ports simultaneously for various Resources. For accessing MySQL, you may assign any port except 8080 (Connector’s health check port). Ensure your security groups are configured to allow traffic on the designated port.

​
Database Health Check

Formal periodically assesses the health of the database. The database used for health checks can be configured in the Resource Details page (see Database Health Check Configuration). If not configured, the system defaults to the mysql database. Formal connects to the configured database and runs SELECT 1.

​
Native User Permissions

The native user should match the permissions end users need to have upstream. For read-only access, grant only SELECT on the application schemas. For read and write access, also grant the write permissions those users need. The native user must have permission to connect to the database configured for health checks. No special privileges are required for the health check itself. Formal does not require extra MySQL privileges just to proxy user queries. Granting SELECT on information_schema is recommended so the Connector can leverage the schema inventory in some policy edge cases. See Native Users for least-privilege guidance.

​
Connect to MySQL

Once the Connector is started and able to reach a MySQL Resource, you can connect to it using any MySQL-compatible client.
MySQL listeners take longer to start than other technologies because they generate a large RSA keypair at initialization. This key is used by the caching_sha2_password authentication plugin to encrypt credentials when clients connect without TLS. This can take up to a minute on modern hardware.
For example, to connect using the mysql CLI client, execute the following command: 
mysql -h CONNECTOR_HOSTNAME -P PORT -D DATABASE_NAME -u FORMAL_USERNAME --password=PASSWORD
Make sure to replace CONNECTOR_HOSTNAME, PORT, DATABASE_NAME, PASSWORD, and FORMAL_USERNAME with the right values. To learn more about users, check out Native Users.
You can access your Formal Credentials in the Formal console.
The standard mysql and mariadb CLI clients don’t support passwords longer than 80 characters when using the -p (interactive password) option. Since Formal access tokens exceed this limit, you must use hashed tokens instead.

​
Smart Routing

The Connector features Smart Routing for MySQL, allowing the linkage of an unlimited number of Resources over the same port (e.g. 3306). Provide the name of the resource following the database name: 
mysql -h CONNECTOR_HOSTNAME -P 3306 -D DATABASE_NAME@RESOURCE_NAME -u 'idp:formal:human:john@joinformal.com'
It is possible to attach multiple hostnames to a single resource. To specify the hostname of the resource you wish to connect to, you can use the following format: 
mysql -h CONNECTOR_HOSTNAME -P 3306 -D DATABASE_NAME@RESOURCE_NAME@RESOURCE_HOSTNAME_NAME -u 'idp:formal:human:john@joinformal.com'
Replace CONNECTOR_HOSTNAME, DATABASE_NAME, RESOURCE_NAME, and RESOURCE_HOSTNAME_NAME with the right values.

​
Policy Evaluation

Formal supports the following policy evaluation stages for MySQL:
  • Session: Evaluate and enforce policies at connection time
  • Request: Evaluate and enforce policies before query execution
  • Response: Evaluate and enforce policies after data retrieval