Modules and reproducible builds

Now that the MySQL driver is installed, let’s take a look at the go.mod file (which we created right at the start of the book). You should see a require block with two lines containing the path and exact version number of the packages that you downloaded:

module snippetbox.alexedwards.net

go 1.23.0

require (
    filippo.io/edwards25519 v1.1.0 // indirect
    github.com/go-sql-driver/mysql v1.8.1 // indirect
)

These lines in go.mod essentially tell the Go command exactly which version of a package should be used when you run a command like go run, go test or go build from your project directory.

This makes it easy to have multiple projects on the same machine where different versions of the same package are used. For example, this project is using v1.8.1 of the MySQL driver, but you could have another codebase on your computer which uses v1.5.0 and that would be A-OK.

You’ll also see that a new file has been created in the root of your project directory called go.sum.

This go.sum file contains the cryptographic checksums representing the content of the required packages. If you open it up you should see something like this:

filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA=
filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
github.com/go-sql-driver/mysql v1.8.1 h1:LedoTUt/eveggdHS9qUFC1EFSa8bU2+1pZjSRpvNJ1Y=
github.com/go-sql-driver/mysql v1.8.1/go.mod h1:wEBSXgmK//2ZFJyE+qWnIsVGmvmEKlqwuVSjsCm7DZg=

The go.sum file isn’t designed to be human-editable and generally you won’t need to open it. But it serves two useful functions:

• If you run the go mod verify command from your terminal, this will verify that the checksums of the downloaded packages on your machine match the entries in go.sum, so you can be confident that they haven’t been altered.

  $ go mod verify
  all modules verified

• If someone else needs to download all the dependencies for the project — which they can do by running go mod download — they will get an error if there is any mismatch between the packages they are downloading and the checksums in the file.

So, in summary:

• You (or someone else in the future) can run go mod download to download the exact versions of all the packages that your project needs.
• You can run go mod verify to ensure that nothing in those downloaded packages has been changed unexpectedly.
• Whenever you run go run, go test or go build, the exact package versions listed in go.mod will always be used.

And those things together makes it much easier to reliably create reproducible builds of your Go applications.

Additional information

Upgrading packages

Once a package has been downloaded and added to your go.mod file the package and version are ‘fixed’. But there are many reasons why you might want to upgrade to use a newer version of a package in the future.

To upgrade to latest available minor or patch release of a package, you can simply run go get with the -u flag like so:

$ go get -u github.com/foo/bar

Or alternatively, if you want to upgrade to a specific version then you should run the same command but with the appropriate @version suffix. For example:

$ go get -u github.com/foo/bar@v2.0.0

Removing unused packages

Sometimes you might go get a package only to realize later that you don’t need it anymore. When this happens you’ve got two choices.

You could either run go get and postfix the package path with @none, like so:

$ go get github.com/foo/bar@none

Or if you’ve removed all references to the package in your code, you can run go mod tidy, which will automatically remove any unused packages from your go.mod and go.sum files.

$ go mod tidy