thanglequoc/vietnamese-provinces-database: formats, schema, and release workflow

Why thanglequoc/vietnamese-provinces-database exists

Vietnamese administrative boundaries change through government resolutions. An application that stores province and ward names as fixed application constants can therefore accumulate stale identifiers, outdated names, and incorrect parent-child relationships. thanglequoc/vietnamese-provinces-database packages those administrative units as reusable database and non-SQL datasets. It covers all 34 provinces and associated districts and wards, with added postal-code and GIS data.

The intended users are engineers and developers who need structured locality information for forms, addresses, validation, analytics, search, mapping, or database seeding. The repository is not presented as a general-purpose geocoding service. It supplies reference records rather than an API for turning free-form Vietnamese addresses into coordinates. It also does not describe itself as a postal routing database, despite including postal codes.

The README says the province and ward data is based on province data exposed by the General Statistics Office of Vietnam website. Its maintainers explicitly state that they are not associated with that office or the Vietnamese government. That distinction matters for provenance. Users who require a direct contractual or technical connection to an official government service may prefer consuming the referenced API directly. Users who want local imports and several storage formats may find this repository more convenient.

The current release shown in the README is `v5.2.0`, linked to `39/2026/QH16` and `388/NQ-UBTVQH16`, with an effective date of 2026-09-20. The release table gives both issue and effect dates. This is preferable to treating every package update as a naming-only change because administrative reorganizations can alter the structure represented by the data.

Repository layout and distribution formats

The repository is organized around database and serialization targets. Its top-level directories include `postgresql/`, `mysql/`, `sqlserver/`, `oracle/`, `json/`, `mongodb/`, `redis/`, and `elasticsearch/`. It also contains `dataset-generation-scripts/`, `patch/`, and `docs/`. Based on this layout, the project treats dataset generation and database-specific packaging as separate concerns rather than asking every consumer to convert one canonical export.

The README lists a PostgreSQL/PostGIS SQL archive, MySQL and MariaDB SQL, Microsoft SQL Server SQL, Oracle SQL, JSON, MongoDB, Redis, and Elasticsearch distributions. The listed `v5.2.0` archives range from a 170.17 KB Redis archive to a 96.18 MB JSON archive. Those are archive sizes stated by the project, not statements about query performance.

The SQL-oriented format is the most explicit installation route. For PostgreSQL, MySQL and MariaDB, SQL Server, and Oracle, the README instructs users to execute `CreateTable_vn_units.sql` first and `ImportData_vn_units.sql` second. The ordering matters because the first script creates the schema and the second populates it.

The repository also adds fields beyond the source province and ward records. Documented additions include an `administrative_regions` table, an `administrative_units` table, assignment of administrative units to province and ward data, English names in full and short forms, code-name slugs, GIS data, and postal codes. The release history shows that GIS exports and postal codes arrived as separate milestones, so consumers should not infer that every historical release has the same fields or ancillary datasets.

PostgreSQL installation and first import

Start by downloading the PostgreSQL/PostGIS archive for the release you intend to use. The README lists the `v5.2.0` archive as `vn_provinces_postgresql_dataset_v5.2.0.zip`. Extract it and select the scripts from the corresponding `postgresql/` database directory inside the package.

If the target PostgreSQL instance does not already contain the required database, create it with the documented SQL statement:

CREATE DATABASE vietnamese_administrative_units;

After that command succeeds, execute `CreateTable_vn_units.sql` against the new database. This is the schema-creation step, not the data-loading step. Then execute `ImportData_vn_units.sql` in the same database context. The second script imports the dataset created by the first script.

The README does not provide a `psql` command line, connection syntax, environment variable, or PostGIS initialization command, so none is substituted here. Oracle users receive a specific exception: they may use an existing database or schema because database creation is environment-specific. For PostgreSQL deployments, confirm that PostGIS is already available before selecting the PostGIS archive. The project description identifies that format as PostgreSQL/PostGIS, but the installation section does not document the exact PostGIS setup commands.

The first useful outcome is therefore a populated target database, not an application API. Connect with the database client used by your environment, select `vietnamese_administrative_units`, and inspect the created tables before building queries against them. The README names `administrative_regions` and `administrative_units`, but the README's visible schema documentation is truncated before it gives a complete column-level contract. Avoid hard-coding a guessed schema during migration.

Administrative units, identifiers, and GIS data

The data model goes beyond a simple province lookup. Administrative units are assigned to province and ward data, and the release metadata table is distributed with the formats. This gives applications a place to represent administrative relationships, although the README excerpt does not fully describe constraints, key types, or relationship cardinalities.

English naming is another explicit addition. Provinces and wards include generated English names, with full and short forms, as well as code names or slugs. Generated names are useful for multilingual interfaces, but they should not be treated as official translations unless the consuming product documents that decision. The project describes these fields as additions made by the repository, which distinguishes them from the original source data.

The GIS add-on contains geospatial data, and the release history records GeoJSON and GIS datasets for Elasticsearch and MongoDB. Boundary consumers therefore have more options than plain tabular imports. Even so, the README does not identify a spatial reference system in the visible text, nor does it promise complete topological continuity between neighboring polygons. Geometry validity, boundary topology, and coordinate-system behavior must be verified in the GIS tools used by your application.

Postal codes were added across formats in `v5.0.0`, with a Ba Chẽ ward-code correction included in that release. This is useful for forms and reference joins, but a postal code field is not the same as a maintained street-level delivery system. The repository does not document address normalization, routing, duplicate detection, or delivery-zone coverage.

Release tracking and upgrade cost

The project has an explicit administrative-change history. The README maps government resolutions, issue dates, effect dates, and release versions. For example, `v5.2.0` tracks resolutions issued on 2026-08-04 with effect from 2026-09-20. Earlier entries cover changes effective from 2023-10-10 through 2025-07-01. This table gives adopters a concrete basis for deciding whether a release contains a structural update relevant to their deployment.

Archives are published for the latest release tag, while older versions remain available under their own version path on the CDN. That supports controlled upgrades and makes it possible to retain the dataset that matches a deployed schema. The README does not document migration SQL between releases. An upgrade can therefore require schema inspection, import into a staging database, application query review, and a rollback plan based on an older archive.

The GitHub repository is not archived, and the last push was on 2026-10-14. That date confirms recent repository activity, but it does not guarantee compatibility with every consumer. Review release notes and decree mappings before replacing production reference data. Pay particular attention when an administrative unit moves between parents or when application code stores numeric identifiers as permanent values.

The repository is licensed under the MIT License. That designation supports a generally permissive licensing model, but the consuming organization should review the actual `LICENSE` file for its required notice and attribution handling. The README does not provide legal guidance or licensing notes for derived databases, so the license file remains the controlling project document.

Limits against the official province-data source

The clearest limitation is freshness relative to government action. The repository states that data is updated according to the most recent effective decree it tracks, but publication still creates a deployment boundary between an administrative decision and adoption of a tagged archive. Applications that require immediate synchronization with every government change should monitor the official source and assess when a release appears.

The second limitation is coverage of address intelligence. Provinces, districts, wards, postal codes, and boundaries support administrative reference work, yet the project does not document street names, coordinates returned by geocoding, delivery routes, or a global administrative-equivalence model. It is the wrong tool when the core requirement is turn-by-turn navigation or continuous postal delivery validation.

A real alternative is the General Statistics Office province-data API referenced by the README. Direct API consumption keeps the consumer closer to the source and may fit systems that already treat official endpoints as an operational dependency. This repository differs by distributing ready-to-import archives for multiple database systems, adding GIS and postal-code assets, and including English names, short names, slugs, metadata, and administrative-unit tables. The tradeoff is an intermediary snapshot with an update and upgrade lifecycle of its own.

Editorial conclusion

Adopt this dataset when an application needs a packaged, frequently revised Vietnamese administrative-unit dataset rather than a live government integration. Do not assume it is a complete routing engine or a substitute for legal authority on administrative boundaries. Verify the release effective date, selected database schema, imported record counts, and compatibility of GIS data before production use.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. thanglequoc/vietnamese-provinces-database on GitHub