﻿<?xml version="1.0" encoding="utf-8"?>

<!-- EngineVersion = Java version -->
<ApiConfig Name="Apache Derby"
           Slug="apache-derby-connector"
           Type="JDBC"
           Category="database"
           Id="d3f4e6b7-8a9c-4b2d-bc3e-7f1a2d3c4e5f"
           Version="2"
           EngineVersion="8"
           Desc="Read and write Apache Derby databases 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/apache-derby-connector.png"
           HelpLink="https://community.zappysys.com/tag/apache-derby">

    <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://db.apache.org/derby/releases/release-10_14_2_0.html" />
        <Param Name="MvnRepositoryDriverDownloadLink"
               Value="https://mvnrepository.com/artifact/org.apache.derby/derbyclient" />
        <Param Name="DriverDownloadLinks"
               Hidden="True"
               Value="derbyclient-10.14.2.0.jar=https://repo1.maven.org/maven2/org/apache/derby/derbyclient/10.14.2.0/derbyclient-10.14.2.0.jar;derby-10.14.2.0.jar=https://repo1.maven.org/maven2/org/apache/derby/derby/10.14.2.0/derby-10.14.2.0.jar" />
    </Template>
    <Auths>
        <Auth Name="ClientServerEnvironment"
              Label="Client/server"
              ConnStr="jdbc:derby://[$HostName$]:[$Port$]/[$Database$]"
              HelpLink="https://db.apache.org/derby/docs/10.14/getstart/cgsquck13780.html">
            <Params>
                <Param Name="DriverClass" Label="Driver class" Required="False" Value="org.apache.derby.jdbc.ClientDriver" Desc="Optional. Leave blank to auto-detect from the JAR unless SPI is ambiguous (e.g. org.apache.derby.jdbc.ClientDriver)." HelpLink="https://db.apache.org/derby/docs/10.14/getstart/cgsquck13780.html" />
                <Param Name="DriverFilePaths" Editor="FileOpen" Label="JDBC driver file(s)" Required="True" Value="{DownloadFolder}\derbyclient-10.14.2.0.jar" Desc="Filled by the wizard after download. Separate multiple JARs with a semicolon (e.g. C:\ZappySys\Jdbc\MyConnector\driver.jar)." HelpLink="https://db.apache.org/derby/docs/10.14/getstart/cgsquck13780.html" />
                <Param Name="HostName" Label="Host" Required="True" Value="MyHostName" Desc="JDBC host name or IP (e.g. MyHostName)." HelpLink="https://db.apache.org/derby/docs/10.14/getstart/cgsquck13780.html" />
                <Param Name="Port" Label="TCP port" Required="True" Value="1527" Desc="JDBC port (e.g. 1527)." HelpLink="https://db.apache.org/derby/docs/10.14/getstart/cgsquck13780.html" />
                <Param Name="Database" Label="Database name" Required="False" Value="MyDatabase" Desc="Database, schema, or catalog name (e.g. MyDatabase)." HelpLink="https://db.apache.org/derby/docs/10.14/getstart/cgsquck13780.html" />
                <Param Name="UserName" Label="User name" Required="False" Desc="Database user. Leave empty if the server allows anonymous JDBC." HelpLink="https://db.apache.org/derby/docs/10.14/getstart/cgsquck13780.html" />
                <Param Name="Password" Label="Password" Required="False" Secret="True" Desc="Database password. Leave empty if none." HelpLink="https://db.apache.org/derby/docs/10.14/getstart/cgsquck13780.html" />
            </Params>
            <Notes>
                <![CDATA[<p>Apache Derby network server from Power BI, SQL Server Linked Server via ZappySys Data Gateway, Crystal Reports, SSRS, Azure Data Factory, and other ODBC tools.</p>
<ol>
<li>Start Network Server (default port <code>1527</code>) or use an existing one.</li><li>Create a database user if authentication is on. Lab often uses a simple user/password.</li><li>Seed Driver class as <code>ClientDriver</code> (SPI can also load EmbeddedDriver).</li><li>After Finish, replace the host (e.g. MyHostName) and database name (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="EmbeddedEnvironment"
              Label="Embedded file"
              ConnStr="jdbc:derby:{DownloadFolder}\mydatabase;create=true"
              HelpLink="https://db.apache.org/derby/docs/10.14/getstart/cgsquck35643.html">
            <Params>
                <Param Name="DriverClass" Label="Driver class" Required="False" Value="org.apache.derby.jdbc.EmbeddedDriver" Desc="Optional. Leave blank to auto-detect from the JAR unless SPI is ambiguous (e.g. org.apache.derby.jdbc.EmbeddedDriver)." HelpLink="https://db.apache.org/derby/docs/10.14/getstart/cgsquck35643.html" />
                <Param Name="DriverFilePaths" Editor="FileOpen" Label="JDBC driver file(s)" Required="True" Value="{DownloadFolder}\derby-10.14.2.0.jar" Desc="Filled by the wizard after download. Separate multiple JARs with a semicolon (e.g. C:\ZappySys\Jdbc\MyConnector\driver.jar)." HelpLink="https://db.apache.org/derby/docs/10.14/getstart/cgsquck35643.html" />
            </Params>
            <Notes>
                <![CDATA[<p>Apache Derby embedded from Power BI, SQL Server Linked Server via ZappySys Data Gateway, Crystal Reports, SSRS, Azure Data Factory, and other ODBC tools.</p>
<ol>
<li>No server. The database folder is created under <code>{DownloadFolder}</code>.</li><li>Use <code>EmbeddedDriver</code> (do not leave class blank -- SPI is ambiguous with the client JAR).</li><li>Optional: add <code>;create=true</code> (already in this URL) the first time.</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="Memory"
              Label="In-memory"
              ConnStr="jdbc:derby:memory:[$Database$];create=true"
              HelpLink="https://db.apache.org/derby/docs/10.14/devguide/cdevdvlpinmemdb.html">
            <Params>
                <Param Name="DriverClass" Label="Driver class" Required="False" Value="org.apache.derby.jdbc.EmbeddedDriver" Desc="Optional. Leave blank to auto-detect from the JAR unless SPI is ambiguous (e.g. org.apache.derby.jdbc.EmbeddedDriver)." HelpLink="https://db.apache.org/derby/docs/10.14/devguide/cdevdvlpinmemdb.html" />
                <Param Name="DriverFilePaths" Editor="FileOpen" Label="JDBC driver file(s)" Required="True" Value="{DownloadFolder}\derby-10.14.2.0.jar" Desc="Filled by the wizard after download. Separate multiple JARs with a semicolon (e.g. C:\ZappySys\Jdbc\MyConnector\driver.jar)." HelpLink="https://db.apache.org/derby/docs/10.14/devguide/cdevdvlpinmemdb.html" />
                <Param Name="Database" Label="Database name" Required="False" Value="MyDatabase" Desc="Database, schema, or catalog name (e.g. MyDatabase)." HelpLink="https://db.apache.org/derby/docs/10.14/devguide/cdevdvlpinmemdb.html" />
            </Params>
            <Notes>
                <![CDATA[<p>Apache Derby in-memory from Power BI, SQL Server Linked Server via ZappySys Data Gateway, Crystal Reports, SSRS, Azure Data Factory, and other ODBC tools.</p>
<ol>
<li>Data lasts for this DSN Java process only.</li><li>Keep EmbeddedDriver. Use for labs and Excel previews.</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://db.apache.org/derby/docs/10.14/ref/rrefsqlj81859.html">
            <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[SELECT TABLENAME FROM SYS.SYSTABLES WHERE TABLETYPE = 'T' ORDER BY TABLENAME]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="select-rows" Label="Select rows" HelpLink="https://db.apache.org/derby/docs/10.14/ref/rrefsqlj81859.html">
            <Desc><![CDATA[<p>Returns rows from <code>"APP"."ORDERS"</code>. Replace the identifier with your catalog object. Works in Excel, SSRS, and Crystal Reports.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM "APP"."ORDERS"]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="filter-rows" Label="Filter with WHERE" HelpLink="https://db.apache.org/derby/docs/10.14/ref/rrefsqlj81859.html">
            <Desc><![CDATA[<p>Returns matching rows from <code>"APP"."ORDERS"</code>.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM "APP"."ORDERS"
WHERE id = 1]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="join-tables" Label="Join tables" HelpLink="https://db.apache.org/derby/docs/10.14/ref/rrefsqlj81859.html">
            <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 "APP"."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://db.apache.org/derby/docs/10.14/ref/rrefsqlj81859.html">
            <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 "APP"."ORDERS"
GROUP BY status]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="order-limit" Label="Order and limit" HelpLink="https://db.apache.org/derby/docs/10.14/ref/rrefsqlj81859.html">
            <Desc><![CDATA[<p>Returns the first 100 rows. Useful for preview in Excel or Crystal Reports.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM "APP"."ORDERS"
FETCH FIRST 100 ROWS ONLY]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="count-all" Label="Count rows" HelpLink="https://db.apache.org/derby/docs/10.14/ref/rrefsqlj81859.html">
            <Desc><![CDATA[<p>Returns the number of rows in <code>"APP"."ORDERS"</code>.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT COUNT(*) AS row_count FROM "APP"."ORDERS"]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="case-expr" Label="CASE expression" HelpLink="https://db.apache.org/derby/docs/10.14/ref/rrefsqlj81859.html">
            <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 "APP"."ORDERS"]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="select-list" Label="Select specific columns" HelpLink="https://db.apache.org/derby/docs/10.14/ref/rrefsqlj81859.html">
            <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 "APP"."ORDERS"]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="having" Label="Filter groups with HAVING" HelpLink="https://db.apache.org/derby/docs/10.14/ref/rrefsqlj81859.html">
            <Desc><![CDATA[<p>Keeps groups whose count is at least 1.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT status, COUNT(*) AS row_count
FROM "APP"."ORDERS"
GROUP BY status
HAVING COUNT(*) >= 1]]>
            </Code>
        </Example>

        <Example Default="True" Group="ODBC" Slug="list-orders" Label="List orders">
            <Desc><![CDATA[<p>Returns all rows from the orders table in the APP schema. In Apache Derby, schema and table names are case-sensitive; quote them when needed.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT * FROM "APP"."ORDERS"]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="list-order-lines" Label="List order lines">
            <Desc><![CDATA[<p>Returns order lines with the order ID by joining orders and order lines.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT o.ID, ol.*
FROM "APP"."ORDERS" AS o
JOIN "APP"."ORDER_LINES" AS ol
  ON o.ID = ol.ORDER_ID]]>
            </Code>
        </Example>

        <Example Group="ODBC" Slug="get-product-quantities-for-a-specific-order" Label="Get product quantities for a specific order">
            <Desc><![CDATA[<p>Returns product name and quantity for each line item in a single order.</p>]]></Desc>
            <Code>
                <![CDATA[SELECT
    ol.ORDER_ID,
    p.NAME AS Product,
    ol.QUANTITY
FROM "APP"."ORDER_LINES" AS ol
JOIN "APP"."PRODUCTS" AS p ON ol.PRODUCT_ID = p.ID
WHERE ol.ORDER_ID = 12345]]>
            </Code>
        </Example>
    </Examples>
</ApiConfig>
