This is documentation for the CCMS (Collaborative Collections Management System).

1. Reference

1.1. Commands

1.1.1. create set

Define a new set

create set set_name
Description

The create set command creates a new, empty set.

Parameters

set_name

The name of the new set.
Currently set names must begin with test followed by ., because test is the only available project space for new sets.
Examples

Create a set myset in project test:

create set test.myset;

1.1.2. insert

Insert objects into a set

insert into target_set_name
    select *
        from source_set_name
        [ where search_condition ]
        [ limit count ]
Description

The insert command selects objects from a source set according to specified criteria, and inserts the selected objects into a target set.

Parameters
into

The into clause specifies the target set.

from

The from clause specifies the source set.

where

The where clause specifies a search condition in the form of a Boolean expression. Only objects that satisfy this condition will be selected.

See also Reference > Queries.

limit

The limit clause specifies a maximum number of objects that will be returned.

Examples

To select items in stock from the reserve set and insert them into a set test.myset:

insert into test.myset select * from reserve where availability = 'In stock';

1.1.3. select

Retrieve objects from a set

select *
    from set_name
    [ where search_condition ]
    [ order by attribute [ asc | desc ] ]
    limit count
    [ offset start ]
Description

The select command retrieves a list of objects from a set according to specified criteria.

Parameters

The first argument specifies * meaning all available attributes.

from

The from clause specifies the desired set that will be the source of data.

where

The where clause specifies a search condition in the form of a Boolean expression. Only objects that satisfy this condition will be retrieved.

See also Reference > Queries.

order by

The order by clause specifies a sort order for objects to be returned. The objects are sorted by the specified attribute, with asc for ascending order (the default) or desc for descending order.

limit

The limit clause specifies a maximum number of objects that will be returned.

At present the limit clause is required for select.
offset

The offset clause specifies a number of objects that will be skipped and not returned as part of the result. This can be useful for retrieving objects one page of data a time. Note that the order by clause is required when offset is used.

Examples

To retrieve items in stock from the set test.myset:

select * from test.myset where availability = 'In stock' order by title;

1.1.4. show

List the values of a system variable

show name
Description

show lists the current values of system configurations or other variables.

Parameters

name

sets

Currently defined sets.
Examples
show sets;

1.2. Queries

1.2.1. Value expressions

The where clause in a query is followed by a search condition. This condition is a Boolean expression consisting of operators and operands.

The supported operators, in order of precedence, are:

Operator Associativity Description

= <> < > <= >=

comparison operators

not

right

logical negation

and

left

logical conjunction

or

left

logical disjunction

Parentheses may be used to override these precedence rules.

Supported operand types are:

Operand type Example Description

name

author

attribute name

string literal

'Thomas à Kempis'

string constant

number

33

numeric constant

1.3. Protocol

Non-query commands such as create set return a diagnostic status:

{
  "commands": "create set test.myset;"
}
{
  "results": [
    {
      "status": "create set"
    }
  ]
}

The status may be an error:

{
  "results": [
    {
      "status": "error",
      "message": "set test.myset already exists"
    }
  ]
}

Query commands such as select also return tabular data sets, with the attribute names described under "fields", e.g.:

{
  "commands": "select id from test.myset limit 2;"
}
{
  "results": [
    {
      "status": "select",
      "fields": [
        {
          "name": "id",
          "type": "bigint"
        }
      ],
      "data": [
        [
          41
        ],
        [
          63
        ]
      ]
    }
  ]
}
Selecting individual attributes, as in the example above, is not yet supported. However, select * is supported.

Multiple commands can be combined in a single request, separated by semicolons:

{
  "commands": "create set test.myset; create set test.myset2;"
}

2. Server administration

2.1. System requirements

2.1.1. Hardware requirements

This section will contain system hardware requirements.

2.1.2. Software requirements

  • Operating system: Linux

  • Database system: PostgreSQL 18 or later

  • To build from source:

2.2. Building the software

It is suggested that a ccms user be created and the server run by that user, for example, in /home/ccms.

To build CCMS, first set the GOPATH environment variable to specify a path that can serve as the build workspace for Go, e.g.:

export GOPATH=$HOME/go

Then to build the server:

./build

The build script creates a bin/ subdirectory and builds the ccd server and ccc client executables there:

./bin/ccd help

./bin/ccc help

In general running ccd takes the form:

ccd <command> <arguments>

Some typical commands are:

  • init initializes a new CCMS instance

  • start starts the server

  • stop shuts down the server

  • version prints the CCMS version

For more infomation about a specific command:

ccd help <command>

2.3. Server configuration

The ccd server makes use of local storage in a data directory which is created using ccd with the init command. In this example we will create the data directory as data/:

ccd init -D data

This will also create a file ccd.conf in the data directory with the following structure:

[main]
host = host name of the PostgreSQL server
port = port number of the PostgreSQL server
user = database user that is the owner of the database
password = password of user
dbname = database name
sslmode = should be set to "require" or stronger option

This file should be edited to add database connection parameters, for example:

[main]
host = ccms.indexdata.com
port = 5432
user = ccms
password = w6bqYkFWm4rpGR5mCtFw
dbname = ccms
sslmode = require

The ccd server will assume that the user and database defined here already exist; so they should be created before continuing. The user should be the owner of the database.

2.4. Upgrading from a previous version

Upgrading from a previous version of CCMS is not currently supported.

2.5. Running the server

To start the server:

nohup ccd start -D data -l ccd.log &

To stop the server:

ccd stop -D data

The server can be set up to run with systemd via a file such as /etc/systemd/system/ccms.service, for example:

[Unit]
Description=CCMS
After=network.target remote-fs.target

[Service]
Type=simple
User=ccms
ExecStart=/bin/bash -ce "exec /home/ccms/bin/ccd start -D /home/ccms/data -l /home/ccms/ccd.log"
Restart=on-abort

[Install]
WantedBy=multi-user.target

Then:

systemctl enable ccms

systemctl start ccms