Open-Source Databases · thanglequoc

vietnamese-provinces-database

A comprehensive SQL and GIS dataset covering Vietnamese administrative divisions (34 provinces, districts, wards, and regions). Provides multi-database support (PostgreSQL, MySQL, SQL Server, Oracle) with schema, data import scripts, and geospatial boundaries synchronized to official Vietnamese government decrees.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/thanglequoc/vietnamese-provinces-database

1.7k

GitHub stars

397

Forks

PLpgSQL

Primary language

MIT

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	thanglequoc/vietnamese-provinces-database
Owner	thanglequoc
Primary language	PLpgSQL
License	MIT — OSI-approved
Stars	1.7k
Forks	397
Open issues	6
Latest release	v4.0.0 (2026-06-21)
Last updated	2026-07-05
Source	https://github.com/thanglequoc/vietnamese-provinces-database

What vietnamese-provinces-database is

PLpgSQL-based administrative reference database with normalized schema (administrative_regions, administrative_units, provinces, wards tables), English/Vietnamese naming, code slugs, and GIS dataset add-on (v4.0.0). Tracks compliance with Vietnamese government decrees via versioned releases and includes multi-DBMS deployment scripts.

Quickstart

Get the vietnamese-provinces-database source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/thanglequoc/vietnamese-provinces-database.git2cd vietnamese-provinces-database3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

E-commerce and Logistics Address Systems

Localization, address validation, and shipment routing requiring accurate Vietnamese provincial and ward hierarchies. Schema directly supports hierarchical location lookups and code-based filtering.

GIS and Regional Analytics Applications

Geospatial boundary mapping, regional reporting, and administrative region analysis. GIS dataset (v4.0.0+) enables mapping and spatial queries across administrative units.

Government and Regulatory Compliance Systems

Systems requiring up-to-date Vietnamese administrative structure aligned with official decrees. Maintains decree version history; useful for audit trails and historical jurisdiction tracking.

Implementation considerations

Select appropriate SQL script (PostgreSQL, MySQL, SQL Server, or Oracle) from corresponding directory before database creation. Execution order matters: CreateTable first, then ImportData.
Normalize application queries to use code-based lookups (code_name, code_name_en, administrative_unit_id) for stability across dataset updates and to filter by administrative tier.
Track decree versions and release notes; plan for periodic data refreshes when new decrees take effect. v3.1.0+ reflects 30/2026/QH16 decree (effective 2026-04-30).
GIS dataset (v4.0.0+) requires compatible spatial query libraries (PostGIS for PostgreSQL); validate vector/raster format compatibility with application stack.
Mirror or freeze release version in production; do not auto-pull latest if regulatory alignment to specific decree date is contractual.

When to avoid it — and what to weigh

Real-time Dynamic Administrative Changes — Data updates are release-driven (6 monthly cycles in 2024–2026) and aligned to government decree effective dates. Not suitable for sub-decree-cycle real-time updates.
Offline-First Mobile or Low-Bandwidth Use — Database approach requires SQL engine; no lightweight JSON/CSV export files documented in README. Consider CSV alternatives if offline sync is critical.
Cross-Border or Multi-Country Administrative Systems — Data is Vietnam-specific. Projects requiring multi-nation administrative hierarchies should not rely solely on this dataset.
Production Use Without Vendor Independence Review — Author explicitly disclaims affiliation with Vietnamese government or statistics office. Critical systems should independently verify decree compliance and data accuracy.

License & commercial use

Licensed under MIT License. Permissive OSI-approved license allowing use, modification, and distribution in proprietary and open-source contexts, with no warranty or liability. Include license text in distribution.

MIT License permits commercial use without royalty or attribution requirement. However, the dataset itself derives from Vietnamese government API and decree data; verify your jurisdiction's policy on repackaging government-sourced data for commercial product sale. The author disclaims affiliation with government, so independent legal review is recommended if reselling as primary product.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Adequate
License clarity	Clear
Deployment complexity	Moderate
DEV.co fit	Good
Assessment confidence	High

Security considerations

Dataset is read-only reference data; primary security concern is unauthorized modification of administrative hierarchy in production (prevent accidental or malicious schema updates). Use role-based database access control (read-only roles for application). No mention of data encryption, audit logging, or compliance certifications. Validate that decree-sourced data does not introduce geopolitical or territorial disputes in regulated jurisdictions.

Alternatives to consider

OpenStreetMap (OSM) + Nominatim

Free, global, community-maintained administrative boundaries. Lack Vietnamese-government decree synchronization but offer GIS coverage. Better for general geolocation; weaker for regulatory compliance.

Google Maps Geocoding API + Address Validation API

Managed, real-time, high availability. Charges per request; no local database deployment. Suitable for SaaS e-commerce; unsuitable for offline or cost-sensitive applications.

Geonames.org Vietnamese Data

Free, public-domain administrative reference. Lower accuracy for Vietnamese ward-level hierarchies and no decree versioning. Simpler CSV format for lightweight integrations.

Software development agency

Build on vietnamese-provinces-database with DEV.co software developers

Integrate a government-decree-synchronized, multi-database administrative hierarchy into your e-commerce, logistics, or GIS application. MIT licensed, active maintenance, comprehensive schema.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

wilayah province-city-china sql-paises-estados-cidades

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Databases Web App Development API Development Custom Software & Database Talk to DEV.co

vietnamese-provinces-database FAQ

Is the data current?

Yes, as of v4.0.0 (2026-06-21). Data tracks decree 30/2026/QH16 (effective 2026-04-30). Check release notes for which decree version your application requires.

Can I use this in a commercial product?

MIT License permits commercial use. However, the underlying data is sourced from Vietnamese government API and decrees; verify local regulations on repackaging government data for resale. Independent legal review recommended.

Do I need PostGIS for the GIS dataset?

Only if using PostgreSQL and spatial queries (v4.0.0+). MySQL, SQL Server, and Oracle installations may not require spatial extensions depending on use case; check documentation or contact maintainer for format details.

How do I handle a new government decree?

Wait for a new release or manually patch the SQL scripts. The maintainer typically releases updates 1–6 months after decree issuance. For urgent updates, fork the repository or contact the maintainer.

Custom software development services

Adopting vietnamese-provinces-database is usually one piece of a larger software development effort. As a software development agency, DEV.co provides software development services and web development expertise — pairing senior software developers and web developers with your team to design, build, and operate open-source databases software in production.

Deploy Vietnamese Admin Data Today

Integrate a government-decree-synchronized, multi-database administrative hierarchy into your e-commerce, logistics, or GIS application. MIT licensed, active maintenance, comprehensive schema.

Talk to DEV.co Schedule a Consultation