.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "DACHS" 1 "2021-02-04" "2.3"
.SH NAME
dachs \- data publishing infrastructure for the Virtual Observatory (VO)
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs [global\-options] <subcommand> [options] function\-argument ...
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
dachs  provides  support for data ingestion and publishing, for metadata
handling, and for a variety of VO protocols and standards, e.g. the
Table Access Protocol (TAP) or the Simple Cone Search (SCS).
.sp
There are numerous sub\-commands covering the various tasks (importing,
controlling the server, running tests, etc).
.sp
Subcommand names can be abbreviated to the shortest unique prefix.
.sp
A central concept of DaCHS is the Resource Descriptor (RD), and XML
description of a data collection including metadata, ingestion rules,
service definitions, and regression tests.  They are usually referenced
through their RD ids, which are the relative paths from DaCHS\(aq inputs
directory to the file containing the RD, with the conventional extension
\fB\&.rd\fP stripped.  For instance, in a default install, the file
\fB/var/gavo/inputs/myrsc/q.rd\fP would have \fBmyrsc/q\fP as RD id.
.sp
Most commands dealing with RD ids will also pick up RDs if referenced by
path; in the example above, if you are in \fB/var/gavo/inputs/myrsc\fP,
you could also reference the RD as either \fBq\fP or \fBq.rd\fP\&.
.sp
Several commands take references to RD elements (table definitions, exec
items, direct grammar, etc).  These consist of an RD id as just
discussed, a hash mark, and the XML id of the target element.  Tables
have an id automatically, for other elements you may have to add an
artificial id.
.SH GLOBAL OPTIONS
.sp
Global options are given before the subcommand name.
.INDENT 0.0
.TP
.B  \-\-debug
produce debug info as appropriate
.TP
.B  \-\-enable\-pdb
run pdb on all errors
.TP
.B  \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.B  \-\-hints
if there are hints on an error, display them
.TP
.BI \-\-profile\-to\fB= PROFILEPATH
enable profiling and write a profile to PROFILEPATH
.TP
.B  \-\-suppress\-log
suppress logging of exceptions to the dachs\-specific log files
.TP
.B  \-\-version
shows the versions of the software, of the database schema
expected by the software and of the database schema actually
on disk (if the latter two disagree, run dachs upgrade).
.UNINDENT
.SH THE ADMIN SUBCOMMAND
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs admin  [\-h] subsubfunction [subfunction\-arguments ...]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This is a somewhat random collection of commands related to
administering a data center.  In particular, this is where you create
and edit accounts.
.sp
subsubcommands can be abbreviated as long as the abbreviation is
unique.  For instance \fBdachs adm xsd\fP will do an XSD validation.
.sp
For more information on the subsubfunctions, pass a \fB\-h\fP flag.
.SS Subsubcommands
.INDENT 0.0
.IP \(bu 2
\fBaddtogroup user group\fP \-\- adds a user to a group
.IP \(bu 2
\fBadduser user password [remarks]\fP \-\- add  a  user/password pair to
the DaCHS user table.  Note that as of DaCHS 1.0 the password is stored
in clear text and also transmitted in clear text since DaCHS only
supports HTTP basic authentication.  Do not use valuable passwords
here
.IP \(bu 2
\fBchangeuser user password [remarks]\fP \-\- change remarks and/or
password for a DC user.  See adduser for details.
.IP \(bu 2
\fBcleantap\fP \-\- remove expired Universal Worker Service (UWS) jobs
.IP \(bu 2
\fBdelfromgroup user group\fP \-\- remove a user from a group
.IP \(bu 2
\fBdeluser user\fP \-\- remove a DaCHS user from the user table.
.IP \(bu 2
\fBdumpDF path\fP \-\- Dumps the source of a file included with the DaCHS
distribution.  The argument is a package resource path
(like /inputs/__system__/scs.rd); for system RDs, the special
//rd\-id syntax is supported.
.IP \(bu 2
\fBexecute exec\-id\fP \-\- Execute the contents of an RD execute element. You
must give that element an explicit id in order to make this work; then
exec\-id is rd\-id#exec\-id
.IP \(bu 2
\fBhipsfill [\-d HIPSDIR] svcId\fP \-\- complete the properties file in
HIPSDIR with metadata from the service referenced by svcId (e.g.,
q#hips).
.IP \(bu 2
\fBhipsgen dataId minOrder\fP \-\- Write a Hipsgen parameter file for making a
HiPS out of the data imported by dataId (e.g., q#import) to stdout.
minOrder is the minimal HEALPix order Hipsgen should generate (low
orders are computationally expensive!)
.IP \(bu 2
\fBhashPassword pw\fP \-\- hash a password.  adduser and friends already
hash themselves, so this is likely only useful for the
[web]adminPasswd setting.
.IP \(bu 2
\fBindexStatements tableRef\fP \-\- show the statements to create the
indices on a table.  The tableRef has the format RD\-id#table\-id; it
is \fInot\fP a database table reference.
.IP \(bu 2
\fBlistusers\fP \-\- dump the user table
.IP \(bu 2
\fBmakedelrec ivoid\fP \-\- create a registry record of ivoid saying
the resource is removed.  This is only necessary when recovering
from disasters that made you lose records from DaCHS\(aq internal
tables.
.IP \(bu 2
\fBsuggestucds tableId\fP \-\- Make suggestions for UCDs of the columns
of the referenced table (rd\-id#table\-id format) not having one.
This is based on their descriptions and uses a GAVO web service.
.IP \(bu 2
\fBtapabort jobId helpMsg\fP \-\- manually abort a TAP job and return
helpMsg to the requesting user as error message.
.IP \(bu 2
\fBupdateTAPSchema\fP \-\- Update the TAP_SCHEMA metadata for all RDs
mentioned in TAP_SCHEMA (deprecated; use dachs imp //tap
refresh instead).
.IP \(bu 2
\fBxsdValidate path\fP \-\- Validate a file against built\-in VO schemas
and with built\-in schema validator.
.UNINDENT
.SH THE CONFIG SUBCOMMAND
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs config [section\-name] config\-key
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This outputs values of DaCHS\(aq configuration to stdout.  section\-name
defaults to general.  This is most commonly used to make external
components aware of DaCHS\(aq file locations, e.g., through
\fBinputs_dir=$(dachs config inputsDir)\fP\&.
.sp
See the operator\(aqs guide for a documentation on DaCHS\(aq configuration
options.
.SH THE DATAPACK SUBCOMMAND
.sp
Synposis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs datapack [\-h] {create,load} ...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Management of full DaCHS resources in the frictionless data package
format.  Note that while DaCHS\-created data packages should work as
normal data packages, DaCHS can only (automatically) load data packages
generated by DaCHS itself \-\- there simply is not enough metadata in
generic data packages to produce usable resources.
.SS Subsubcommands
.SS datapack create
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs datapack create [\-h] id dest
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Positional arguments:
.INDENT 0.0
.TP
.B id
Absolute RD id to produce a datapack for
.TP
.B dest
Name of a zip file to dump to
.UNINDENT
.sp
The command creates a data package containing the RD, a README in the
resource directory if it exists, auxiliary files (like a booster grammar
or a custom core) the RD may have, and all data files that the sources
in the RD yield; for collecting these files, \fBsources\fP elements with
\fBignoreSources\fP children reading from the database are ignored,
because that would make behaviour a bit too unpredictable.
.sp
To include further files, you can use the datapack\-extrafiles property
on the RD.  This must contain a json sequence literal with
resdir\-relative shell patterns that should be included as well.
Non\-existing paths and directories in this list are silently ignored.
You cannot include files outside of the resource directory in a data
package.
.SS datapack load
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs datapack load [\-h] [\-t] [\-\-force] source
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Positional argument:
.INDENT 0.0
.TP
.B source
Name of a DaCHS\-produced data package zip file.
.UNINDENT
.sp
Optional arguments:
.INDENT 0.0
.TP
.B  \-t\fP,\fB  \-\-no\-test
Do not run tests after importing.
.TP
.B  \-\-force
If the resdir the package declares already exists, remove it
before unpacking (rather than bailing out.
.UNINDENT
.sp
This unpacks a DaCHS\-produced data package, imports it, and runs tests
on it (which you will want to suppress if you do not have a DaCHS server
running locally).
.SH THE DROP SUBCOMMAND
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
drop [\-h] [\-s] [\-\-all] rd\-id [dd\-id ...]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This is the reverse of import: Tables created by a \fBdachs imp\fP with
identical arguments are being torn down by \fBdachs drop\fP\&.  This will
not work reliably if the RD has been modified between the imp and the
drop, in particular if the RD has been deleted.  In such situations, you
can use the \fB\-f\fP flag, which unconditionally tears down everything
DaCHS has recorded as coming from the referenced RD.
.SS Arguments
.INDENT 0.0
.TP
.B rd\-id
RD path or ID to drop
.TP
.B dd\-id
optional  data descriptor (DD) ID(s) if you do not
want to drop the entire RD; note that  no  service
publications will be undone if you give DD IDs
.UNINDENT
.SS Options
.INDENT 0.0
.TP
.B  \-\-all
drop  all  DDs  in  the RD, not only the auto ones
(overrides manual selection)
.TP
.B  \-s\fP,\fB  \-\-system
drop tables even if they are system tables
.UNINDENT
.SH THE DUMP SUBCOMMAND
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs dump [\-h] {load,create,ls} ...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This is an interface to dumping database tables and inspecting and
restoring the generated dumps.
.sp
This is mainly intended for small to medium tables that are just kept
in the database, e.g., DaCHS\(aq administrative tables and the like.  For
normal user tables, built from science data, doing re\-imports is the
recommended way to deal with data loss.
.sp
In particular, this command is \fInot\fP designed (at this point) for really
large tables.  For technical reasons (that could be overcome), currently
the individual dumps are kept in memory during creation (but not during
loading).
.sp
Before loading, the target tables are dropped if they are already
present; note that this will also drop any views they might be part of,
as well as any rows that have foreign keys on this table.  After
loading, indices and primary keys on the restored tables will be
recreated, but no scripts or similar are run.  Hence, you will have to
manually re\-create any dependent resources after a restore.
.sp
This also means that, for example, restoring a table with products
without also restoring //products#products will lose the products that
previously were in the restored table from the products table.
.SS Subsubcommands
.SS dump create
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs dump create [options] dumpFile ids [ids ...]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Dump one or more tables to DaCHS\(aq dump format.  When you pass in RD ids,
all onDisk\-tables defined in the RD will be dumped.
.sp
Positional arguments:
.INDENT 0.0
.TP
.B dumpFile
Name of a file to write the dump to; use \- to dump to stderr.
.TP
.B ids
ids of table definitions (as in myres/q#main) or RDs to dump.
.UNINDENT
.sp
Options:
.INDENT 0.0
.TP
.B  \-\-text
write dumps in text format.  You need that when objects in the
tables have no binary representation.  At least in 2020, that is
true for all pgsphere objects.
.UNINDENT
.SS dump load
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs dump load [\-h] source
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Restore table(s) from a file created by the \fBdump create\fP subcommand
before
.sp
Positional argument:
.INDENT 0.0
.TP
.B source
File to restore from. Use \- to restore from stdin.
.UNINDENT
.SS dump ls
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs dump ls [\-h] source
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
List tables and dump metadata from a DaCHS dump.
.sp
Positional arguments:
.INDENT 0.0
.TP
.B source
source file to list
.UNINDENT
.SH THE GENCOL SUBCOMMAND
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs gencol [\-h] [\-f {fits,vot,viz}] FILE
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The gencol subcommand quickly generates a set of basic column elements
for inclusion in RDs.  It is particularly convenient together with
\fBdachs start\fP\&.
.sp
This currently understands FITS binary tables, VOTables and Vizier\-Style
byte\-by\-byte descriptions (the latter somewhat haphazardly).  It assumes
there is only one table in each file (and will ignore others in the FITS
and VizieR case).
.sp
It will extract what metadata there is and emit formatted RD XML to
stdout; this should work just fine for cut\-and\-paste into <table>
elements in RD.  Note that usually, important metadata will be missing
(e.g., UCDs for FITS and VizieR), and usually data providers are not
terribly careful when writing metadata.  Hence, you should definitely
thoroughly review the elements created before using them in a public
service.
.sp
The program tries to guess the applicable parser from a file name
(e.g., README or anything ending in .txt will be treated as
Vizier\-like).  Where this fails, use the \-f option.
.sp
For Vizier\-like descriptions, the program also dumps \fBcolDefs\fP
material for use in columnGrammar\-s.
.SS Argument
.INDENT 0.0
.TP
.B FILE
Source file to generate the columns from. This can be
a FITS, a VOTable, or Vizier Column\-by\-column
description, and DaCHS will guess based on the
extension. Use the format option if it guesses wrong.
.UNINDENT
.SS Options
.INDENT 0.0
.TP
.B  \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.BI \-f \ FMT\fR,\fB \ \-\-format \ FMT
Format of the input table: FITS binary (\fBfits\fP), VOTable (\fBvot\fP), or
Vizier byte\-by\-byte (\fBviz\fP)
.UNINDENT
.SH THE IMPORT SUBCOMMAND
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs import [options] rd\-name [data\-id]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This subcommand is used to ingest data described by an RD.  For special
applications, ingestion can be restricted to specific data items within
an RD.
.SS Options
.INDENT 0.0
.TP
.B  \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.B  \-n\fP,\fB  \-\-updateRows
Deprecated.  Use updating data items instead.
.TP
.B  \-d\fP,\fB  \-\-dumpRows
Dump raw rows as they are emitted by the grammar.
.TP
.B  \-D\fP,\fB  \-\-dumpIngestees
Dump processed rows as emitted by the row makers.
.TP
.B  \-R\fP,\fB  \-\-redoIndex
Drop indices before updating a table and recreate them
when done
.TP
.B  \-m\fP,\fB  \-\-meta\-only
just update table meta (privileges, column descriptions,...).  This
will also update the tables\(aq obscore clauses, but you will have to
\fBdachs imp //obscore\fP to update the obscore view itself in this
case.
.TP
.B  \-I\fP,\fB  \-\-meta\-and\-index
do not import, but update table meta (privileges,
column descriptions,...) and recreate the indices
.TP
.B  \-u\fP,\fB  \-\-update
update mode \-\- don\(aqt drop tables before writing.
.TP
.B  \-s\fP,\fB  \-\-system
(re\-)create system tables, too
.TP
.B  \-v\fP,\fB  \-\-verbose
talk a lot while working
.TP
.B  \-r\fP,\fB  \-\-reckless
Do not validate rows before ingestion
.TP
.BI \-M \ MAX\fR,\fB \ \-\-stop\-after\fB= MAX
Stop after having parsed MAX rows
.TP
.BI \-b \ N\fR,\fB \ \-\-batch\-size\fB= N
deliver N rows at a time to the database.
.TP
.B  \-c\fP,\fB  \-\-continue\-bad
do not bail out after an error, just skip the current
source and continue with the next one.
.TP
.B  \-L\fP,\fB  \-\-commit\-after\-meta
commit the importing transaction after updating the
meta tables.  Use this when loading large (hence \-L)
data sets to avoid keeping a lock on the meta tables
for the duration of the input, i.e., potentially days.
The price is that users will see empty tables during
the import.
.TP
.B  \-\-hide\-adql
Interpret adql=True on tables as adql=hidden (this is for fallback mirrors)
.UNINDENT
.SH THE INFO SUBCOMMAND
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs info [\-h] table\-id
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This displays column statistics about the table referred to in the
argument (which must be a fully qualified table name resolvable by the
database system).
.SS Argument
.INDENT 0.0
.TP
.B table\-id
table ID (of the form rdId#tableId)
.UNINDENT
.SH THE INIT SUBCOMMAND
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs init [\-h] [\-d DSN] [\-\-nodb]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This initialises DaCHS\(aq file system and database environment.  Calling
\fBdachs init\fP on an existing site should not damage anything.  It
might, however, fix things if, for instance, permissions on some
directories went funny.
.SS Options
.INDENT 0.0
.TP
.BI \-d \ <DSN>\fR,\fB \ \-\-dsn \ <DSN>
data source name (DSN) to use to  connect  to  the future DaCHS
database; the DSN must let DaCHS connect to the database as an
administrator;  dbname, host,  and  port  get  copied  to  the
profile, if given; this is not required if the calling user
has superuser privileges on a database running on localhost.
Otherwise, the DSN has to look like \(dqhost=example.org dbname=mydb
user=superuser password=secret\(dq.
.TP
.B  \-\-nodb
inhibit  initialization  of  the database (you may
want to use this when refreshing the  file  system
hierarchy)
.UNINDENT
.SH THE LIMITS SUBCOMMAND
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs limits [\-h] [\-t] [\-s P] [\-d] itemId [itemId ...]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This creates or updates DaCHS\(aq estimates of various metadata of RDs
or tables, in particular the STC coverage, the size of the tables and,
unless \fB\-t\fP is given, the column statistics.  This may take a long
time for large tables, in which case you may use the
\fB\-\-sample\-percent\fP option, which makes DaCHS only look at a subset
of the full data.
.sp
When running \fBdachs limits\fP on an RD, it will skip views under the
assumption that in the typical case, column metadata for the
interesting columns will already have been obtained for the source
tables.  For views for which this is assumption is wrong, set the
forceStats property to True.
.sp
You should in general run \fBdachs limits\fP before publishing a resource.
.SS Arguments
.INDENT 0.0
.TP
.B itemId
either an RD id or a table reference in the from rd\-id#table\-id.
A single ALL will expand to all RDs that already have limits\-obtained
metadata.
.UNINDENT
.SS Options
.INDENT 0.0
.TP
.B  \-t\fP,\fB  \-\-tables\-only
Only acquire table/resource\-level metadata (rather than column
metadata, which usually takes a lot longer).
.TP
.BI \-s \ P\fR,\fB \ \-\-sample\-percent \ P
Only look at P percent of the table to determine min/max/mean.
.TP
.B  \-d\fP,\fB  \-\-dump
Do not obtain statistics but rather dump the results of the
last run
.UNINDENT
.SH THE MKBOOST SUBCOMMAND
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs mkboost [option] <id\-of\-directGrammar>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This writes a C source skeleton for using the direct grammar referenced
to fill a database table.  See the \fIGuide to Write Booster Grammars\fP in
the DaCHS documentation for how to use this command.
.SS Options
.INDENT 0.0
.TP
.B  \-b\fP,\fB  \-\-binary
generate a skeleton for a binary parser
.TP
.BI \-s \ <SPLITTER>\fR,\fB \ \-\-splitter\fB= <SPLITTER>
generate   a  split  skeleton  with  split  string
<SPLITTER>
.UNINDENT
.SH THE MKRD SUBCOMMAND
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs mkrd [option] sample
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Rudimentary support for generating RDs from data.  This was probably
a bad idea.  Better use dachs start.
.SS Options
.INDENT 0.0
.TP
.BI \-f \ <SRCFORM>\fR,\fB \ \-\-format\fB= <SRCFORM>
source format: FITS or VOT; default: detected from
file name
.TP
.BI \-t \ <TABLENAME>\fR,\fB \ \-\-table\-name\fB= <TABLENAME>
name of the generated table
.UNINDENT
.SH THE PUBLISH SUBCOMMAND
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs pub [\-h] [\-a] [\-m] [\-k] [\-u] rd [rd ...]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This marks data and/or services contained in an RD as published; this
will make them displayed in DaCHS\(aq portal page or pushed to the VO
registry through DaCHS\(aq OAI\-PMH endpoint.  See the \fIOperator\(aqs Guide\fP
for details.
.SS Arguments
.INDENT 0.0
.TP
.B rd
RDs to publish; you can give ids or file paths. Use
the magic value ALL to check all published RDs,
ALL_RECURSE to look for RDs in the file system (check
twice for detritus before doing that later thing).
.UNINDENT
.SS Options
.INDENT 0.0
.TP
.B  \-k\fP,\fB  \-\-keep\-timestamps
Preserve the time stamp of the last record modification. This may
sometimes be desirable with minor updates to an RD that don\(aqt
justify a re\- publication to the VO.
.TP
.B  \-u\fP,\fB  \-\-unpublish
Unpublish all resources coming from this RD Note that this will in
general create \(dqdeleted records\(dq, i.e., essentially empty resource
records only stating that the resource referenced by an identifier
is no longer available.  This is important for reliable operation
in the presence of incremental harvesting.
.UNINDENT
.SH THE PURGE SUBCOMMAND
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs purge [\-h] tablename [tablename...]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will delete tables in the database and also remove their metadata
from DaCHS\(aq internal tables (e.g., TAP_SCHEMA, table of published
records).  Use this if \fBdachs drop\fP fails for to remove some table for
one reason or another.
.SS Argument
.INDENT 0.0
.TP
.B tablename
(SQL) name of the table to drop,  including  the  schema name
.UNINDENT
.SH THE SERVE SUBCOMMAND
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs serve [\-h] {debug | reload | restart | start | stop}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This exposes various functionality for managing DaCHS\(aq server component.
While these usually are being called through init scripts or systemd
components, the \fBdebug\fP subfunction is very convenient during service
development off the production environment.
.sp
\fBserve start\fP, \fBstop\fP, and \fBrestart\fP manage a PID file, which
DaCHS does not do when running under systemd.  Hence, do \fInot\fP use these
subcommands when systemd manages your DaCHS.  expireRD is fine, though.
.SS Subsubcommands
.INDENT 0.0
.IP \(bu 2
\fBdebug\fP \-\- run a server and remain in the foreground, dumping all
kinds of stuff to the terminal.  If you have an SSL certificate, this
will try bind an https interface to port 40443; that\(aqs exclusively
for little experiments, do not use it for actual operations.
.IP \(bu 2
\fBreload\fP \-\- reload server configuration (incomplete)
.IP \(bu 2
\fBrestart\fP \-\- restart the server
.IP \(bu 2
\fBstart\fP \-\- start the server and put it in the background
.IP \(bu 2
\fBstop\fP \-\- stop a running server
.IP \(bu 2
\fBexpireRD <rdId>\fP \-\- forget the cached RD in the running server.
While in general, DaCHS reloads an RD if it finds it changed,
sometimes it does not realise some dependency has changed.  In that
case, this subsubcommand can expunge the RD so it will be re\-parsed
when the next access occurs.  Note that this requires
[web]adminpasswd be set; the command uses [web]serverURL to figure
out where to connect the running server.
.UNINDENT
.sp
The \fBstart\fP subcommand accepts a \fB\-\-foreground/\-f\fP option.  If you pass
it, the server will not double\-detach and not redirect stderr to a log
file and instead stay in the foreground; it will also not check for PID
files or create them.  In contrast to \fBdebug\fP, it
will change users, etc., and not put the DaCHS into debug mode.
This option is primarily useful for systemd units.
.SH THE START SUBCOMMAND
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs start [\-h] (list|<data\-type\-tag>)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The start subcommand generates a template RD for a certain type of data
that you can then fill out.  The data\-type\-tag can be something like scs
(for catalogs), siap (for images), or ssap (for spectra).  Pass \fBlist\fP
to see what is available.
.sp
The template uses the name of current directory as resdir and schema
name.  That means that if starting a data collection, you should create
its resdir as a child of GAVO_ROOT/inputs and execute \fBdachs start\fP in
that dicrectory.
.sp
To fill out the template RD, load it into a text editor and, ina first
go, search for the pattern %.*%.  You should see enough hints from what
is between the percent signs and the environment to get a reasonable
shot at filling things out.  Then reead the comments; very typcially,
you can get an extremely basic data publication without that, but a good
service will normally require some extra work beyond filling things out.
.SS Argument
.INDENT 0.0
.TP
.B data\-type\-tag
A short identifier for a data type.  Pass \fBlist\fP here to see a
list of known tags and their meanings.
.UNINDENT
.SH THE TEST SUBCOMMAND
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs test [\-h] [\-v] [\-V] [\-d] [\-t TAG] [\-R N] [\-T SECONDS] [\-D FILE]
            [\-w SECONDS] [\-u SERVERURL] [\-n NTHREADS]
            [\-\-seed RANDOMSEED] [\-k KEYWORDS]
            id
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This runs regression tests embedded in the whatever is reference by id
(can be an RD, a regression suite, or a single regression test).  For
details, see the chapter on \fIregression testing\fP in the \fIDaCHS Reference
Manual\fP\&.
.SS Argument
.INDENT 0.0
.TP
.B id
RD id or cross\-RD identifier for a testable thing.  Write ALL here
to have DaCHS search and test all RDs in the inputs, ignoring those
in or below directories with a file named DACHS_PRUNE.
.UNINDENT
.SS Options
.INDENT 0.0
.TP
.B  \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.B  \-v\fP,\fB  \-\-verbose
Talk while working
.TP
.B  \-d\fP,\fB  \-\-dump\-negative
Dump the content of failing tests to stdout
.TP
.BI \-t \ TAG\fR,\fB \ \-\-tag \ TAG
Also run tests tagged with TAG.
.TP
.BI \-R \ N\fR,\fB \ \-\-n\-repeat \ N
Run each test N times
.TP
.BI \-T \ SECONDS\fR,\fB \ \-\-timeout \ SECONDS
Abort and fail requests after inactivity of SECONDS
.TP
.BI \-D \ FILE\fR,\fB \ \-\-dump\-to \ FILE
Dump the content of last failing test to FILE
.TP
.BI \-w \ SECONDS\fR,\fB \ \-\-wait \ SECONDS
Wait SECONDS before executing a request
.TP
.BI \-u \ SERVERURL\fR,\fB \ \-\-serverURL \ SERVERURL
URL of the DaCHS root at the server to test
.TP
.BI \-n \ NTHREADS\fR,\fB \ \-\-number\-par \ NTHREADS
Number of requests to be run in parallel
.TP
.BI \-k \ KEYWORDS\fR,\fB \ \-\-keywords \ KEYWORDS
Only run tests with descriptions containing all
(whitespace\-separated) keywords. Sequential tests will
be run in full, nevertheless, if their head test
matches.
.UNINDENT
.SH THE VALIDATE SUBCOMMAND
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs validate [\-h] [\-x] [\-v] rd [rd...]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This checks RDs for well\-formedness and some aspects  of  VO\-friendliness
.SS Arguments
.INDENT 0.0
.TP
.B rd
RD path or ID to validate.  Write ALL here to have DaCHS search
and validate all RDs in your input and validate them, ignoring those
in or below directories with a file named DACHS_PRUNE.
.UNINDENT
.SS Options
.INDENT 0.0
.TP
.B  \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.B  \-p\fP,\fB  \-\-pre\-publication
Validate as if all services were IVOA published even
if they are not (this may produce spurious errors if
unpublished services are in the RD).
.TP
.B  \-v\fP,\fB  \-\-verbose
Talk while working
.TP
.B  \-t\fP,\fB  \-\-run\-tests
Run regression tests embedded in the checked RDs
.TP
.BI \-T \ SECONDS\fR,\fB \ \-\-timeout \ SECONDS
When running tests, abort and fail requests after
inactivity of SECONDS
.TP
.B  \-c\fP,\fB  \-\-compare\-db
Also make sure that tables that are on disk (somewhat)
match the definition in the RD.
.UNINDENT
.SH THE UPGRADE SUBCOMMAND
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs upgrade
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Each DaCHS version has an associated database schema version, encoding
the structure of DaCHS\(aq (and the implemented protocol versions\(aq) ideas of
how system and user tables should look like.  \fBdachs upgrade\fP attempts
to work out how to change the database to match the expectations of the
current version and executes the respective code.  It will not touch
its data structures if it decrees that the installation is up to date.
.sp
Operating system packages will usually try to run \fBdachs upgrade\fP as
part of their management operation.  In case \fBdachs upgrade\fP requires
manual intervention, this may fail, in which case operators may need to
call \fBdachs upgrade\fP manually.
.sp
Operators keeping a manually installed DaCHS should run \fBdachs upgrade\fP
after each \fBsvn update\fP or update from tar.
.sp
\fBdachs upgrade\fP cannot perform actions requiring superuser privileges,
since none of its roles have those.  Currently, this is mainly updating
postgres extensions DaCHS uses (if you use extra ones, you can configure
DaCHS\(aq watch list in [db]managedExtensions).  \fBdachs upgrade \-e\fP will
attempt to figure out the instructions necessary to update extensions
and write them to stdout.  Hence, operators should execute something
like \fBdachs upgrade \-e | psql gavo\fP from a database superuser account
after upgrading postgres extensions.
.SS Options
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.BI \-\-force\-dbversion \ FORCEDBVERSION
assume this as the database\(aqs schema version. If you
don\(aqt develop DaCHS, you almost certainly should stay
clear of this flag
.TP
.B  \-e\fP,\fB  \-\-get\-extension\-script
Dump a script to update DaCHS\-managed extensions (will
print nothing if no extensions need updating). This
will return 0 if material was written, 1 otherwise.
.TP
.B  \-t\fP,\fB  \-\-update\-tap\-schema
Update the TAP schema, i.e., re\-read all the
metadata from the TAP\-published tables.  This
isn\(aqt really related to upgrading, but it is
generally a good idea to sync on\-disk
representations with what you may have edited in
the RDs.
.UNINDENT
.UNINDENT
.UNINDENT
.SH THE ADQL SUBCOMMAND
.sp
Synopsis:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dachs adql query
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This subcommand executes ADQL queries locally and writes the resulting
VOTable to stdout.  We consider removing it.
.SH INTERNAL OR DEPRECATED SUBCOMMANDS
.sp
The subcommands \fBshow\fP, \fBstc\fP are deprecated and not documented
here.  They may disappear without further notice.
.sp
the subcommands \fBtaprun\fP, \fBdlrun\fP, \fBuwsrun\fP, \fBgendoc\fP, \fBraise\fP
are used internally and should not be directly used by DaCHS operators.
.SH REPORTING BUGS
.sp
To report bugs and request support, please use our support mailing
list \fI\%http://lists.g\-vo.org/cgi\-bin/mailman/listinfo/dachs\-support\fP\&.
.SH SEE ALSO
.sp
Comprehensive, if always incomplete documentation on DaCHS is available
in several documents available at \fI\%http://docs.g\-vo.org/DaCHS/\fP
(upstream site with PDF downloads and the formatted reference
documentation) and \fI\%http://dachs\-doc.readthedocs.io/en/latest/index.html\fP
(with facilities for updating the documents).
.SH COPYRIGHT
.sp
Copyright  ©  2017  The GAVO project.  License GPLv3+: GNU
GPL version 3 or later <\fI\%http://gnu.org/licenses/gpl.html\fP>.
This is free software: you are free  to  change  and  redistribute  it.
There is NO WARRANTY, to the extent permitted by law.
.SH AUTHOR
Markus Demleitner <gavo@ari.uni-heidelberg.de>
.\" Generated by docutils manpage writer.
.