<?xml version="1.0" encoding="utf-8"?>

<!-- EngineVersion = Java version -->
<ApiConfig Name="MariaDB"
           Slug="mariadb-connector"
           Type="JDBC"
           Category="database"
           Id="b3f7c8d4-5a6e-4f3b-9d2e-7c8a9f4e1b2c"
           Version="2"
           EngineVersion="8"
           Desc="Read and write MariaDB from Power BI, SQL Server Linked Server via ZappySys Data Gateway, Crystal Reports, SSRS, Azure Data Factory, and other ODBC tools -- almost no coding required."
           Logo="https://cdn.zappysys.com/api/images/logos/mariadb-connector.png"
           HelpLink="https://community.zappysys.com/search?q=mariadb">

    <VersionHistory>
      <Change Ver="2" Date="2026-09-15" Type="Modified">Auth Notes (numbered steps), documented params, Maven DriverDownloadLinks, extra SQL examples for ODBC apps.</Change>
      <Change Ver="1" Date="2025-04-29" Type="New">Initial version.</Change>
    </VersionHistory>
    <Template>
        <Param Name="DriverDownloadPageLink"
               Value="https://mariadb.com/downloads/connectors/connectors-data-access/java8-connector" />
        <Param Name="MvnRepositoryDriverDownloadLink"
               Value="https://mvnrepository.com/artifact/org.mariadb.jdbc/mariadb-java-client" />
        <Param Name="DriverDownloadLinks"
               Hidden="True"
               Value="mariadb-java-client-3.5.3.jar=https://repo1.maven.org/maven2/org/mariadb/jdbc/mariadb-java-client/3.5.3/mariadb-java-client-3.5.3.jar" />
    </Template>
    <Auths>
        <Auth Name="Default"
              Label="Default connection"
              ConnStr="jdbc:mariadb://[$HostName$]:[$Port$]/[$Database$]"
              HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/">
            <Params>
                <Param Name="DriverClass" Label="Driver class" Required="False" Value="org.mariadb.jdbc.Driver" Desc="Optional. Leave blank to auto-detect from the JAR unless SPI is ambiguous (e.g. org.mariadb.jdbc.Driver)." HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/" />
                <Param Name="DriverFilePaths" Editor="FileOpen" Label="JDBC driver file(s)" Required="True" Value="{DownloadFolder}\mariadb-java-client-3.5.3.jar" Desc="Filled by the wizard after download. Separate multiple JARs with a semicolon (e.g. C:\ZappySys\Jdbc\MyConnector\driver.jar)." HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/" />
                <Param Name="HostName" Label="Host" Required="True" Value="MyHostName" Desc="JDBC host name or IP (e.g. MyHostName)." HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/" />
                <Param Name="Port" Label="TCP port" Required="True" Value="3306" Desc="JDBC port (e.g. 3306)." HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/" />
                <Param Name="Database" Label="Database name" Required="False" Value="MyDatabase" Desc="Database, schema, or catalog name (e.g. MyDatabase)." HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/" />
                <Param Name="UserName" Label="User name" Required="False" Desc="Database user. Leave empty if the server allows anonymous JDBC." HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/" />
                <Param Name="Password" Label="Password" Required="False" Secret="True" Desc="Database password. Leave empty if none." HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/" />
            </Params>
            <Notes>
                <![CDATA[<p>MariaDB from Power BI, SQL Server Linked Server via ZappySys Data Gateway, Crystal Reports, SSRS, Azure Data Factory, and other ODBC tools.</p>
<ol>
<li>Note the host, port (default <code>3306</code>), and database name.</li><li>Create an application user (not a personal DBA login) with SELECT on the schemas you need.</li><li>Paste user and password. After Finish, edit the host (e.g. MyHostName) and database (e.g. MyDatabase) on the DSN Main UI.</li>
<li>Finish the wizard. Then click <strong>Test Connection</strong> on the DSN Main UI (the wizard does not run Test Connection).</li><li>Done. You can query from C#, Python, PowerShell, and ODBC apps.</li>
</ol>]]>
            </Notes>
        </Auth>
        <Auth Name="Ssl"
              Label="SSL connection"
              ConnStr="jdbc:mariadb://[$HostName$]:[$Port$]/[$Database$]?sslMode=[$SslMode$]"
              HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/">
            <Params>
                <Param Name="DriverClass" Label="Driver class" Required="False" Value="org.mariadb.jdbc.Driver" Desc="Optional. Leave blank to auto-detect from the JAR unless SPI is ambiguous (e.g. org.mariadb.jdbc.Driver)." HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/" />
                <Param Name="DriverFilePaths" Editor="FileOpen" Label="JDBC driver file(s)" Required="True" Value="{DownloadFolder}\mariadb-java-client-3.5.3.jar" Desc="Filled by the wizard after download. Separate multiple JARs with a semicolon (e.g. C:\ZappySys\Jdbc\MyConnector\driver.jar)." HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/" />
                <Param Name="HostName" Label="Host" Required="True" Value="MyHostName" Desc="JDBC host name or IP (e.g. MyHostName)." HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/" />
                <Param Name="Port" Label="TCP port" Required="True" Value="3306" Desc="JDBC port (e.g. 3306)." HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/" />
                <Param Name="Database" Label="Database name" Required="False" Value="MyDatabase" Desc="Database, schema, or catalog name (e.g. MyDatabase)." HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/" />
                <Param Name="SslMode" Label="SSL mode" Required="True" Options="Notset=;Preferred=PREFERRED;Required=REQUIRED;Verify CA=VERIFY_CA;Verify identity=VERIFY_IDENTITY;Trust=trust" Value="trust" Desc="MySQL/MariaDB sslMode (e.g. Trust from the dropdown)." HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/" />
                <Param Name="UserName" Label="User name" Required="True" Desc="Database user. Leave empty if the server allows anonymous JDBC." HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/" />
                <Param Name="Password" Label="Password" Required="True" Secret="True" Desc="Database password. Leave empty if none." HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/" />
            </Params>
            <Notes>
                <![CDATA[<p>MariaDB with TLS from Power BI, SQL Server Linked Server via ZappySys Data Gateway, Crystal Reports, SSRS, Azure Data Factory, and other ODBC tools.</p>
<ol>
<li>Same as Default Auth. Use this when the server requires TLS (managed Cloud SQL, RDS, SkySQL).</li><li>After Finish, confirm <code>sslMode</code> on the JDBC URL matches your server (REQUIRED vs VERIFY_CA).</li>
<li>Finish the wizard. Then click <strong>Test Connection</strong> on the DSN Main UI (the wizard does not run Test Connection).</li><li>Done. You can query from C#, Python, PowerShell, and ODBC apps.</li>
</ol>]]>
            </Notes>
        </Auth>
    </Auths>

    <Examples>
        <Example Group="ODBC" Slug="list-tables" Label="List tables" HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/">
            <Desc><![CDATA[<p>Lists tables available to this connection. Use this in Power BI or a SQL Server Linked Server to confirm the catalog before building reports.</p>]]></Desc>
            <Code>
                <![CDATA[SHOW TABLES]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="select-rows" Label="Select rows" HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/">
            <Desc><![CDATA[<p>Returns rows from <code>orders</code>. Replace the identifier with your catalog object. Works in Excel, SSRS, and Crystal Reports.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM orders]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="filter-rows" Label="Filter with WHERE" HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/">
            <Desc><![CDATA[<p>Returns matching rows from <code>orders</code>.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM orders
WHERE id = 1]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="join-tables" Label="Join tables" HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/">
            <Desc><![CDATA[<p>Joins two tables on a key. Use in Azure Data Factory or SSIS when you need a combined extract.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT a.id, a.name, b.amount
FROM orders AS a
JOIN my_other_table AS b ON a.id = b.parent_id]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="group-by" Label="Aggregate with GROUP BY" HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/">
            <Desc><![CDATA[<p>Counts rows per group. Typical Power BI import pattern before a visual.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT status, COUNT(*) AS row_count
FROM orders
GROUP BY status]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="order-limit" Label="Order and limit" HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/">
            <Desc><![CDATA[<p>Returns the first 100 rows. Useful for preview in Excel or Crystal Reports.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM orders
ORDER BY 1
LIMIT 100]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="count-all" Label="Count rows" HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/">
            <Desc><![CDATA[<p>Returns the number of rows in <code>orders</code>.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT COUNT(*) AS row_count FROM orders]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="case-expr" Label="CASE expression" HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/">
            <Desc><![CDATA[<p>Maps a column to labels with <code>CASE</code>.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT id,
       CASE WHEN status = 'A' THEN 'Active' ELSE 'Other' END AS status_label
FROM orders]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="select-list" Label="Select specific columns" HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/">
            <Desc><![CDATA[<p>Returns a column list instead of star. Prefer this in Linked Server views.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT id, name, status
FROM orders]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="having" Label="Filter groups with HAVING" HelpLink="https://mariadb.com/kb/en/about-mariadb-connector-j/">
            <Desc><![CDATA[<p>Keeps groups whose count is at least 1.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT status, COUNT(*) AS row_count
FROM orders
GROUP BY status
HAVING COUNT(*) >= 1]]>
            </Code>
        </Example>

        <Example Default="True" Group="ODBC" Slug="read-orders" Label="Read orders">
            <Desc><![CDATA[<p>Gets all rows from the <code>orders</code> table. Use this in Power BI or Excel to list every order without filtering.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM orders]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="read-order-lines" Label="Read order lines">
            <Desc><![CDATA[<p>Gets order lines joined with orders so you can see which lines belong to which order.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT
    o.id,
    ol.*
FROM orders o
JOIN order_lines ol
  ON o.id = ol.order_id]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="read-product-quantities-for-specific-order" Label="Read product quantities for a specific order">
            <Desc><![CDATA[<p>Gets product name and quantity for each line of one order. Replace 12345 with your order ID.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT
    ol.order_id,
    p.name AS product,
    ol.quantity
FROM order_lines ol
JOIN products p ON ol.product_id = p.id
WHERE ol.order_id = 12345]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="read-data-from-table-with-space-in-name" Label="Read data from a table with a space in its name">
            <Desc><![CDATA[<p>Run <code>SET SESSION sql_mode</code> once to enable ANSI_QUOTES, then SELECT from a backtick-quoted table name.</p>]]></Desc>
            <Code>
                <![CDATA[SET SESSION sql_mode = CONCAT(@@SESSION.sql_mode, ',ANSI_QUOTES')

SELECT
    id,
    name
FROM `order lines`]]>
            </Code>
        </Example>
    </Examples>
</ApiConfig>
