Docker image v3.2.2: pg-upgrade-null-tenant-id.sql missing from container, causing startup crash

[Ayanami-Shinji]

Describe the bug

The Nacos 3.2.2 Docker image references META-INF/pg-upgrade-null-tenant-id.sql in the startup validation (added in #15150), but the file is not packaged in the container. Users upgrading from 3.2.1 to 3.2.2 with PostgreSQL experience a startup crash:

PostgreSQL schema is incompatible for table `config_info`: column `tenant_id` must be NOT NULL DEFAULT `"`. Apply the migration script META-INF/pg-upgrade-null-tenant-id.sql before starting Nacos.

The migration SQL file exists in the GitHub source at plugin-default-impl/nacos-default-datasource-plugin/nacos-datasource-plugin-postgresql/src/main/resources/META-INF/pg-upgrade-null-tenant-id.sql (develop branch), but a thorough find / -name "*.sql" inside the official Docker container returns zero results — there are no SQL files at all in the image.

Additionally, the release notes for 3.2.2 make no mention of this required manual migration step.

Expected behavior

One of the following:

1. The migration SQL is included in the Docker image so users can extract and apply it, OR
2. The migration is applied automatically during startup, OR
3. At minimum, the release notes clearly document this manual step with the SQL content

Actually behavior

• Container crashes with a stack trace pointing to a non-existent file
• docker exec + find / -name "*.sql" returns nothing
• Zero META-INF directories exist in the container
• Release notes say nothing about the migration requirement

How to Reproduce

1. Run Nacos 3.2.1 with PostgreSQL, having existing config data
2. Stop and upgrade to nacos/nacos-server:v3.2.2
3. Container exits with IllegalStateException: PostgreSQL schema is incompatible
4. find / -name "pg-upgrade-null-tenant-id.sql" inside the image returns nothing

Workaround

The SQL must be applied manually before upgrading:

ALTER TABLE config_info ALTER COLUMN tenant_id SET DEFAULT '"'"', UPDATE config_info SET tenant_id = '"'"' WHERE tenant_id IS NULL, ALTER COLUMN tenant_id SET NOT NULL;
-- (repeat for config_info_gray, config_tags_relation, his_config_info)

The original SQL is at: https://github.com/alibaba/nacos/blob/develop/plugin-default-impl/nacos-default-datasource-plugin/nacos-datasource-plugin-postgresql/src/main/resources/META-INF/pg-upgrade-null-tenant-id.sql

Desktop

• OS: Ubuntu 24.04 (amd64)
• Version: nacos-server 3.2.2 (Docker nacos/nacos-server:v3.2.2)
• Module: config (PostgreSQL datasource)
• SDK: N/A (server-side)

Additional context

See PR #15150 which introduced this migration. The reviewer explicitly requested the migration SQL be provided for existing deployments, and it was added to source — it just did not make it into the Docker build artifact.

[KomachiSion]

How to solve it?

And the not docker 3.2.2 release, like nacos-setup or install by munual whether contain this problem?

[Ayanami-Shinji]

Additional finding: fresh install (not upgrade) also broken

Spent today deploying a new UAT environment against an empty PostgreSQL database. Same config_info namespace migrate pre check failed crash, but for a different reason than the upgrade path:

The namespaceMigratePreCheck at ConfigMigrateService.java:864 runs BEFORE the schema initialization (table creation). On a freshly created database the config_info table does not exist yet, so the configInfoConflictCount SQL query fails. The exception is caught by the retry loop but the log output is filtered by the default logback level, making it look like a conflict check failure when it's actually a missing table error.

Confirmed by pre-creating the schema before starting Nacos — works fine once tables exist.

So PR #15150's migration logic breaks both paths:

1. Upgrade (3.2.1 → 3.2.2): missing pg-upgrade-null-tenant-id.sql in the container image (original report)
2. Fresh install: migration pre-check runs before schema init, crashes because tables don't exist yet (new finding)

Suggested fix order:

1. Move schema initialization before the migration pre-check
2. Bundle the migration SQL in the Docker image

[Ayanami-Shinji]

@KomachiSion

Workaround for Docker fresh install:

Pre-create the PostgreSQL schema before starting Nacos:

1. Dump schema from an existing healthy 3.2.2 instance or from the source: pg-schema.sql in the plugin resources
2. Apply the migration SQL: https://github.com/alibaba/nacos/blob/develop/plugin-default-impl/nacos-default-datasource-plugin/nacos-datasource-plugin-postgresql/src/main/resources/META-INF/pg-upgrade-null-tenant-id.sql
3. Grant table permissions to the nacos DB user
4. Then start the container

For non-Docker releases:

Likely affected too. The root cause is in ConfigMigrateService.java — the migrate() method (annotated with @PostConstruct) runs before the schema initialization DDL, so config_info and related tables don't exist yet when the pre-check queries them. This is a startup ordering bug in the Java code, not Docker-specific. That said, the pg-upgrade-null-tenant-id.sql file is present in the source distribution package (it's committed to the repo), just missing from the Docker image build artifact. So the upgrade path should be fixable for non-Docker users by manually running that SQL.

[KomachiSion]

Additional finding: fresh install (not upgrade) also broken

Spent today deploying a new UAT environment against an empty PostgreSQL database. Same config_info namespace migrate pre check failed crash, but for a different reason than the upgrade path:

The namespaceMigratePreCheck at ConfigMigrateService.java:864 runs BEFORE the schema initialization (table creation). On a freshly created database the config_info table does not exist yet, so the configInfoConflictCount SQL query fails. The exception is caught by the retry loop but the log output is filtered by the default logback level, making it look like a conflict check failure when it's actually a missing table error.

Confirmed by pre-creating the schema before starting Nacos — works fine once tables exist.

So PR #15150's migration logic breaks both paths:

1. Upgrade (3.2.1 → 3.2.2): missing pg-upgrade-null-tenant-id.sql in the container image (original report)
2. Fresh install: migration pre-check runs before schema init, crashes because tables don't exist yet (new finding)

Suggested fix order:

1. Move schema initialization before the migration pre-check
2. Bundle the migration SQL in the Docker image

I am puzzled regarding the startup sequence. Nacos itself does not possess the capability to automatically create database tables; typically, operations or deployment personnel are responsible for pre-creating the PostgreSQL database tables before configuring the PostgreSQL JDBC settings within Nacos.

Therefore, the scenario where the config_info table is missing should not occur.

[Ayanami-Shinji]

@KomachiSion you're right — I re-checked and Nacos does not auto-create tables. spring.sql.init.mode=never in nacos-server.properties:20 explicitly disables Spring Boot's schema auto-init, and the deployment docs instruct users to manually run mysql-schema.sql before starting. The "fresh install" crash I reported was a misdiagnosis — starting against an empty database without pre-creating the schema is expected to fail. Apologies for the noise.

However, the upgrade path bug stands, and it's independent of whether tables are pre-created:

The pg-upgrade-null-tenant-id.sql migration lives inside the PostgreSQL datasource plugin JAR under META-INF/. When validatePostgresqlTenantSchema() detects incompatible tenant_id columns, it throws an error pointing users to a path that doesn't exist on the container filesystem. find / -name "*.sql" returns nothing because find doesn't search inside JARs — the file is there, but inaccessible to anyone who doesn't know to jar xf the right plugin.

Suggestions:

1. Copy pg-upgrade-null-tenant-id.sql into /home/nacos/conf/ in the Docker image (alongside the schema SQLs), so users can find and apply it
2. Or print the actual SQL content in the error message instead of a META-INF path that users can't resolve

[KomachiSion]

OK, it should be cp when nacos build. like other schema.sql.

Welcome submit PR to supported.