SlashDB Configuration Files

All of SlashDB's configuration files reside in the /etc/slashdb/ directory.

├── databases.cfg
├── license.key
├── nginx.conf
├── querydefs.cfg
├── slashdb.ini
└── users.cfg

The *.cfg files contain YAML formatted configs for databases, users and sql pass-thru queries. We recommend only editing those using the Configuration GUI. If needed, the files can be modified manually, but you must make sure that the slashdb and memcached services are offline beforehand and started after.

To stop/start slashdb and memcached:

sudo service slashdb stop
sudo service memcached stop

sudo service slashdb start
sudo service memcached start

databases.cfg

A simple configuration for SQLite database looks like below

Chinook:
  alternate_key: {}
  autoload: true
  autoload_user: {dbpass: '', dbuser: ''}
  connection: /var/lib/slashdb/sqlite/chinook.sqlite
  creator: admin
  db_encoding: utf-8
  db_id: Chinook
  db_schema: null
  db_type: sqlite
  desc: Example SQLite database
  excluded_columns: {}
  execute: []
  foreign_keys: {}
  autoconnect: true
  read: []
  write: []

It's easier to modify database configuration using Configuration GUI. Some features are hidden and require modifying databases.cfg manually.

alternate_key

Data Discovery reflects only tables with primary keys. When a primary key is not defined it may be manually added to config under in alternate_key dictionary. This feature can be used for database views that typically don't have primary key.

The keys in the dictionary are names of tables, values are lists of column names that can be treated as artificial primary key.

Example:

alternate_key:
  Table1: [col1, col2]
  ViewCustomer: [CustomerId]

autoload

This options when true tells SlashDB to make a full reflect on database. When false then SlashDB will be looking for the model installed as plugin with the same name. This feature is used for advanced use cases with custom built ORM model.

autoload: true
autoload_user: {dbuser: 'john', dbpass: 'secretpasssowrd'}

autoload_user

It's a dictionary that stores login and password to the database to be used for reflect purposes. It must be used together with autoload = true

Example:

autoload: true
autoload_user: {dbuser: 'john', dbpass: 'secretpasssowrd'}

connection

Connection stores location of the database. For SQLite it's path to file e.g. /home/john/database.sqlite. For MS SQL, DB2, MySQL, MariDB, PostgreSQL it's host, port and database e.g. 192.168.1.1:1433/Northwind. For Oracle it's host, port and SID e.g. 192.168.1.1:1521/xe

Example

connection: database.my-domain:1433/Northwind

creator

Creator options is used for administrative purposes. User which adds a new database config is assigned as a creator and is automatically granted permissions to read, modify and connect the database.

db_encoding

This option tells SlashDB what is the charset encoding in the database. This information in required to correctly process diacritic characters. Allowed values are:

utf-16-be utf-16-le utf-7 utf-8 ascii
big5 big5hkscs cp037 cp424 cp437
cp500 cp737 cp775 cp850 cp852
cp855 cp856 cp857 cp860 cp861
cp862 cp863 cp864 cp865 cp866
cp869 cp874 cp875 cp932 cp949
cp950 cp1006 cp1026 cp1140 cp1250
cp1251 cp1252 cp1253 cp1254 cp1255
cp1256 cp1257 cp1258 ujis eucjis2004
eucjisx0213 euckr gb2312 gbk gb18030-2000
hz-gb-2312 iso-2022-jp iso-2022-jp-1 iso-2022-jp-2 iso-2022-jp-2004
iso-2022-jp-3 iso-2022-jp-ext iso-2022-kr iso-8859-1 iso-8859-2
iso-8859-3 iso-8859-4 iso-8859-5 iso-8859-6 iso-8859-7
iso-8859-8 iso-8859-9 iso-8859-10 iso-8859-13 iso-8859-14
iso-8859-15 cp1361 koi8_r koi8_u mac_cyrillic
mac_greek mac_iceland mac_latin2 mac_roman mac_turkish
ptcp154 shiftjis shiftjis2004 shiftjisx0213 utf-16

db_id

Unique database id that is used in other configuration files: users.cfg and querydefs.cfg. Also the id becomes an API endpoint in Data Discovery e.g. /db/Chinook.

db_schema

This option is used if SlashDB should connect to certain schema in the database. That's applicable for databases that support use schema like MS SQL, PostgreSQL, Oracle, DB2. If not provided a default user schema is used.

db_type

Defines what sort of a database server SlashDB is connecting. Allowed values are:

  • sqlite for SQLite
  • mssql for MS SQL Server
  • oracle for Oracle
  • db2 for IBM DB2
  • mysql for MySQL or MariaDB
  • postgresql for PostgreSQL

desc

Non-obligatory additional description of the purpose of the API or any other useful notes.

excluded_columns

This option allows to exclude certain columns from the API but columns cannot be part on relationship constraint. Whole table can be removed from API by excluding primary key for certain table.

Option excluded_columns expects a dictionary object where key is table name and value is list of column names to be excluded form API.

Example: To exclude a regular columns Company, Address and City from table Customer and BillingAddress from table Invoice

excluded_columns:
    Customer: [Company, Address, City]
    Invoice: [BillingAddress]

To exclude a table from API exclude the primary key.

excluded_columns:
    InvoiceLine: [InvoiceLineId]

execute

It's a list of SlashDB users allowed to control state of that particular API state - connect or disconnect. Account admin is always privileged and doesn't have to listed.

Example:

Only john, mike and admin will be able change the state of the connection.

execute: [john, mike]

foreign_keys

Deprecated. Should be empty dictionary or null.

autoconnect

This option accept true or false value that define if the API should connect automatically to the server when SlashDB starts.

read

List of users allow to view the database config. Account admin is always privileged and doesn't have to listed.

Example:

Only john, mike and admin will be able view the config details.

read: [john, mike]

write

List of users allowed to modify the database config.Account admin is always privileged and doesn't have to listed.

Example:

Only john, mike and admin will be able view the config details.

read: [john, mike]

users.cfg

users

querydefs.cfg

sql pass-thru queries

license.key

It's a INI formatted file containing an initial license. As with *.cfg files, it is recommended to only use the GUI to modify and update this file.

nginx/nginx.conf

This file contains the SlashDB's default nginx configuration. If you are using something other that nginx as the http server, this file can be used as a information source / template for your custom setup. Changes to this file require restating the SlashDB service.

To restart Slashdb service:

sudo service slashdb restart

slashdb.ini

slashdb.ini is the core config file for SlashDB. Just like the license.key, it is an INI formatted file.

API key settings

The header and query string argument names can be defined to match environment and other systems requirements e.g. 3Scale.

app_id_name (Not used in single parameter credentials)
apikey_name

Example

Changed apikey_name to "secret".

# Header or get parameter authentication.
# Two parameters credentials use appid and apikey (called app_id mode in 3Scale).
# Single parameter credentials userapikey (called user_key mode in 3Scale)
appid_name = appid
apikey_name = secret

Request with modified apikey_name in query string

curl -i 'localhost:8888/db.json?appid=mobile-app-1&secret=v8fcyt1l8jbpp58157eo16456ms9ap61'

HTTP/1.1 200 OK

Request with modified apikey_name in header

curl -i 'localhost:8888/db.json' /
-H 'appid:mobile-app-1' /
-H 'secret:v8fcyt1l8jbpp58157eo16456ms9ap61'

HTTP/1.1 200 OK

Full INI file example

[app:sdbapp]

# Pyramid config
use = egg:slashdb
mako.directories = slashdb.formats.html_sdb:templates
static_path = slashdb.formats.html_sdb:static
exclog.ignore = pyramid.httpexceptions.WSGIHTTPException

# SlashDB Config
branding.name = SlashDB
branding.tag = SlashDB
output_encoding = utf-8
databases_path = /etc/slashdb/databases.cfg
users_path = /etc/slashdb/users.cfg
querydefs_path = /etc/slashdb/querydefs.cfg
initial_state_path = /etc/slashdb/regular-initial
license = /etc/slashdb/license.key
license_upgrading_email = contact@slashdb.com

# makes accepting terms and conditions required in welcome slides for development license
require_details_in_terms_and_conditions = False

# URL used to save user details from welcome slides registration
registration_url = https://beta.slashdb.com/db/SDB/license.json?apikey=12345677890

authentication = True
google.cse_id = 123456789012346790:doom-o_hrva
default_limit = 29
ignore_default_fields = False
models_package = slashdb.models

refid_prefix = __href

# URL substitution configuration
# url.substitution.__ = /
url.append_substitution = False

# How often to reissue a new cookie in sec.
# Suggested 1/10 of cookie_timeout
cookie_reissue_time = 360

# How long a ticket in cookie valid in sec.
cookie_timeout = 3600

# How long a cookie is valid in sec.
cookie_max_age = 3600

# Memcached server
memcached_server = 127.0.0.1:11211

# Header or get parameter authentication.
# Two parameters credentials use appid and apikey (called app_id mode in 3Scale).
# Single parameter credentials useapikey (called user_key mode in 3Scale)
appid_name = appid
apikey_name = apikey

# engine echo when reflecting models
engine_echo = False

# Should SlashDB stream data by default
stream_by_default = False

# sqlalchemy_sdb config
# Use new approach provided by SQLAlchemy Automap. If False then SlashDB 0.9.x method is used.
sqlalchemy_sdb.use_sqlalchemy_automap = True
sqlalchemy_sdb.yield_per = 10
# sqlalchemy reflect engine cho
sqlalchemy_sdb.engine_echo = False
# sqlalchemy mysql diver: mysql+[driver_name]://
sqlalchemy_sdb.mysql_driver = mysqldb
# per database SQLAlchemy engine config
sqlalchemy_sdb.db.Chinook.echo = True
sqlalchemy_sdb.db.Northwind.echo = True

# csv_sdb config
csv_sdb.stream_by_default = False
csv_sdb.headers_by_default = True

# html_sdb config
html_sdb.stream_by_default = False

# xml_sdb config
xml_sdb.root_tag = SlashDB
xml_sdb.xmlns = http://www.vtenterprise.com/slashdb
xml_sdb.nil_visible = True
xml_sdb.stream_by_default = False

# xsd_sdb config
xsd_sdb.stream_by_default = False

# json_sdb config
json_sdb.indent = 4
json_sdb.stream_by_default = False

# txt_xsd config
txt_sdb.nil_visible = False
txt_sdb.stream_by_default = False

[server:main]
use = egg:waitress#main
host = 0.0.0.0
port = 6543
threads = 2

[pipeline:main]
pipeline =
    cors
    sdbapp

[filter:cors]
use = egg:wsgicors#middleware
# CORS available policies
# "free" policy
free_origin=copy
free_headers=*
free_expose_headers=Set-Cookie, Warning
free_methods=HEAD, OPTIONS, GET, POST, PUT, DELETE
free_maxage=180
free_credentials=true

# CORS enabled policies
policy=free

# Logging

[loggers]
keys = root, slashdb, exc_logger, sqlalchemy

[handlers]
keys = console, filelog, exc_handler, mail_exc_handler

[formatters]
keys = generic, exc_formatter

[logger_root]
level = INFO
handlers = console, filelog

[logger_slashdb]
level = INFO
handlers = filelog
qualname = slashdb

[logger_exc_logger]
level = ERROR
handlers = exc_handler
# mail_exc_handler is for mailing errors, see its section
#handlers = exc_handler, mail_exc_handler
qualname = exc_logger

[logger_sqlalchemy]
level = DEBUG
handlers =
qualname = sqlalchemy

[logger_sqlalchemy_pool]
level = INFO
handlers =
qualname = sqlalchemy.pool

[handler_console]
class = StreamHandler
args = (sys.stderr,)
level = NOTSET
formatter = generic

[handler_filelog]
class = handlers.RotatingFileHandler
args = ('/var/log/slashdb/slashdb.log','a', 2*1024*1024, 5, 'utf-8')
level = INFO
formatter = generic

[handler_exc_handler]
class = handlers.RotatingFileHandler
args = ('/var/log/slashdb/exceptions.log','a', 2*1024*1024, 5, 'utf-8')
level = ERROR
formatter = exc_formatter

[handler_mail_exc_handler]
class = handlers.SMTPHandler
args = (('smtp.host.com', 25), 'from@email.com', ['to@email.com'], 'SlashDB Error', ('smtp_login', 'smtp_password'))
level = ERROR
formatter = exc_formatter

[formatter_exc_formatter]
format = %(asctime)s %(message)s

[formatter_generic]
format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
# End logging configuration


# uWSGI config for service scriptm starts uWSGI as a daemon
[uwsgi]
uid = vte
gid = vte
socket = 127.0.0.1:8001
virtualenv = /opt/slashdb
daemonize = /var/log/slashdb/uwsgi.log
log-maxsize = 20971520
master = true
enable-threads = true
single-interpreter = true
lazy = true
processes = 1
threads = 16
paste = config:%p
paste-logger = %p

# uWSGI config used when starting uWSGI from supervisord -runs uWSGI foreground. Used in docker container.
[docker-uwsgi]
uid = vte
gid = vte
socket = 127.0.0.1:8001
virtualenv = /opt/slashdb
logto = /var/log/slashdb/uwsgi.log
log-maxsize = 20971520
master = true
enable-threads = true
single-interpreter = true
lazy = true
processes = 1
threads = 16
paste = config:%p
paste-logger = %p

Just like with other configuration files, changes to this file require restating the SlashDB service:

sudo service slashdb restart

results matching ""

    No results matching ""