.\" -*- mode: troff; coding: utf-8 -*-
.TH "" "7" ""
.SH NAME
.LP
alpm-repo-db - a database format for describing the metadata of \fBA\fRrch \fBL\fRinux \fBP\fRackage \fBM\fRanagement (ALPM) based package repositories.
.SH DESCRIPTION
.LP
Repository databases are (optionally compressed) \fBtar\fR archives that contain directories and metadata files.
The contents of such a database describe the state of an ALPM package repository (\fBalpm-repo\fR).
Here, \fBalpm-repo-desc\fR and \fBalpm-repo-files\fR files provide metadata on specific package versions currently considered in a package repository.
.PP
Repository database files are created from \fBalpm-package\fR files using package repository management software (e.g. \fBdbscripts\fR[1] which relies on \fBrepo-add\fR).
.PP
Package management software (e.g. \fBpacman\fR) relies on \fBalpm-repo-db\fR files for the purpose of search, dependency resolution and download of package files.
.PP
In some contexts, repository databases may be referred to as \fIrepository sync databases\fR or \fIrepository metadata\fR.
.SS
Variants
.LP
Two variants of repository databases exist: \fIdefault\fR and \fIdefault with files\fR.
.IP "1." 3
\fIdefault\fR: The database contains one \fBalpm-repo-desc\fR file per \fBalpm-package\fR in the repository.
This repository database variant allows package management software to query relevant metadata for search and download of package files from a repository.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "2." 3
\fIdefault with files\fR: The database contains one \fBalpm-repo-desc\fR and one \fBalpm-repo-files\fR file per \fBalpm-package\fR in the repository.
In addition to querying relevant metadata for search and download of package files from a repository, this repository database variant allows package management software to search through a simple file list per package.
.SS
Format
.LP
\fIUncompressed\fR repository database files in the variant \fIdefault\fR follow the following naming scheme:
.PP
An \fBalpm-repo-name\fR directly followed by the string \(oq.db.tar\(cq (e.g. \f(CRrepo.db.tar\fR).
.PP
\fIUncompressed\fR repository database files in the variant \fIdefault with files\fR follow the following naming scheme:
.PP
An \fBalpm-repo-name\fR directly followed by the string \(oq.files.tar\(cq (e.g. \f(CRrepo.files.tar\fR).
.SS
Compression
.LP
Repository databases may optionally be compressed using a single supported compression technology.
If an \fBalpm-repo-db\fR is compressed, a technology-specific suffix is appended to the file name:
.IP "\(bu" 3
\f(CR.Z\fR for compression based on adaptive Lempel-Ziv coding (e.g. \f(CRrepo.db.tar.Z\fR, or \f(CRrepo.files.tar.Z\fR), see the \fBcompress\fR command
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CR.bz2\fR for \fBbzip2\fR compression (e.g. \f(CRrepo.db.tar.bz2\fR, or \f(CRrepo.files.tar.bz2\fR)
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CR.gz\fR for \fBgzip\fR compression (e.g. \f(CRrepo.db.tar.gz\fR, or \f(CRrepo.files.tar.gz\fR)
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CR.lrz\fR for \fBlrzip\fR compression (e.g. \f(CRrepo.db.tar.lrz\fR, or \f(CRrepo.files.tar.lrz\fR)
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CR.lz4\fR for \fBlz4\fR compression (e.g. \f(CRrepo.db.tar.lz4\fR, or \f(CRrepo.files.tar.lz4\fR)
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CR.lz\fR for \fBlzip\fR compression (e.g. \f(CRrepo.db.tar.lz\fR, or \f(CRrepo.files.tar.lz\fR)
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CR.lzo\fR for \fBlzop\fR compression (e.g. \f(CRrepo.db.tar.lzo\fR, or \f(CRrepo.files.tar.lzo\fR)
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CR.xz\fR for \fBxz\fR compression (e.g. \f(CRrepo.db.tar.xz\fR, or \f(CRrepo.files.tar.xz\fR)
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CR.zst\fR for \fBzstd\fR compression (e.g. \f(CRrepo.db.tar.zst\fR, or \f(CRrepo.files.tar.zst\fR)
.LP
Handling of compression technologies is specific to the package repository management tool.
.SS
Digital signatures
.LP
Digital signatures can be created for repository database files.
.PP
Currently, only \fBOpenPGP signatures\fR[2] over the repository database file are supported.
Detached signatures carry the same name as the repository database file for which they are created, with an additional \f(CR.sig\fR suffix (e.g. \f(CRrepo.db.tar.zst.sig\fR is the digital signature for a repository database file \f(CRrepo.db.tar.zst\fR).
.SS
Symlinks
.LP
For each variant of a repository database as well as for each of their digital signatures, a symlink is created, that represents an archive and compression agnostic file name.
.LP
.EX
\&.
├── repo.db -> repo.db.tar.gz
├── repo.db.sig -> repo.db.tar.gz.sig
├── repo.db.tar.gz
├── repo.db.tar.gz.sig
├── repo.files -> repo.files.tar.gz
├── repo.files.sig -> repo.files.tar.gz.sig
├── repo.files.tar.gz
└── repo.files.tar.gz.sig
.EE
.PP
These file names are used by package management software to download package repository databases regardless of compression algorithms, which allows to change them on the fly.
.SS
Contents
.LP
The contents of a repository database depend on the database variant and the number of unique \fBalpm-package\fR files in the \fBalpm-repo\fR it describes.
Here, each package can only be present in a single version in the repository database.
In both variants, metadata of a package is kept in a top-level directory, that is named after the package and its specific version.
The name follows this schema:
.PP
An \fBalpm-package-name\fR directly followed by a \f(CR-\fR sign, directly followed by an \fBalpm-package-version\fR (in the \fIfull\fR or \fIfull with epoch\fR form), e.g.:
.IP "\(bu" 3
\f(CRexample-package-1.0.0-1\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRexample-package-1:1.0.0-1\fR
.SS
Default
.LP
The \fIdefault\fR repository database variant keeps one \fBalpm-repo-desc\fR file per package in the repository database, e.g.:
.LP
.EX
\&.
└── example-package-1.0.0-1
    └── desc
.EE
.SS
Default with files
.LP
The \fIdefault with files\fR repository database variant keeps one \fBalpm-repo-desc\fR and one \fBalpm-repo-files\fR file per package in the repository database, e.g.:
.LP
.EX
\&.
└── example-package-1.0.0-1
    ├── desc
    └── files
.EE
.SS
Creation
.LP
ALPM repository databases are created using one or more \fBalpm-package\fR files and their respective optional digital signatures.
For the \fBalpm-repo-desc\fR entries, the package\(cqs \fBPKGINFO\fR data, as well as the properties of the package file and its optional digital signature are used.
The \fBalpm-repo-files\fR file is directly derived from the package file\(cqs list of data files.
.LP
.EX
            alpm-package - - - - digital signature
           /      |     \e           /
   data files   PKGINFO  \e         /
      /                \e  \e       /
     /                  \e  \e     /
    |                    \e  |   /
    |     alpm-repo-db    \e |  /
    |    /            \e   | | /
alpm-repo-files    alpm-repo-desc
.EE
.SH EXAMPLES
.SS
Adding a package to an empty repository database
.LP
Given a repository named \f(CRrepo\fR and a package named \f(CRexample-package\fR, the following example explores the use and transformation of metadata when adding a package to a package repository.
.PP
Assuming to start off with an empty package repository, the repository databases will exist already:
.LP
.EX
\&.
├── repo.db -> repo.db.tar.gz
├── repo.db.sig -> repo.db.tar.gz.sig
├── repo.db.tar.gz
├── repo.db.tar.gz.sig
├── repo.files -> repo.files.tar.gz
├── repo.files.sig -> repo.files.tar.gz.sig
├── repo.files.tar.gz
└── repo.files.tar.gz.sig
.EE
.PP
The \f(CRrepo\fR repository does not contain any packages yet, both \f(CRrepo.db.tar.gz\fR and \f(CRrepo.files.tar.gz\fR are empty.
.PP
First, the package file and its digital signature are put into the repository directory to bring it into scope:
.LP
.EX
\&.
├── example-package-1.0.0-1-x86_64.pkg.tar.zst
├── example-package-1.0.0-1-x86_64.pkg.tar.zst.sig
├── repo.db -> repo.db.tar.gz
├── repo.db.sig -> repo.db.tar.gz.sig
├── repo.db.tar.gz
├── repo.db.tar.gz.sig
├── repo.files -> repo.files.tar.gz
├── repo.files.sig -> repo.files.tar.gz.sig
├── repo.files.tar.gz
└── repo.files.tar.gz.sig
.EE
.PP
Repository management software is then used to add \f(CRexample-package\fR to the repository database.
Here, the contents of the repository database variants are changed and their respective digital signatures updated.
.PP
The \fIdefault\fR repository database will contain:
.LP
.EX
\&.
└── example-package-1.0.0-1
    └── desc
.EE
.PP
The \fIdefault with files\fR repository database will contain:
.LP
.EX
\&.
└── example-package-1.0.0-1
    ├── desc
    └── files
.EE
.PP
Only now, package management software is made aware of the package \f(CRexample-package\fR in version \f(CR1.0.0-1\fR in the package repository \f(CRrepo\fR, after downloading the updated repository database.
.SS
Updating a package in a repository database
.LP
Extending on the above example of \fBadding a package to an empty repository database\fR, the following example illustrates updating package metadata in a repository database.
Assuming to start off with a package repository \f(CRrepo\fR, that already contains the package \f(CRexample-package\fR in version \f(CR1.0.0-1\fR, the repository directory should look something like this:
.LP
.EX
\&.
├── example-package-1.0.0-1-x86_64.pkg.tar.zst
├── example-package-1.0.0-1-x86_64.pkg.tar.zst.sig
├── repo.db -> repo.db.tar.gz
├── repo.db.sig -> repo.db.tar.gz.sig
├── repo.db.tar.gz
├── repo.db.tar.gz.sig
├── repo.files -> repo.files.tar.gz
├── repo.files.sig -> repo.files.tar.gz.sig
├── repo.files.tar.gz
└── repo.files.tar.gz.sig
.EE
.PP
The \fIdefault\fR repository database will contain:
.LP
.EX
\&.
└── example-package-1.0.0-1
    └── desc
.EE
.PP
The \fIdefault with files\fR repository database will contain:
.LP
.EX
\&.
└── example-package-1.0.0-1
    ├── desc
    └── files
.EE
.PP
If the package \f(CRexample-package\fR receives an upgrade (e.g. for version \f(CR1.1.0-1\fR), this new package file and its corresponding digital signature are copied to the repository directory:
.LP
.EX
\&.
├── example-package-1.0.0-1-x86_64.pkg.tar.zst
├── example-package-1.0.0-1-x86_64.pkg.tar.zst.sig
├── example-package-1.1.0-1-x86_64.pkg.tar.zst
├── example-package-1.1.0-1-x86_64.pkg.tar.zst.sig
├── repo.db -> repo.db.tar.gz
├── repo.db.sig -> repo.db.tar.gz.sig
├── repo.db.tar.gz
├── repo.db.tar.gz.sig
├── repo.files -> repo.files.tar.gz
├── repo.files.sig -> repo.files.tar.gz.sig
├── repo.files.tar.gz
└── repo.files.tar.gz.sig
.EE
.PP
At this point, both repository database variants still advertise the package \f(CRexample-package\fR in version \f(CR1.0.0-1\fR.
However, the package files and digital signatures of both version \f(CR1.0.0-1\fR and version \f(CR1.1.0-1\fR are present in the repository directory.
.PP
Repository management software is then used to add \f(CRexample-package\fR in version \f(CR1.1.0-1\fR to the repository database.
As only one version of \f(CRexample-package\fR may exist in a given repository database, the metadata for \f(CR1.0.0-1\fR is removed.
.PP
The \fIdefault\fR repository database will contain:
.LP
.EX
\&.
└── example-package-1.1.0-1
    └── desc
.EE
.PP
The \fIdefault with files\fR repository database will contain:
.LP
.EX
\&.
└── example-package-1.1.0-1
    ├── desc
    └── files
.EE
.SH SEE ALSO
.LP
\fBbzip2\fR(1), \fBcompress\fR(1), \fBgzip\fR(1), \fBlrzip\fR(1), \fBlz4\fR(1), \fBlzip\fR(1), \fBlzop\fR(1), \fBpkgctl\fR(1), \fBtar\fR(1), \fBxz\fR(1), \fBzstd\fR(1), \fBPKGINFO\fR(5), \fBalpm-repo-desc\fR(5), \fBalpm-repo-files\fR(5), \fBalpm-package\fR(7), \fBalpm-package-name\fR(7), \fBalpm-package-version\fR(7), \fBalpm-repo\fR(7), \fBalpm-repo-name\fR(7), \fBpacman\fR(8), \fBrepo-add\fR(8)
.SH NOTES
.IP "1." 3
\fBdbscripts\fR
.IP
.UR https://gitlab.archlinux.org/archlinux/dbscripts
.UE
.IP "2." 3
\fBOpenPGP signatures\fR
.IP
.UR https://openpgp.dev/book/signing_data.html#detached-signatures
.UE