eclipsedaanse/daanse-pivot-duckdb repository overview

⁠Daanse Pivot Server — DuckDB

Production Daanse OLAP (XMLA) server image for DuckDB. The image ships the Daanse ROLAP engine, the XMLA endpoint, the DuckDB JDBC driver, the DataSource and the matching SQL dialect. It is configured entirely through environment variables. The DuckDB database is a file mounted into the container and is opened read-only by default (DuckDB access_mode=READ_ONLY; an in-memory DuckDB would be private to each connection and is therefore not useful here).

Note: this image is based on Debian (eclipse-temurin:25-jre) instead of Alpine because the DuckDB native library requires glibc.

Images: docker.io/eclipsedaanse/daanse-pivot-duckdb:snapshot and ghcr.io/eclipse-daanse/daanse-pivot-duckdb:snapshot (linux/amd64, linux/arm64).

⁠Quick start

docker run --name daanse-pivot \
  -v ./catalog:/app/catalog:ro \
  -v ./database.duckdb:/app/data/database.duckdb:ro \
  -p 8080:8080 \
  eclipsedaanse/daanse-pivot-duckdb:snapshot

The XMLA endpoint is then available at http://localhost:8080/xmla.

⁠DuckDB environment variables

There are no required variables — mount the database file at the default location and the server starts.

⁠Access mode

The database is opened with DuckDB's access_mode=READ_ONLY unless told otherwise. The mode can be set either way:

DAANSE_JDBC_ACCESS_MODE replaces the read-only default, and the connection pool follows the resulting mode. An access_mode=... entry in DAANSE_JDBC_SETTINGS works the same way; DAANSE_JDBC_ACCESS_MODE wins over it. Do not set DAANSE_JDBC_READ_ONLY=true together with a different access_mode — DuckDB refuses to open the database.

⁠Session init SQL file

DAANSE_JDBC_SESSION_INIT_SQL_FILE names a SQL file (at most 1 MB, path without ; and =) mounted into the container. The part above the marker comment runs once when the database is opened, the part below it for every connection:

CREATE OR REPLACE VIEW "Fact" AS SELECT * FROM "FactData";

/* DUCKDB_CONNECTION_INIT_BELOW_MARKER */

SET search_path = 'analytics';

The file runs with the full privileges of the connection — statements that write need a read-write access mode. Pin its content with DAANSE_JDBC_SESSION_INIT_SQL_FILE_SHA256.

DAANSE_JDBC_SETTINGS configures the database, not a single connection; settings of session scope (search_path, schema, profiling) belong below the marker of the session init SQL file instead.

⁠Source

https://github.com/eclipse-daanse/org.eclipse.daanse.server/tree/main/application/pivot/duckdb

⁠The pivot container

The Daanse pivot server ships the Daanse ROLAP engine and the XMLA endpoint together with exactly one JDBC DataSource implementation, its driver and the matching SQL dialect. It is configured entirely through environment variables; unset variables keep the defaults of the underlying Daanse bundles.

The HTTP port inside the container is 8080. The XMLA endpoint is available at the path configured by DAANSE_XMLA_PATH (default /xmla).

If a required variable is missing, the configurator logs an error and the server starts without an OLAP context: the endpoint answers, but knows no catalogs and returns empty results. Check the container log first when a query comes back empty.

⁠Try it — complete demos

The repository ships self contained demos under application/pivot/common/example⁠ — each is one file embedding a seeded database and a minimal OLAP catalog, and answers an MDX query right after start:

The Kubernetes pod, abbreviated — the same YAML runs unchanged with rootless Podman and on a cluster (there, replace the hostPort with a Service):

apiVersion: v1
kind: ConfigMap
metadata:
  name: daanse-pivot-demo
data:
  init.sql: |
    CREATE TABLE "Fact" ("KEY" VARCHAR(100), "VALUE" INTEGER);
    INSERT INTO "Fact" VALUES ('A', 1), ('B', 2), ('C', 3);
  catalog.xmi: |
    ...your OLAP catalog mapping...
---
apiVersion: v1
kind: Pod
metadata:
  name: daanse-pivot-demo
spec:
  containers:
    - name: db
      image: docker.io/library/postgres:17-alpine
      env:
        - { name: POSTGRES_DB, value: demo }
        - { name: POSTGRES_USER, value: daanse }
        - { name: POSTGRES_PASSWORD, value: secret }
      volumeMounts:
        - { name: demo, mountPath: /docker-entrypoint-initdb.d/init.sql, subPath: init.sql }
    - name: pivot
      image: docker.io/eclipsedaanse/daanse-pivot-postgres:snapshot
      ports:
        - { containerPort: 8080, hostPort: 8080 }
      env:
        # containers in a pod share the network namespace
        - { name: DAANSE_JDBC_HOST, value: localhost }
        - { name: DAANSE_JDBC_DBNAME, value: demo }
        - { name: DAANSE_JDBC_USER, value: daanse }
        - { name: DAANSE_JDBC_PASSWORD, value: secret }
      volumeMounts:
        - { name: demo, mountPath: /app/catalog/catalog.xmi, subPath: catalog.xmi }
  volumes:
    - name: demo
      configMap:
        name: daanse-pivot-demo

⁠Catalog

The OLAP catalog (Daanse ROLAP mapping, .xmi) is mounted at /app/catalog. By default the file /app/catalog/catalog.xmi is loaded. If the mapping is split over several cross-referencing files, point DAANSE_CATALOG_ADDITIONAL_GLOBS at them, e.g. DAANSE_CATALOG_ADDITIONAL_GLOBS=/app/catalog/**/*.xmi.

⁠Common environment variables

⁠Authentication

By default the endpoint is anonymous: every request is served, carrying no roles — so only catalogs without access control answer. Real authentication in front of the container (reverse proxy) is always an option; the image itself offers HTTP Basic authentication against an LDAP directory.

Setting DAANSE_LDAP_URL switches it on: credentials are verified by an LDAP bind, and the caller's roles come from LDAP groups when DAANSE_LDAP_GROUP_SEARCH_BASE is set (roles are intersected with the roles the catalog declares — name the groups after the catalog's roles). Anonymous requests are still served until DAANSE_AUTH_ANONYMOUS=false, which makes the endpoint challenge every request.

⁠No LDAP at hand? Use a side container

The repository ships a complete example under application/pivot/common/example/ldap⁠: one self contained docker-compose.yml that runs an LLDAP⁠ side container next to the pivot — a lightweight LDAP server whose image comes from the LLDAP project itself. The users (admin/admin123, analyst/analyst123) and the group Administrator are plain text JSON configs embedded in the compose file and loaded by LLDAP's official bootstrap script; no extra files needed. LLDAP also serves a web UI on port 17170 to manage users and groups later.

configs:
  groups.json:
    content: |
      { "name": "Administrator" }
  admin.json:
    content: |
      { "id": "admin", "email": "[email protected]", "groups": ["lldap_admin", "Administrator"] }
  analyst.json:
    content: |
      { "id": "analyst", "email": "[email protected]", "password": "analyst123" }

services:
  lldap:
    image: lldap/lldap:stable
    environment:
      LLDAP_LDAP_BASE_DN: dc=example,dc=org
      LLDAP_LDAP_USER_PASS: admin123
      LLDAP_KEY_SEED: change-me-for-anything-real
      LLDAP_JWT_SECRET: change-me-too-at-least-32-characters-long
    ports: ["17170:17170"]   # web UI, optional

  lldap-bootstrap:           # one-shot job loading the users and groups above
    image: lldap/lldap:stable
    depends_on: [lldap]
    entrypoint: ["/bin/sh", "-c", "sleep 2 && /app/bootstrap.sh"]
    restart: on-failure
    environment:
      LLDAP_URL: http://lldap:17170
      LLDAP_ADMIN_USERNAME: admin
      LLDAP_ADMIN_PASSWORD: admin123
      DO_CLEANUP: "false"
    configs:
      - { source: groups.json, target: /bootstrap/group-configs/groups.json }
      - { source: admin.json, target: /bootstrap/user-configs/admin.json }
      - { source: analyst.json, target: /bootstrap/user-configs/analyst.json }

  pivot:
    image: eclipsedaanse/daanse-pivot-postgres:snapshot   # any daanse-pivot-<db>
    depends_on: [lldap]
    ports: ["8080:8080"]
    volumes: ["./catalog:/app/catalog:ro"]
    environment:
      # ... DAANSE_JDBC_* of your database ...
      DAANSE_LDAP_URL: ldap://lldap:3890
      DAANSE_LDAP_TRANSPORT_SECURITY: NONE
      DAANSE_LDAP_ALLOW_UNENCRYPTED: "true"
      DAANSE_LDAP_USER_DN_PATTERN: uid={0},ou=people,dc=example,dc=org
      DAANSE_LDAP_SERVICE_BIND_DN: uid=admin,ou=people,dc=example,dc=org
      DAANSE_LDAP_SERVICE_BIND_PASSWORD: admin123
      DAANSE_LDAP_GROUP_SEARCH_BASE: ou=groups,dc=example,dc=org

Then query with curl -u admin:admin123 ... — or edit the inline JSON to your own users and groups; the group names are the roles.

⁠Connection pool

The engine never talks to the DataSource directly. A single MDX query fans out to as many statements as the segment cache has threads, so all of them go through a pool. The defaults are sized for that fan-out; lower DAANSE_POOL_MAXIMUM_POOL_SIZE if the database has a stricter connection limit than the server does — Oracle refuses rather than queues once processes is reached.

⁠Mount points