MySQL

Register a MySQL database and it becomes a live, read-only catalog in the lake. Query it directly for ad hoc work, or import tables into Iceberg when you want a snapshot you can run large jobs against. Connections are managed in Settings → Lake.

For production databases, point oleander at a read replica with a dedicated read-only user, and make sure the database firewall allows oleander’s egress.

Setup

Open Settings → Lake and choose Add MySQL connection.
Paste a mysql:// URL to fill the fields automatically, or enter them by hand:

Field	Description
Connection name	Lowercase letters, numbers, and underscores, e.g. `my_mysql`. This becomes the catalog prefix in SQL. Names are shared across all connection types, so it cannot match an existing Postgres, MongoDB, or other connection.
Host	Database host, e.g. `db.example.com`
Port	Defaults to `3306`
Database	The database to expose
SSL mode	`DISABLED`, `PREFERRED` (default), `REQUIRED`, `VERIFY_CA`, or `VERIFY_IDENTITY`
Username	The user oleander connects as
Password	Stored encrypted and never returned to the browser

The dialog generates the SQL for a read-only user if you want to create one - copy it and run it against your database before saving:

CREATE USER 'oleander_reader'@'%' IDENTIFIED BY '<choose a password>';
GRANT SELECT, SHOW VIEW ON `app_production`.* TO 'oleander_reader'@'%';

Querying live

A connection is scoped to one database, so tables are reachable as connection_name.database.table:

-- Read straight from MySQL
SELECT id, email, created_at
FROM my_mysql.app_production.users
WHERE created_at >= '2026-01-01'
LIMIT 100;

-- Join MySQL against your Iceberg lake
SELECT u.email, count(*) AS events
FROM my_mysql.app_production.users u
JOIN oleander.default.events e ON e.user_id = u.id
GROUP BY 1;

In the lake tree, column lists come from information_schema with primary key columns marked.

A MySQL table selects DuckDB. DuckDB is the only engine that attaches external connections, so the query router routes any query naming a connection table there before it considers input size - leave engine on auto. Asking for Bloom, Polars, or Spark on one of these queries returns an engine capability error rather than rerouting silently.

Live reads run against your database, so treat them the way you would treat any query against production: filter, limit, and prefer a replica. Once a table is imported it lives in Iceberg and the router is free to send it to any engine.

Importing into Iceberg

For anything larger than an ad hoc read, import the table. The import runs as a Spark JDBC read and lands the data as an Iceberg table in your lake, where every engine can reach it.

The read is split into parallel ranges over the table’s integer primary key, with the partition count following table size. A table without an integer primary key is read on a single connection.
DATETIME values keep their wall-clock time, and zero dates (0000-00-00) are read as NULL.

Unlike Postgres imports, MySQL cannot share one snapshot across connections, so a parallel import of a live, changing table is not guaranteed to be consistent across partitions. Import from a replica, or during a quiet period, when that matters.

The destination defaults to oleander.default.<table> - the sanitized source table name, with no connection prefix. OVERWRITE replaces it, APPEND adds to it.

For large tables, prefer more executors (4-8) over bigger machines. Each executor core opens one connection to the source database.

An import does not return rows. It submits a job and returns a run_id you can monitor like any other run, and once it completes you can sample the destination with a normal query.

Table syncing

A one-off import gives you a snapshot. Put the same import on a schedule and the Iceberg copy tracks the source instead. Schedules run hourly or daily, and are managed the same way as Postgres syncs: under Scheduled syncs in Settings → Lake, and under Transfers in the lake’s left panel.

Scheduled syncs are incremental where the table allows it. After the first full import, each run picks up new and changed rows rather than recopying the table.

What a run does depends on the table’s keys, and the reason is written to the run’s plan log:

Table has	Each run
A timestamp cursor column and a primary key	Merges rows changed since the last run
An integer primary key only	Appends rows with a key above the last one seen
Neither	Falls back to a full refresh

Every sync run is a normal oleander run: it appears in run history, emits lineage with the MySQL table as the input and the Iceberg table as the output, and carries cost like any other job.

From an agent

Two tools cover MySQL over MCP:

Tool	What it does
`mysql_connections_list`	List registered connections - name, host, port, database, username, SSL mode. Credentials are never returned.
`mysql_tables_import`	Import a table into Iceberg with the partitioned, parallel read described above

For ad hoc reads of live data an agent uses query_run against connection.database.table instead.

Permissions

MySQL connections are an IAM resource type. Registering one requires Create on MySQL connections → All MySQL connections. Browsing a connection’s tables in the lake tree and importing from it require Describe on that specific connection, and scheduled syncs check the same permission for the principal that runs them. See Resources and actions.

Getting Started

Platform

IAM

Connections

Integrations

Coding with agents

CLI

External Compute

Setup

Querying live

Importing into Iceberg

Table syncing

From an agent

Permissions

​Setup

​Querying live

​Importing into Iceberg

​Table syncing

​From an agent

​Permissions

Setup

Querying live

Importing into Iceberg

Table syncing

From an agent

Permissions