.\" -*- mode: troff; coding: utf-8 -*-
.TH "" "7" ""
.SH NAME
.LP
alpm-db - a database format for describing the state of packages on an \fBA\fRrch \fBL\fRinux \fBP\fRackage \fBM\fRanagement (ALPM) based system.
.SH DESCRIPTION
.LP
The databases on ALPM based systems are represented by a directory structure that contains metadata files.
The contents of such a database describes the state of all installed packages.
Here, \fBALPM-MTREE\fR, \fBalpm-db-desc\fR and \fBalpm-db-files\fR files provide metadata on specific package versions currently installed.
.PP
Entries for databases are created from \fBalpm-package\fR files using package management software such as \fBpacman\fR.
Package management software relies on \fBalpm-db\fR structures for the purpose of search, dependency resolution and system management.
.PP
The \fBalpm-db\fR format exists in multiple versions.
The information in this document is for version \f(CR9\fR, which is the current version and has been introduced with the release of \fBpacman\fR 4.2.0 on 2014-12-19.
.SS
Contents
.LP
The contents of the system database depend on the number of unique packages it describes.
Each package can only appear once, in a single version.
.SS
Metadata
.LP
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
.LP
In each of these directories, one \fBALPM-MTREE\fR, one \fBalpm-db-desc\fR and one \fBalpm-db-files\fR file are kept to describe a package, e.g.:
.LP
.EX
\&.
└── example-package-1.0.0-1
    ├── desc
    ├── files
    └── mtree
.EE
.SS
Schema version
.LP
The current schema version of the system database is encoded in the top-level version file \f(CRALPM_DB_VERSION\fR.
This ASCII text file contains a single line with a numeric version string, e.g.:
.LP
.EX
9
.EE
.PP
When changes to the format of the system database are necessary, they are indicated by incrementing the version string intended for the version file.
.PP
Dedicated tools such as \fBpacman-db-upgrade\fR are used to upgrade the contents of the system database (e.g. metadata files, directory structure) and eventually update the version in \f(CRALPM_DB_VERSION\fR.
.SS
Creation
.LP
The data in an \fBalpm-db\fR is derived from \fBalpm-package\fR files and created using package management software such as \fBpacman\fR.
For the \fBalpm-db-desc\fR entries, the package\(cqs \fBPKGINFO\fR data, as well as the properties of the package file are used.
The \fBalpm-repo-files\fR file is directly derived from the package file\(cqs list of data files.
The \fBALPM-MTREE\fR file is a copy of the package\(cqs \fBALPM-MTREE\fR file.
.LP
.EX
              alpm-db -----------.
              /  |  \e             \e
             /   |   \e             \e
alpm-db-files    |    alpm-db-desc  |
    |            |         |        |
    |         ALPM-MTREE   |        |
 data files      |         |        |
       \e         |       PKGINFO   /
        \e        |     /          /
         \e       |    /          /
          alpm-package-----------
.EE
.SH EXAMPLES
.SS
Installing a package on a system
.LP
Assuming an empty system, the installation of a package \f(CRexample-package\fR in version \f(CR1.0.0-1\fR leads to the following addition in the \fBalpm-db\fR:
.LP
.EX
\&.
└── example-package-1.0.0-1
    ├── desc
    ├── files
    └── mtree
.EE
.SS
Upgrading an existing package on a system
.LP
Extending on the previous example on \fBinstalling a package on a system\fR, the upgrade of a package \f(CRexample-package\fR to version \f(CR1.1.0-1\fR leads to the following change in the \fBalpm-db\fR:
.LP
.EX
\&.
└── example-package-1.1.0-1
    ├── desc
    ├── files
    └── mtree
.EE
.SH SEE ALSO
.LP
\fBALPM-MTREE\fR(5), \fBPKGINFO\fR(5), \fBalpm-db-desc\fR(5), \fBalpm-db-files\fR(5), \fBalpm\fR(7), \fBalpm-package\fR(7), \fBalpm-package-name\fR(7), \fBalpm-package-version\fR(7), \fBpacman\fR(8), \fBpacman-db-upgrade\fR(8)