> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/consume/activate/mysql-clients/mysql.md). # MySQL Query semantic models from the terminal with mysql classic client. The semantic layer already handles joins, aggregations, and transformations, so you write plain SQL. > **Want to query your data?** See the [Query Guide](/consume/activate/mysql-clients/mysql/query.md) for SQL examples, supported syntax, and tips. ## Prerequisites
RequirementDetail
Classic MySQL clientThe standard mysql command-line client. Install steps for Windows and macOS below.
DataOS usernameYour DataOS ID. Used as the connection username.
DataOS API tokenYour DataOS API token. Used as the password. Get it from Profile icon → your name → Tokens.
> **Use the classic `mysql` client, not `mysqlsh`.** DataOS connection commands need `--enable-cleartext-plugin`, which `mysqlsh` doesn't support. All examples below assume the classic `mysql` client. *** ## Install on Windows First-time setup only. Skip to [Connect](#connect) if `mysql --version` already works. ### 1. Download the installer Get **MySQL Installer Community**: [link](https://dev.mysql.com/downloads/installer/) and pick `mysql-installer-web-community`. ### 2. Install components 1. Launch **MySQL Installer**. 2. Click **Add…**. 3. Expand **MySQL Servers**. 4. Pick **MySQL Server 8.0** (or the latest available). 5. Click **>** to add it, then **Next**, then **Execute**. > Installing the MySQL Server is the easiest way to get `mysql.exe`. You won't use the local database with DataOS; it's just there to provide the client. ### 3. Configure the local server Accept the defaults at each screen: * **Type and Networking:** Development Computer, TCP/IP enabled, Port 3306, Open Windows Firewall Ports → **Next**. * **Authentication Method:** Use Strong Password Encryption (Recommended) → **Next**. * **Accounts and Roles:** set any root password (e.g. `root123`) → **Next**. * **Windows Service:** keep "Configure MySQL Server as Windows Service" and "Start at System Startup" → **Next**. * **Apply Configuration:** click **Execute**, wait for green checkmarks, then **Finish**. ### 4. Add MySQL to PATH 1. Press **Win + R** and run `sysdm.cpl`. 2. Go to **Advanced → Environment Variables → System Variables → Path → New**. 3. Add: ``` C:\Program Files\MySQL\MySQL Server 8.0\bin ``` 4. Click **OK**, close and reopen PowerShell. ### 5. Verify ```powershell mysql --version ``` Expected: ``` mysql Ver 8.x.x for Win64 ``` Confirm the executable location: ```powershell where mysql ``` Expected: ``` C:\Program Files\MySQL\MySQL Server 8.0\bin\mysql.exe ``` *** ## Install on macOS First-time setup only. Skip to [Connect](#connect) if `mysql --version` already works. ### Official package Download the MySQL Community Server DMG from the [download page](https://dev.mysql.com/downloads/mysql/8.0.html) that matches your system configuration, then install it. ### Verify ```bash mysql --version ``` Expected: ``` mysql Ver 8.x.x for macos on ... ``` *** ## Connect In the data product, go to **Activate → Database Client** and open the **MySQL** guide. Starting there saves you from assembling the command yourself: the in-product guide gives you a ready-to-run connection command and a sample query for the selected data product. ![In-product MySQL setup page showing the connection command and a sample query](/files/AY61rVrV8YuOpCat5teQ) Copy the command, drop in your username, API token, and database, then run it: ```bash mysql -h -P 3306 -u -p'' --enable-cleartext-plugin . ``` Example: ```bash mysql -h tcp.pacific-051426.dataos.cloud -P 3306 -u kanakguptatmdcio -p'' --enable-cleartext-plugin product-sandbox.powerbi-pg ``` Or omit the key after `-p` and you'll be prompted for it: ```bash mysql -h tcp.pacific-051426.dataos.cloud -P 3306 -u kanakguptatmdcio -p --enable-cleartext-plugin product-sandbox.powerbi-pg ``` Parameters:
ParameterDescription
-hYour DataOS TCP host
-P 3306MySQL wire protocol port
-uYour DataOS username
-pYour DataOS API token (no space between -p and the value)
--enable-cleartext-pluginRequired. Enables cleartext authentication over TLS.
Last argument<tenant>.<data-product-name>: the semantic model to connect to
> **API token format:** Wrap the key in single quotes if it has special characters, e.g. `-p'abc123=='`. *** ## Query your data Once connected, run SQL against the semantic model: ```sql SELECT TABLE_NAME,TABLE_COMMENT FROM information_schema.tables WHERE table_schema = 'public';; -- Helps you distinguish between tables and metrics SHOW FULL COLUMNS FROM ; -- Helps you understand the measures and dimensions ``` > See the [Query Guide](/consume/activate/mysql-clients/mysql/query.md) for SQL examples, supported syntax, and tips. *** ## Troubleshooting | Symptom | Fix | | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Access denied` | API token is wrong or expired. Get a fresh one from the Tokens tab and retry. | | `Unknown database` | The `.` value is off. Copy the exact name from the data product page. | | Connection times out | Port `3306` is probably blocked. Check VPN and firewall rules between your machine and the DataOS TCP host. | | `cleartext plugin not loaded` | You're missing `--enable-cleartext-plugin`. | | `mysql: command not found` / `'mysql' is not recognized` | The MySQL `bin` directory isn't on your PATH. Re-check the install steps and reopen your terminal. On Windows, verify with `dir "C:\Program Files\MySQL" -Recurse -Filter mysql.exe`. | | `mysqlsh: unknown option --enable-cleartext-plugin` | You're using MySQL Shell (`mysqlsh`). Use the classic `mysql`. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://v2.dataos.info/consume/activate/mysql-clients/mysql.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.