Prepare an External Database
An AISIX Enterprise control plane installed with Helm can use the chart's bundled PostgreSQL instance or an external PostgreSQL database managed by your DBA team. The external database connection role only needs to own the control-plane database. It needs no SUPERUSER, CREATEROLE, or BYPASSRLS. Other database engines are not supported.
The online and offline Docker Compose packages do not support an external database. Their Compose files set the control-plane services' database URLs to the bundled postgres service and do not expose overrides in .env. Use Helm when the control plane must connect to an external PostgreSQL database.
The control-plane services share one database:
cp-api: Control-plane API server. It runs the schema migration on startup.dp-manager: Data-plane manager. It connects to the same database but does not run the control-plane application migration. Its embedded Kine backend manages its own storage schema. On a fresh database,dp-managerretries missing application-schema errors for up to about two minutes whilecp-apicompletes the migration.
cp-api also serves the dashboard and stores user accounts and sign-in sessions in the same database. The dashboard itself holds no database connection.
PostgreSQL Requirements
- PostgreSQL 14 or later.
- One empty database owned by the role the control plane connects as.
- One login role that owns that database. It can be
NOSUPERUSER,NOCREATEROLE, andNOBYPASSRLS.cp-apianddp-managerboth connect as this role. - No PostgreSQL extensions. UUIDs use the built-in
gen_random_uuid().
Why Database Ownership Is Enough
On its first start, cp-api prepares the database schema. Owning the database lets it create the public and auth schemas, tables, indexes, and functions, and apply later migrations to them. Under default PostgreSQL privileges, the database owner can create objects in public, so a standard cluster needs no separate schema grant.
AISIX Enterprise does not use PostgreSQL Row-Level Security. cp-api creates no additional database role and no Row-Level Security policies, and it does not switch roles per request, so the connection role needs no role-management or bypass privilege. Organizations are kept apart by the control plane's own queries.
Create the Database and Role
Run this once as a database administrator, using an account that can create roles and databases. The control-plane connection role itself needs no privilege beyond owning its database.
-- 1) A dedicated login role for the control plane. No special attributes.
CREATE ROLE aisix LOGIN PASSWORD 'change-me-to-a-strong-password'
NOSUPERUSER NOCREATEROLE NOBYPASSRLS;
-- 2) A dedicated database owned by that role.
CREATE DATABASE aisix_cloud OWNER aisix;
Choose your own role name, password, and database name. Ownership is what lets aisix create objects in public and add the auth schema on first boot.
The chart does not embed the password in the connection URLs it renders. Each control-plane component reads the password from a Kubernetes Secret and percent-encodes it into the URL at startup, so the password may contain characters such as +, /, and =. See Deploy the AISIX Enterprise Control Plane.
If your DBA has hardened the public schema, for example by revoking the default CREATE privilege, also grant schema access explicitly while connected to the new database:
\c aisix_cloud
GRANT USAGE, CREATE ON SCHEMA public TO aisix;
Connect the Control Plane to the Database
With Helm, set the externalDatabase.* values (and postgresql.builtin=false) as described in AISIX Enterprise Configuration. The chart builds the connection URLs for the control-plane services from those values. Both services connect as externalDatabase.username.
The control plane connects through one database URL. Leave twoDSN.enabled at its default, false. When it is true, Helm first requires twoDSN.existingSecret or a nonempty twoDSN.servingPassword that does not start with CHANGE_ME. After that check passes, the chart renders a second database URL as database.admin_url. cp-api then refuses to start in on-premises mode, and its pod log names the configuration file key or environment variable that set the URL. An environment variable overrides the configuration file. Outside the chart, set only database.url (AISIX_CLOUD_DATABASE_URL) for cp-api; cp-api refuses to start when database.admin_url (AISIX_CLOUD_ADMIN_DATABASE_URL) is also set. See Upgrade from 1.6.0 Through 1.7.0 for a deployment that still sets it.
Set sslmode=require (or stricter, such as verify-full) whenever the database is reached over a network you do not fully control.