Running Dify metadata on MySQL or OceanBase when your standard is MySQL-compatible
If your database standard requires MySQL compatibility, Dify can use MySQL or OceanBase as its metadata database, but PostgreSQL remains the default and the option the rest of the stack is written around. The Dify environment variable reference lists PostgreSQL (default), MySQL and OceanBase as the supported metadata database choices, selected through the database type setting in the environment file. TiDB appears in the topic name, but the same reference does not list it, so confirm TiDB support against the current Dify docs before you treat it as supported or plan a build around it. Check the Dify environment variables reference for the exact DB_TYPE values and connection keys in the release you plan to run.
The metadata database holds the platform's structured records: accounts and workspaces, app definitions and workflow configuration, knowledge base and document records, model provider settings, and the job state that background workers rely on. Uploaded files and vector embeddings are stored elsewhere (object storage and the vector store), so the database choice affects the control plane, not the bulk of your document data. Because Dify's bundled stack, documentation and most operator runbooks assume PostgreSQL, ask your Dify vendor or implementation partner to confirm which database features, migrations and upgrade steps they have tested against MySQL or OceanBase for your target version.
Before you commit, decide who owns the database. If your DBA team already runs a MySQL-compatible service with backups, failover and monitoring, a supported Dify connection can reuse those controls, and that is the main reason to choose this path. The cost is that you take on the compatibility risk yourself: test schema creation, upgrade migrations and the background job queue on a staging copy before each Dify minor release, which arrive roughly monthly according to the Dify releases page. Ask for the database versions and character set and collation settings Dify requires, the connection pool limits you should set, and the restore procedure you must test. Keep a current backup before every upgrade, as the Dify Docker Compose guide recommends, and confirm that your backup tool restores a Dify instance end to end.
Which metadata database fits your standard
This table compares PostgreSQL, MySQL, OceanBase and TiDB as the Dify metadata database across support status, configuration value, operational fit, tooling and team skills. Read it as a checklist to confirm with Dify and your database vendor before you commit, since only PostgreSQL is the default and the others need their own validation.
| Criterion | PostgreSQL | MySQL | OceanBase | TiDB |
|---|---|---|---|---|
| Support status | Default metadata database in Dify | Listed as a supported metadata database option | Listed as a supported metadata database option | Not listed in the supplied Dify env reference; confirm before planning |
| DB_TYPE value | postgresql (default) | Set per the env reference; confirm exact value | Set per the env reference; confirm exact value | Do not assume a value; confirm with Dify docs |
| Default port and tuning | Covered by default Compose layout | Confirm port and tuning with Dify docs | Confirm port and tuning with Dify docs | Confirm port and tuning with Dify docs and TiDB |
| Operational fit | Matches the bundled db_postgres container and most upgrade paths | Fits teams already running MySQL backup and failover practice | Fits teams with an existing OceanBase cluster and support contract | Depends on whether TiDB is approved in your estate |
| Tooling and backups | Dify documents PostgreSQL alongside the Compose stack | Use your existing MySQL backup tooling, tested for Dify schema | Use vendor tooling, tested for Dify schema | Use vendor tooling, tested for Dify schema |
| Team skills needed | PostgreSQL administration, connection pool and TLS | MySQL administration and version checks | OceanBase administration and vendor support | TiDB administration and vendor support |
| Upgrade and migration risk | Lowest documented path in Dify deployment docs | Re-test every Dify upgrade against your MySQL version | Re-test every Dify upgrade against your OceanBase version | Re-test every Dify upgrade against your TiDB version |
What changes in ports, connection settings and tuning
When DB_TYPE moves from the default PostgreSQL to MySQL or OceanBase, the connection block of the environment file changes as a set. The host, port, username, password and database name keys all point at your MySQL-compatible endpoint instead of the bundled PostgreSQL container, which stops being the metadata store once you switch. Do not assume the Compose service name or the default port carries over. Confirm the exact key names, the accepted DB_TYPE values and the default ports for each database in the Dify environment variables reference, and check the Compose docs for any service you still start that depends on the old database. After every upgrade, compare your file against .env.example because new variables can appear.
Connection capacity is the first item to validate. Dify runs several services that open database connections (the API, the worker and the plugin daemon), so the total number of connections your endpoint must accept grows with replicas and worker concurrency. Ask the database owner for the server's maximum connection setting and any proxy or pool limit in front of it, then compare that with the concurrency you plan. Confirm how the chosen Dify version and driver handle pool sizing before you set any value, and do not copy numbers from a PostgreSQL tuning guide.
Character set and collation need a deliberate check before the first migration run. Dify stores multilingual prompts, document text and workflow content, so the database, tables and connection must agree on a Unicode-capable character set and a collation your team has tested, and the utf8mb4 family is the usual place to start for MySQL-compatible engines. Verify that the server's default settings do not silently truncate or re-encode text, and test with a non-Latin document and a long prompt. Document the result, because changing collation later is slower than setting it correctly at install.
How to set up Dify on MySQL or OceanBase
This sequence takes a self-hosted Dify from a Compose stack with the default PostgreSQL metadata database to one that stores metadata in a MySQL-compatible database. Each step ends with a check, so you can confirm the database is in use before you test apps and knowledge bases.
Confirm the target Dify version
The platform team selects the Dify release to deploy and reads its upgrade guide on the GitHub releases page before changing anything. Check the current minor versions listed there, since 1.17.1 was the latest release in the supplied facts and minor releases arrive roughly monthly. Record the version tag and the matching .env.example, because the variables for the metadata database can change between releases. Done when the version, the upgrade notes and the environment reference you will follow all refer to the same release.
Provision the MySQL-compatible database
The database team creates a dedicated schema and service account for Dify on MySQL, OceanBase or TiDB, following the character set, collation and SQL mode that the Dify environment reference and your database vendor document for that engine. Confirm with the vendor that the version you run supports the features Dify's migrations use, and ask whether TiDB or your OceanBase tenant is covered by the MySQL setting in the environment reference. Grant the account rights to create and alter tables. Done when a client connection from the Dify host succeeds with that account and an empty schema is visible.
Set DB_TYPE and connection variables
The platform engineer edits the production env file and sets DB_TYPE to the value the environment variable reference lists for MySQL or OceanBase, then sets the host, port, database name, user and password variables that the reference defines for that database. Store the password in your secrets tooling and reference it from the env file rather than pasting it into shared documents. Keep the PostgreSQL variables out of the file so the setup is not split across two engines. Done when the env file contains one database type and every connection value matches the account created in the previous step.
Decide what remains on the bundled PostgreSQL
The platform engineer checks the Compose file for the bundled PostgreSQL container and the services that depend on it, including the plugin daemon connection described in the Dify docs. Confirm with the Dify documentation for your release whether the bundled PostgreSQL container still starts, and whether any component still expects PostgreSQL. Decide whether to remove the container or keep it running for components that require it, and document that choice in the runbook. Done when a written list shows which services use the MySQL-compatible database and which, if any, still use PostgreSQL.
Start the stack and read startup logs
The platform engineer starts the Docker Compose stack with the pinned version, using a Compose release that meets the 2.24.0 minimum in the Dify self-hosting docs. Watch the API and worker logs during startup for connection errors, authentication failures or migration messages. If the api container restarts, read the database error before changing any other variable. Done when all core containers report healthy and the logs show that the API connected to the database without repeated errors.
Verify migrations and administrator login
The platform engineer confirms that the schema migrations completed by checking the API logs and the tables in the target schema, and then opens the Dify console to create the first administrator account. Log out and sign in again to confirm that sessions work with the new database. Check that the SECRET_KEY was set before first start, because changing it later logs out all users. Done when the administrator can sign in and the tables that Dify created are visible in the MySQL-compatible schema.
Create and run a test app
A builder creates a simple test workflow or chatbot app in a workspace, saves it, publishes it and runs a test conversation through the preview. This step confirms that application metadata, prompts and run records are written to and read from the new database. Use a model provider that your team has approved for testing, and do not use production data. Done when the app saves, reloads with the same configuration after a page refresh and returns a test response.
Upload a document to a knowledge base
A builder creates a knowledge base, uploads a small test document and waits for indexing to finish. This check covers the metadata writes for documents and segments, the file storage configuration and the vector store, so a failure here may come from a component other than the database. Confirm that the document appears with its indexing status and that a retrieval test returns the expected passage. Done when the document reaches a completed status and retrieval returns text from it.
Trade-offs against the PostgreSQL default
Choosing MySQL, TiDB or OceanBase for Dify's metadata database trades alignment with your existing database estate against the default path that Dify's documentation and release testing cover most closely. The cards below set out the decisions that follow from that trade, and what to confirm with Dify before you commit.
Fit with your DBA estate
If your organization already runs MySQL-compatible databases with tested backup, restore and monitoring, a matching engine can reuse those runbooks, access reviews and on-call skills. Check whether your DBA team will own the Dify schema, who approves schema changes during upgrades, and whether your backup tool can capture a consistent snapshot of the metadata database alongside the file storage Dify uses.
Less documented ground
The environment variable reference names MySQL and OceanBase as supported metadata database options, but most deployment guidance, examples and troubleshooting threads assume PostgreSQL. Expect fewer worked examples for ports, tuning and failure modes. Ask Dify which MySQL-compatible engines and versions it tests against, and whether a documented configuration exists for your target.
Upgrade testing burden
Dify ships minor releases roughly monthly, and each upgrade follows the guide for the target version with a backup beforehand. On a non-default database, your team carries the verification of migrations, new environment variables and any database-specific behavior that the vendor's default path does not exercise. Budget staging runs for every upgrade, and agree with Dify who validates which release on which database engine.
Exposure to unsupported paths
Features that Dify adds later may be built and tested against PostgreSQL first. A feature that works on the default may fail or need a workaround on another engine, and you may only learn this after an upgrade. Before adopting a feature such as a new plugin or workflow capability, ask whether it is covered for your database type and record the answer in your change log.
Less-tested configuration risk
A non-default metadata database combined with an external cache, object storage and vector store is a combination with fewer public reports. Failures may be harder to diagnose because community answers will not match your stack. Plan a reference environment that mirrors production, define who you will ask first when something breaks, and confirm the support route that applies to your license edition.
Support and contract scope
The Community edition is free and limited to a single workspace, while the Enterprise edition is custom priced and includes professional support. Confirm in writing whether support covers your chosen metadata database, which versions it covers, and how upgrade assistance is handled. Where the vendor's support does not cover your database, the cost of diagnosing those issues stays with your team or your implementation partner.
Security and operations to plan for the metadata database
Moving Dify's metadata to MySQL, TiDB or OceanBase changes where sensitive data lives and who can reach it. The cards below cover the decisions that carry over from the default PostgreSQL setup and the checks to run before go-live.
Keep SECRET_KEY stable across the move
The environment reference says SECRET_KEY signs session cookies and JWTs and encrypts OAuth credentials, and that changing it after deployment logs out all users. Reuse the exact value from your current environment file when you cut over to the new database, and store it in your secrets manager rather than in a shared file. Confirm with a test login and an OAuth connection check after the switch, because a changed key can break stored credentials as well as sessions.
Place the database on a private network
The API and worker containers need a route to the database, but nothing else should. Put MySQL, TiDB or OceanBase on a private subnet or internal network segment reachable only from the Dify hosts, and confirm that the database port is not published on a public address. For TiDB or OceanBase, also check which internal components (placement, storage or proxy nodes) are reachable from outside the cluster network.
Encrypt database connections with TLS
Credentials and metadata such as app configuration, model settings and workspace records cross the network on every query. Enable TLS on the database listener and confirm which certificate authority Dify's containers trust, so that certificate verification works rather than being disabled. Ask your database vendor or DBA which TLS modes are supported by the driver version bundled with your Dify release.
Use a least-privilege database account
Create a dedicated account for Dify that owns only the metadata schema, rather than reusing an administrator login. Limit it to the privileges Dify needs to run its migrations and normal operations, and keep migration rights separate from runtime rights if your change process requires it. Record who holds the account and rotate its password on a schedule you can prove.
Define backup and restore ownership
Dify's Docker Compose docs recommend a backup before every upgrade, and an external database moves that duty to your team. Decide who owns database backups, how often they run, where they are stored, and how long they are kept. Restore a copy into a test environment and check that the app list and knowledge base records load, because a backup that has never been restored is not yet proven.
Monitor connections, errors and growth
Track connection counts, slow queries, replication or cluster health, storage growth and failed logins on the database. Alert on connection exhaustion and on errors from the api and worker containers, since both appear first as failed requests in the console. Review these signals after each Dify minor release, which arrive roughly monthly according to the release history.
Questions teams ask before choosing MySQL or OceanBase for Dify
Should we standardize on MySQL or keep Dify's default PostgreSQL?
Standardize on MySQL only if your organization already runs MySQL-compatible databases well and has the people to operate them, because that is the main driver. PostgreSQL is the default metadata database in Dify, so it has the most documented paths, the most community experience and the fewest surprises at upgrade time. The environment variable reference lists PostgreSQL as the default, with MySQL and OceanBase as alternatives set through DB_TYPE. A shared database standard, existing backup tooling and staff skills are legitimate reasons to choose the alternative. Without those drivers, the default is usually the lower-risk choice.
How much extra effort does a non-default metadata database add?
The effort comes from verification rather than from writing configuration. You set DB_TYPE, point the connection variables at the new engine, adjust ports and tuning, and then test every workflow that touches metadata, including app publishing, knowledge base operations, user administration and background jobs. Each alternative engine also needs its own sizing, connection pool limits and backup routine. Expect the most work in the first build and in each validation cycle after a Dify upgrade, since the team must confirm the combination still works on the new release.
What does the work need from our internal DBA team?
Your DBAs own the database platform: provisioning, high availability design, TLS settings, account and privilege model, monitoring, backup and restore testing, and capacity planning. Dify's own administrators handle the application side, including the connection variables and the health of the services that read and write metadata. Agree on this split in writing before the build starts. Ask the DBA team to confirm how they will test restores, since a backup that has never been restored does not count as a recovery plan.
Can our team set up a non-default metadata database alone?
A team with Docker, database and Linux experience can often complete a test deployment alone, using the Docker Compose documentation and the environment variable reference. Production readiness is a different test. It requires a documented upgrade path, verified restores, tuned connection limits and a validation suite that exercises Dify features after each change. Teams without that operating experience usually find the gaps during the first upgrade, when a schema or driver difference appears in production. An outside partner can plan and build that validation work under a fixed scope, while your team keeps ownership of day-two operations.
How long does a MySQL or OceanBase metadata database project take?
Duration depends on how many environments you run, how much of your existing database platform you can reuse, and how thoroughly you need to test. The largest variables are the number of Dify features your teams use, the number of integrations that depend on the database, and whether you are also moving file storage or the vector store at the same time. No duration is given here because no researched figure supports one. Ask any implementation partner for a timeline tied to a written list of environments, test cases and handover deliverables.
How do Dify upgrades change when the metadata database is not PostgreSQL?
Upgrades follow the same process, but each one needs an extra compatibility check against your chosen engine. Dify ships minor releases roughly monthly, so the schedule for validation work is continuous rather than occasional. Before every upgrade, take a backup, read the upgrade guide for the target version, and compare .env.example for new variables. Then run your validation suite against the new release in a non-production environment. Ask whether the database engine you chose is covered by the target release's documentation, because support differences between engines can change the upgrade plan.
What does a partner quote for this work depend on?
A quote follows from a written scope, so it depends on the decisions that change the work. These include the target engine and version, the number of environments, the hosting model for the database, the backup and restore requirements, the Dify features in use, and whether the work includes migrating existing data. Compliance evidence needs, such as documented change control and tested recovery, also add effort. Ask for line items for design, build, validation, documentation, handover and any retained support, so you can compare options against your own team's effort.
How DeployOpen scopes a Dify metadata database change
DeployOpen plans, implements, tests, documents and supports self-hosted open-source platforms inside your own infrastructure, so a change to Dify's metadata database is handled as a bounded engagement. We start from your standard database requirements and the Dify version you run, then agree the work in writing before any change is made.
How we scope
- Confirm which MySQL-compatible engine your standard allows: MySQL, TiDB or OceanBase, and its exact version.
- Check the Dify release you run against the DB_TYPE values and database setup its docs describe.
- Record the migration path, downtime tolerance, backup and rollback requirements in the written scope.
How we build
- Prepare the target database, accounts, ports and tuning, then point a staging Dify instance at it.
- Run a full test of workflows, knowledge base indexing, file storage and scheduled jobs against the new metadata store.
- Verify secrets such as SECRET_KEY are unchanged so existing users and encrypted credentials keep working.
How we hand over
- Deliver the configuration, environment file changes and a tested backup and restore runbook for the chosen engine.
- Document the known differences from the default PostgreSQL setup, including which features you must retest after upgrades.
- Walk your operators through monitoring, connection limits and the upgrade checklist for future Dify releases.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Ask us to confirm the upgrade impact of each new Dify minor release on your chosen metadata database before you apply it.
