Environment:Apache Dolphinscheduler Database Backend

Knowledge Sources	Apache DolphinScheduler MySQL PostgreSQL
Domains	Infrastructure, Data_Integration
Last Updated	2026-02-10 10:00 GMT

Overview

PostgreSQL 15.2+ (default) or MySQL 8.0+ relational database backend with HikariCP connection pooling for metadata storage and Quartz job scheduling.

Description

DolphinScheduler requires a relational database for storing workflow definitions, task instances, datasource configurations, user accounts, and Quartz scheduler state. PostgreSQL is the default database (driver: `org.postgresql.Driver`, version 42.4.4). MySQL is the primary alternative (driver: `com.mysql.cj.jdbc.Driver`, version 8.0.33). The database schema includes Quartz tables (prefixed with `QRTZ_`) using InnoDB engine with utf8 charset. HikariCP manages the internal connection pool with a validation query of `select 1`.

Usage

Use this environment for all DolphinScheduler deployments. The database is required for API Server, Master Server, and Worker Server. Schema initialization must be run before first startup. Both PostgreSQL and MySQL are supported via Spring profiles.

System Requirements

Category	Requirement	Notes
Database	PostgreSQL 15.2+ or MySQL 8.0.33+	H2 available for testing only
Disk	10GB+ SSD recommended	Grows with workflow history
Charset	utf8 (MySQL) / UTF-8 (PostgreSQL)	MySQL uses utf8_bin collation
Engine	InnoDB (MySQL)	Required for transactional integrity

Dependencies

Database Drivers (managed by Maven BOM)

`postgresql` = 42.4.4 (PostgreSQL JDBC driver)
`mysql-connector-java` = 8.0.33 (MySQL JDBC driver)
`h2` = 2.2.220 (test only)
`druid` = 1.2.20 (SQL parsing)
`hikaricp` (bundled with Spring Boot 2.7.x)

Additional Database Drivers (datasource plugins)

`hive-jdbc` = 2.3.9
`kyuubi-jdbc` = 1.7.0
`clickhouse-jdbc` = 0.4.6
`mssql-jdbc` = 11.2.1.jre8
`ojdbc8` = 21.5.0.0
`DmJdbcDriver18` = 8.1.2.79

Credentials

The following properties must be configured in `application.yaml`:

`spring.datasource.url`: JDBC connection URL
`spring.datasource.username`: Database username (default: `root`)
`spring.datasource.password`: Database password (default: `root`)
`spring.datasource.driver-class-name`: JDBC driver class

Quick Install

# PostgreSQL via Docker (recommended)
docker run -d --name dolphinscheduler-postgresql \
  -p 5432:5432 \
  -e POSTGRESQL_USERNAME=root \
  -e POSTGRESQL_PASSWORD=root \
  -e POSTGRESQL_DATABASE=dolphinscheduler \
  bitnami/postgresql:15.2.0

# MySQL via Docker (alternative)
docker run -d --name dolphinscheduler-mysql \
  -p 3306:3306 \
  -e MYSQL_ROOT_PASSWORD=123456 \
  --default-authentication-plugin=mysql_native_password \
  mysql:8.0.33

# Initialize schema (PostgreSQL)
psql -h 127.0.0.1 -U root -d dolphinscheduler -f dolphinscheduler-dao/src/main/resources/sql/dolphinscheduler_postgresql.sql

# Initialize schema (MySQL)
mysql -h 127.0.0.1 -u root -p123456 dolphinscheduler < dolphinscheduler-dao/src/main/resources/sql/dolphinscheduler_mysql.sql

Code Evidence

Default PostgreSQL configuration from `dolphinscheduler-api/src/main/resources/application.yaml:48-54`:

datasource:
  driver-class-name: org.postgresql.Driver
  url: jdbc:postgresql://127.0.0.1:5432/dolphinscheduler
  username: root
  password: root
  hikari:
    connection-test-query: select 1
    pool-name: DolphinScheduler

MySQL schema definition from `dolphinscheduler-dao/src/main/resources/sql/dolphinscheduler_mysql.sql:21-36`:

CREATE TABLE `QRTZ_JOB_DETAILS` (
    `SCHED_NAME` varchar(120) NOT NULL,
    `JOB_NAME` varchar(200) NOT NULL,
    ...
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE = utf8_bin;

Docker Compose PostgreSQL from `deploy/docker/docker-compose.yml:20-30`:

dolphinscheduler-postgresql:
  image: bitnami/postgresql:15.2.0
  environment:
    POSTGRESQL_USERNAME: root
    POSTGRESQL_PASSWORD: root
    POSTGRESQL_DATABASE: dolphinscheduler

Common Errors

Error Message	Cause	Solution
`Access denied for user 'root'@'localhost'`	Wrong database credentials	Check `spring.datasource.username` and `password`
`Table 'QRTZ_JOB_DETAILS' doesn't exist`	Schema not initialized	Run the SQL initialization script for your database
`Communications link failure`	Database server unreachable	Verify database host/port and network connectivity
`Unknown database 'dolphinscheduler'`	Database not created	Create the database first: `CREATE DATABASE dolphinscheduler`

Compatibility Notes

PostgreSQL: Default and recommended database. Version 15.2+ tested in Docker Compose.
MySQL: Requires `mysql_native_password` authentication plugin (not `caching_sha2_password`). Version 8.0.33+ tested.
H2: Available for unit testing only. Not suitable for production.
Quartz Tables: Must use `quartz.job-store-type: jdbc` with `initialize-schema: never` (schema managed manually).

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment