Merge pull request #80 from maxmind/greg/eng-3475-mmdbverify-is-released

horgh · web-flow · commit 1d7a890f3208 · 2025-11-14T15:20:03.000-08:00
Prepare for release
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  goreleaser:
+    name: Release with GoReleaser
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: recursive
+          persist-credentials: false
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.25'
+          cache: false
+
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@e435ccd777264be153ace6237001ef4d979d3a7a # 6.4.0
+        with:
+          distribution: goreleaser
+          version: latest
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,2 @@
+dist/
+mmdbverify
diff --git a/.goreleaser.yml b/.goreleaser.yml
@@ -0,0 +1,69 @@
+project_name: 'mmdbverify'
+version: 2
+
+before:
+  hooks:
+    - 'go mod tidy'
+
+builds:
+  - id: 'mmdbverify'
+    main: './'
+    binary: 'mmdbverify'
+    goos:
+      - 'darwin'
+      - 'linux'
+      - 'windows'
+    ignore:
+      - goos: 'darwin'
+        goarch: '386'
+      - goos: 'linux'
+        goarch: '386'
+      - goos: 'windows'
+        goarch: '386'
+
+archives:
+  - id: 'mmdbverify'
+    ids:
+      - 'mmdbverify'
+    wrap_in_directory: true
+    format_overrides:
+      - goos: windows
+        formats:
+          - zip
+    files:
+      - 'CHANGELOG.md'
+      - 'LICENSE'
+      - 'README.md'
+
+checksum:
+  name_template: 'checksums.txt'
+
+snapshot:
+  version_template: "{{ .Tag }}-next"
+
+changelog:
+  disable: true
+
+nfpms:
+  - id: 'mmdbverify'
+    ids:
+      - 'mmdbverify'
+    vendor: 'MaxMind, Inc.'
+    homepage: 'https://www.maxmind.com/'
+    maintainer: 'MaxMind, Inc. <support@maxmind.com>'
+    description: 'Tool to verify MaxMind MMDB database files.'
+    license: 'Apache 2.0'
+    formats:
+      - 'deb'
+      - 'rpm'
+    bindir: '/usr/bin'
+    contents:
+      - src: 'CHANGELOG.md'
+        dst: '/usr/share/doc/mmdbverify/CHANGELOG.md'
+      - src: 'LICENSE'
+        dst: '/usr/share/doc/mmdbverify/LICENSE'
+      - src: 'README.md'
+        dst: '/usr/share/doc/mmdbverify/README.md'
+
+release:
+  target_commitish: "{{ .FullCommit }}"
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-11-14
+
+### Added
+
+- Initial official release of mmdbverify
+- Verify MaxMind DB file validity
+- Search tree validation
+- Data section validation
+- Metadata validation and sanity checks
+- Command-line interface with `-file` flag
+- Cross-platform builds (Linux, macOS, Windows for amd64 and arm64)
+- Debian and RPM package support
+- Clear error messages to stderr
+- Zero exit code on success, non-zero on failure
+
+[unreleased]: https://github.com/maxmind/mmdbverify/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/maxmind/mmdbverify/releases/tag/v1.0.0
diff --git a/README.md b/README.md
@@ -1,27 +1,189 @@
-MaxMind DB Verifier
--------------------
+# mmdbverify
 
-This is a utility to verify that a MaxMind DB is valid. The search tree,
-data section, and metadata are all checked for validity and sanity. If the
-database cannot be parsed or is otherwise invalid, a short description will
-be sent to `stderr` and the utility will exit with a non-zero exit code. If
-successful, no output will be printed and an exit code of zero will be
-returned.
+A command-line utility to verify the validity of MaxMind DB (MMDB) files.
 
-Note that this tool may flag a database as invalid even though it is
-completely parseable. This may happen if there is unexpected data in the
-data section or metadata that is not well-formed.
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Go Version](https://img.shields.io/badge/Go-1.24%2B-00ADD8?logo=go)](https://golang.org)
 
-Usage
-=====
+## Overview
 
-Required:
+This utility verifies that a MaxMind DB file is valid by checking:
 
-* -file=[FILENAME] - The path to the database to test.
+- **Search tree** - Validates the tree structure used for IP lookups
+- **Data section** - Ensures all data is properly formatted and accessible
+- **Metadata** - Verifies metadata is well-formed and contains expected fields
 
-Copyright and License
-=====================
+If the database is valid, the tool exits silently with status code `0`. If
+invalid, an error description is printed to `stderr` and the tool exits with a
+non-zero status code.
 
-This software is Copyright (c) 2015-2025 by MaxMind, Inc.
+**Note:** This tool may flag a database as invalid even if it can be parsed.
+This occurs when there is unexpected or malformed data in the data section or
+metadata.
 
-This is free software, licensed under the Apache License, Version 2.0.
+## Installation
+
+### Binary Releases (Recommended)
+
+Download pre-built binaries from the
+[GitHub Releases page](https://github.com/maxmind/mmdbverify/releases).
+
+> **Architecture Guide:**
+>
+> - `amd64` = x86-64 / x64 (most common for Intel/AMD processors)
+> - `arm64` = ARM 64-bit (Apple Silicon, AWS Graviton, Raspberry Pi 4+)
+> - `darwin` = macOS
+
+#### Linux
+
+**Using .deb package (Debian/Ubuntu):**
+
+```bash
+# Download the .deb file for your architecture from the releases page
+sudo dpkg -i mmdbverify_<VERSION>_linux_<ARCH>.deb
+```
+
+**Using .rpm package (RedHat/CentOS/Fedora):**
+
+```bash
+# Download the .rpm file for your architecture from the releases page
+sudo rpm -i mmdbverify_<VERSION>_linux_<ARCH>.rpm
+```
+
+**Using tar.gz archive:**
+
+```bash
+# Download and extract
+tar -xzf mmdbverify_<VERSION>_linux_<ARCH>.tar.gz
+sudo mv mmdbverify/mmdbverify /usr/local/bin/
+```
+
+#### macOS
+
+```bash
+# Download the appropriate file for your Mac:
+# - darwin_arm64 for Apple Silicon (M1/M2/M3/M4)
+# - darwin_amd64 for Intel Macs
+tar -xzf mmdbverify_<VERSION>_darwin_<ARCH>.tar.gz
+sudo mv mmdbverify/mmdbverify /usr/local/bin/
+```
+
+#### Windows
+
+1. Download the Windows zip file for your architecture from the releases page
+2. Extract the zip file
+3. Add `mmdbverify.exe` to your PATH or run it directly
+
+**Using PowerShell:**
+
+```powershell
+# Extract
+Expand-Archive -Path mmdbverify_<VERSION>_windows_<ARCH>.zip -DestinationPath .
+
+# Run
+.\mmdbverify\mmdbverify.exe -file C:\path\to\database.mmdb
+```
+
+### From Source
+
+```bash
+go install github.com/maxmind/mmdbverify@latest
+```
+
+### Build Locally
+
+```bash
+git clone https://github.com/maxmind/mmdbverify.git
+cd mmdbverify
+go build
+```
+
+## Usage
+
+```bash
+# Verify a database file (silent on success)
+mmdbverify -file /path/to/GeoIP2-City.mmdb
+
+# Verify with verbose output
+mmdbverify -file /path/to/GeoIP2-City.mmdb -verbose
+# Verifying /path/to/GeoIP2-City.mmdb...
+# /path/to/GeoIP2-City.mmdb is valid
+
+# Check exit code
+echo $?
+# 0
+
+# Failure (error printed to stderr with filename, non-zero exit code)
+mmdbverify -file /path/to/invalid.mmdb
+# Error verifying /path/to/invalid.mmdb: invalid database metadata
+echo $?
+# 1
+```
+
+### Command-Line Flags
+
+- `-file` - **Required.** Path to the MaxMind DB file to verify
+- `-verbose` - Print verification status messages
+
+## Examples
+
+### Verify GeoIP2 Database
+
+```bash
+# Silent mode (default)
+mmdbverify -file GeoIP2-City.mmdb
+
+# Verbose mode
+mmdbverify -file GeoIP2-City.mmdb -verbose
+```
+
+### Verify Multiple Databases
+
+```bash
+# Verify all MMDB files with verbose output
+for db in *.mmdb; do
+    mmdbverify -file "$db" -verbose
+done
+```
+
+### Use in CI/CD Pipeline
+
+```bash
+# Exit immediately if validation fails
+mmdbverify -file GeoIP2-Country.mmdb || exit 1
+```
+
+## Use Cases
+
+- **Pre-deployment validation** - Verify databases before deploying to
+  production
+- **Download verification** - Ensure downloaded MMDB files are not corrupted
+- **CI/CD pipelines** - Validate databases in automated testing workflows
+- **Quality assurance** - Check custom MMDB files created with
+  [mmdbwriter](https://github.com/maxmind/mmdbwriter)
+
+## Requirements
+
+- Go 1.24 or later (for building from source)
+- MaxMind DB files to verify (GeoIP2, GeoLite2, or custom MMDB files)
+
+## Related Tools
+
+- [mmdbinspect](https://github.com/maxmind/mmdbinspect) - Inspect and query MMDB
+  files
+- [mmdbwriter](https://github.com/maxmind/mmdbwriter) - Create custom MMDB files
+- [mmdbconvert](https://github.com/maxmind/mmdbconvert) - Convert MMDB to
+  CSV/Parquet
+
+## License
+
+Copyright (c) 2015-2025 by MaxMind, Inc.
+
+This software is licensed under the Apache License, Version 2.0. See
+[LICENSE](LICENSE) for details.
+
+## Support
+
+- **Issues:** [GitHub Issues](https://github.com/maxmind/mmdbverify/issues)
+- **MaxMind Support:**
+  [https://support.maxmind.com](https://support.maxmind.com)
diff --git a/go.mod b/go.mod
@@ -4,4 +4,4 @@ go 1.24.0
 
 require github.com/oschwald/maxminddb-golang/v2 v2.1.0
 
-require golang.org/x/sys v0.37.0 // indirect
+require golang.org/x/sys v0.38.0 // indirect
diff --git a/go.sum b/go.sum
@@ -6,7 +6,7 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
-golang.org/x/sys v0.37.0 h1:fdNQudmxPjkdUTPnLn5mdQv7Zwvbvpaxqs831goi9kQ=
-golang.org/x/sys v0.37.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/sys v0.38.0 h1:3yZWxaJjBmCWXqhN1qh02AkOnCQ1poK6oF+a7xWL6Gc=
+golang.org/x/sys v0.38.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/main.go b/main.go
@@ -12,6 +12,7 @@ import (
 func main() {
 	required := "<REQUIRED>"
 	file := flag.String("file", required, "The path to the MaxMind DB to verify")
+	verbose := flag.Bool("verbose", false, "Print verification status messages")
 
 	flag.Parse()
 
@@ -20,14 +21,24 @@ func main() {
 		os.Exit(1)
 	}
 
+	if *verbose {
+		fmt.Printf("Verifying %s...\n", *file)
+	}
+
 	reader, err := maxminddb.Open(*file)
 	if err != nil {
-		fmt.Fprintf(os.Stderr, "Error opening file: %v\n", err)
+		fmt.Fprintf(os.Stderr, "Error opening %s: %v\n", *file, err)
 		os.Exit(1)
 	}
 
 	if err := reader.Verify(); err != nil {
-		fmt.Fprintf(os.Stderr, "Error verifying file: %v\n", err)
+		reader.Close()
+		fmt.Fprintf(os.Stderr, "Error verifying %s: %v\n", *file, err)
 		os.Exit(1)
 	}
+	reader.Close()
+
+	if *verbose {
+		fmt.Printf("%s is valid\n", *file)
+	}
 }

Original file line number	Diff line number	Diff line change
`@@ -4,4 +4,4 @@ go 1.24.0`
`4`	`4`
`5`	`5`	`require github.com/oschwald/maxminddb-golang/v2 v2.1.0`
`6`	`6`
`7`		`-require golang.org/x/sys v0.37.0 // indirect`
	`7`	`+require golang.org/x/sys v0.38.0 // indirect`