yuce
commented
7 years ago Broken the Survey part of the proposal here, since that doesn't really fit into the proposal:
Survey
In this section we present a selection of configuration options supported by other databases.
CockroachDB
Some of the command line flags CockroachDB supports are:
--host: default localhost--port: default 26257--store: changes data store location, default: cockroach-data--background: runs the server as a daemon--join: joins node to a cluster, argument is in the form host:port
Environment variables are supported. A few examples:
- CDB_DATA_DIR
- CDB_CERTS_DIR
We found no information about how to configure CockroachDB with a configuration file.
InfluxDB
InfluxDB supports the following non-exhaustive list of flags:
-database-host: default: localhost-port: default: 8086
InfluxDB supports TOML formatted configuration files. Example:
[data]
dir = "/var/lib/influxdb/data"
query-log-enabled = trueEnvironment variables are supported in the form: INFLUXDB_config-section-name_option-name.
OrientDB
Following are some of the command line flags supported by OrientDB:
-h,--host: default localhost-P,--ports: single port or port range, defaults to: 2424-2430-u,--user: default: root-p,--password: mandatory user password (default: root)
Configuration file is in XML format. Sample configuration:
<properties>
<entry name="cache.size" value="10000" />
<entry name="storage.keepOpen" value="true" />
</properties>Environment variables are supported. Below are some examples:
- CONFIG_FILE
- ORIENTDB_LOG_CONF
- ORIENTDB_PID
Redis
Redis supports the following command line flags and more:
--port: default 6379--bind: the interface to listen (default: 0.0.0.0)--daemonize--pidfile
Redis has a simple configuration file format, which lists the keys and values separated by whiteline. Same keys and values maybe separated on the commandline. Sample configuration:
daemonize no
pidfile /var/run/redis.pid
port 6379
bind 127.0.0.1Redis does not support configuration using environment variables.
RethinkDB
Below is some of the flags supported by RethinkDB:
-d, --directory: The directory to store the data--daemon: Run the server as a daemon--log-file: Specify the log file--config-file: Specify the configuration file--bind: Specify the address to listen to, default localhost
RethinkDB uses a simple configuration file with configuration specified as KEY=VALUE lines. Here’s a sample:
pid-file=/var/run/rethinkdb/rethinkdb.pid
bind=127.0.0.1
cluster-port=29015We found no information about environment variable support of RethinkDB.
jaffee
travisturner
codysoyland
Pilosa Configuration Proposal
Authors
Change log
Abstract
This document contains the proposals for command line, configuration file and environment variable naming and their priorities.
Overview
Configuration is one of the most important parts of software. If a consistent naming convention is not used, it may become hard to configure software. If the software doesn't support the same configuration as in the documentation, the users of the software may get frustrated. Because of those reasons, it is beneficial to have a single reference of configuration options, which Pilosa developers use during development and which can be used to write/update the documentation.
Most common configuration comes from the command line, a configuration file and environment variables. What set of options should be supported by these configuration sources? If the same option is used in two different sources, which should have the upper hand? These questions should be clearly answered to decrease the number of surprises during operation of the software.
In summary, the aims of this document are:
In Table 1 below, current configuration options and defaults are presented:
Proposal
In order to have uniform meaning and representation we use the following terms in our proposal:
Address: Complete address of a service. Aliases: bind, BIND
SCHEME://HOST:PORTform: Specify scheme, host and portHOST:PORTform: Specify host and port, use the default schemeHOSTform: Specify the host and use the default port and scheme:PORTform: Specify the port and use the default host and schemeSCHEME://HOSTform: Specify scheme, host and use the default portSCHEME://:PORTform: Specify scheme and port and use the default hostWe renamed Host which used to mean an address in the current configuration and use HTTP Address instead. In Table 2 below, we summarized the proposed configuration, showing added or changed configuration in bold.
$HOME/.pilosaPriority of Configuration Sources
The configuration maybe specified in the command line, in an environment variable, in the configuration file or the default for that configuration is used. In order to be able to specify the configuration, the priority between these sources should be defined. Below is our proposed priority of sources, where higher level sources override the lower ones:
Command Line
One of the debates in the computing world is the number of dashes before a flag. BSD style utilities does not use any dashes and allows only single letter flags. GNU convention is to use double dashes (
--) before the standard form of a flag and a single dash (-) before the alternative (short) form. Some software uses minus (-) to denote removal of a feature and plus (+) to denote addition. Java, Go and Erlang uses single dash before flags with their command line tools. In this proposal we opted for the GNU style flags, based solely on the observation that the quantity of modern software using that convention vastly outweighs the single dash style, and developers using modern UNIX and UNIX-like OSs would have a certain taste for it. It should be noted that Go’s standard flag parser doesn’t differentiate between single and double dashes.In the light of the discussion above, always use lowercase flags with double dashes (
--) to denote the long form and a single dash (-) to denote the alternative form. Only the most used flags should have an alternative form. Use dash (-) character as the word delimiter. Command line options should be preferably as short as possible without losing their meaning. Table 3 is below:--config-c--data-dir-d--bind-b--bind-PROTOCOL--cluster.replicas--cluster.hostsHOST1:PORT1 HOST2:PORT2--poll-interval--messenger--gossip--plugin-dir--pluginsPLUGIN1 PLUGIN2--plugin-PLUGIN_NAME--anti-entropy.interval--profile.cpu--profile.cpu-time--logConfiguration File
The configuration file is in the TOML format. Use lowercase section and key names. Use dash (
-) character as the word delimiter. Table 4 is below:Environment Variables
Most prominent deployment and orchestration tools such as, Puppet, Chef and Ansible also Docker support environment variables to pass configuration to a program. Moreover, environment variables are the preferred way of passing configuration for some application structuring conventions, like Twelve-Factor App
All environment variables are uppercase with underscore (
_) used as the word delimiter. Some deployment tools (such as Puppet) seems to unable to set environment variables per process (only for the system). In order to avoid inadvertent configuration,PILOSA_prefix must be used. Table 5 is below:Implementation
The
Configstructure inconfig.goshould be modified to match Table 2.(m *Main) ParseFlags(args []string)method incmd/pilosa/main.goshould be moved toconfig.goand become a method ofConfig. New command line flags should be added to that method. A new methods which reads configuration from environment variables should be added. Ideally,Configshould have a method which reads from all configuration sources and applies the priorities mentioned in this document to the fields ofConfig.