7.5 Package Catalog Database

► |  | Package Management in Racket

1 | Getting Started with Packages
2 | Package Concepts
3 | Using raco pkg
4 | Package Metadata
5 | Source, Binary, and Built Packages
6 | Developing Packages with Git
7 | Package APIs
8 | Package Catalog Protocol
9 | PLane T Compatibility
10 | FAQ
11 | Future Plans
12 | How Package Installation and Distribution Works

▼ | 7 | Package APIs

7.1 | Functions for raco pkg
7.2 | Package Management Functions
7.3 | Package Paths and Database
7.4 | Package Source Parsing
7.5 | Package Catalog Database
7.6 | Package Directories Catalog
7.7 | Package Management Environment Variables

On this page:

pkg
current-pkg-catalog-file
call-with-pkgs-transaction
get-catalogs
set-catalogs!
get-pkgs
set-pkgs!
set-pkg!
get-pkg-tags
set-pkg-tags!
get-pkg-ring
set-pkg-ring!
get-pkg-dependencies
set-pkg-dependencies!
get-pkg-modules
set-pkg-modules!
get-module-pkgs
get-pkgs-without-modules

9.0
top contents ← prev up next →

### 7.5 Package Catalog Database🔗ℹ

(require pkg/db) | package: base

The pkg/db library provides tools for storing and retrieving package catalog information in a local database.

The functions provided by pkg/db do not actually manage packages; they do not change or consult the local database of installed modules in any package scope. The functions provided by pkg/db simply reflect a local copy of the information that a package catalog and individual package might provide (but with no guarantee of being in sync with an actual package catalog or package).

The database is implemented as an SQLite database with its own locking, so no additional locks are needed for database access, but beware of concurrent database changes that could break your program logic.

> > struct
> > (struct |  | pkg (name catalog author source checksum desc)
> #:extra-constructor-name make-pkg
> #:transparent)
> name : string?
> catalog : string?
> author : string?
> source : string?
> checksum : string?
> desc : string?

Represents a package implementation in the database. The name (package name) and catalog (package catalog, normally a URL) fields are always nonempty strings. Otherwise, unknown fields are represented by empty strings.

> parameter (current-pkg-catalog-file) → path-string?
> (current-pkg-catalog-file file) → void?
> file : path-string?

A parameter that determines the file path used to hold the SQLite database. The default value is in the user’s add-on directory as determined by (find-system-path 'addon-dir) and within a subdirectory determined by get-installation-name.

> procedure (call-with-pkgs-transaction proc) → any
> proc : (-> any)

Calls proc so that multiple calls to other pkg/db functions are grouped as a database transaction, which avoids the overhead of making each individual call its own transaction.

Added in version 6.1.1.5 of package base.

> procedure (get-catalogs) → (listof string?)
> procedure (set-catalogs! catalogs) → void?
> catalogs : (listof string?)

Returns or sets the list of strings for all package catalog represented in the database. (Within the database, each package catalog gets its own identifying number.) The order of indices in the list represents a search order.

The set-catalogs! function removes information for any other package catalogs from the database.

> procedure (get-pkgs [#:name name #:catalog catalog]) → (listof pkg?)
> name : (or/c #f string?) = #f
> catalog : (or/c #f string?) = #f

Gets a list of package descriptions. If name or catalog is not #f (or if both are not #f), then the result includes only matching packages.

The result list is ordered by precedence of the package catalog.

> > procedure
> > (set-pkgs! |  | catalog |
> > |  | pkgs |
> > |  | #:clear-other-checksums? clear-other-checksums?) |
> → void?
> catalog : string?
> pkgs : (listof (or/c string? pkg?))
> clear-other-checksums? : #t

Sets the list of all packages that are recognized by the package catalog catalog.

Information about any other package for catalog is removed from the database. If a string is provided for pkgs, it is treated as a package name; if additional information is already recorded in the database for the package name, then the additional information is preserved.

If clear-other-checksums? is true, then for each element of pkgs that has a given checksum other than "", any information in the database specific to another checksum (such as a list of module paths) is removed from the database.

> > procedure
> > (set-pkg! |  | name |
> > |  | catalog |
> > |  | author |
> > |  | source |
> > |  | checksum |
> > |  | desc |
> > |  | #:clear-other-checksums? clear-other-checksums?) |
> → void?
> name : string?
> catalog : string?
> author : string?
> source : string?
> checksum : string?
> desc : string?
> clear-other-checksums? : (not (equal? checksum ""))

Sets the information for a specific package name as recognized by the package catalog catalog.

If clear-other-checksums? is true, then information (such as a list of module paths) is removed from the database when it is specific to a checksum other than checksum.

> procedure (get-pkg-tags name catalog) → (listof string?)
> name : string?
> catalog : string?
> procedure (set-pkg-tags! name catalog module-paths) → void?
> name : string?
> catalog : string?
> module-paths : (listof string?)

Gets or sets a list of tags for the package name as recognized by the package catalog catalog.

> procedure (get-pkg-ring name catalog)
> → (or/c #f exact-nonnegative-integer?)
> name : string?
> catalog : string?
> procedure (set-pkg-ring! name catalog ring) → void?
> name : string?
> catalog : string?
> ring : (or/c #f exact-nonnegative-integer?)

Gets or sets a ring number for the package name as recognized by the package catalog catalog.

The PLT-supported package catalog reports a curated ring number to reflect advice on package preference and conflicts, where the set of ring-0 and ring-1 packages are expected to have no conflicts (that is, no multiply defined modules, document names, etc.). The raco pkg tool does not pay attention to a package’s ring number, but other uses of a catalog may consult ring numbers.

Added in version 6.10.0.3 of package base.

> procedure (get-pkg-dependencies name catalog checksum) → (listof list?)
> name : string?
> catalog : string?
> checksum : string?
> > procedure
> > (set-pkg-dependencies! |  | name |  |  |  |
> > |  | catalog |  |  |  |
> > |  | checksum |  |  |  |
> > |  | dependencies) |  | → |  | void?
> name : string?
> catalog : string?
> checksum : string?
> dependencies : (listof any/c)

Gets or sets a list of dependencies for the package name as recognized by the package catalog catalog and for a specific checksum.

The list of dependencies must have the shape described for a deps "info.rkt" field as described in Package Metadata. The result from get-pkg-dependencies is normalized: each dependency is represented by a list, a version in a dependency is always preceded by '#:version, and if both version and platform specification are included, '#:version appears before '#:platform.

> procedure (get-pkg-modules name catalog checksum) → (listof module-path?)
> name : string?
> catalog : string?
> checksum : string?
> > procedure
> > (set-pkg-modules! |  | name |  |  |  |
> > |  | catalog |  |  |  |
> > |  | checksum |  |  |  |
> > |  | module-paths) |  | → |  | void?
> name : string?
> catalog : string?
> checksum : string?
> module-paths : (listof module-path?)

Gets or sets a list of module paths that are provided for the package name as recognized by the package catalog catalog and for a specific checksum. The module paths should be normalized in the sense of collapse-module-path.

> procedure (get-module-pkgs module-path) → (listof pkg?)
> module-path : module-path?

Reports a list of packages that implement the given module-path, which should be normalized in the sense of collapse-module-path.

> procedure (get-pkgs-without-modules [#:catalog catalog]) → (listof pkg?)
> catalog : (or/c #f string?) = #f

Returns a list of packages (optionally constrained to catalog) for which the database has no modules recorded.

Each resulting pkg has its name, catalog, and checksum field set, but other fields may be "".

top contents ← prev up next →