Skip to content

SlashDB Server Settings

The INI file /etc/slashdb/slashdb.ini is the core configuration file for setting up SlashDB.

The file contains settings for:

The SlashDB service must be restarted after making changes to the INI file for changes to take effect:

sudo systemctl restart slashdb

Below are detailed explanations of the options and examples.

SlashDB Settings

WSGI Application Entry Point

use - defines the entrypoint for WSGI application. Do not modify.

use = egg:slashdb

HTML Templates

mako.directories - path to the folder with GUI templates.

Value can be either a file system path to the folder with Mako templates for the GUI or a reference to a Python package.

Default: slashdb.formats.html_sdb:templates

Example:

mako.directories = /path/to/folder/with/templates

GUI Static Files

static_path - path to a folder containing GUI static files.

Normally SlashDB is delivered with static files being served by NGINX from folder /var/lib/slashdb/static and requests for static files don't reach the WSGI server.

Modify this option to use a different set of static files when running pserve.

Value can be either a file system path or a reference to a Python package.

Default: slashdb.formats.html_sdb:static

Example:

static_path = /var/lib/slashdb/static

Branding

branding.name - changes the product name in API.

The branding, by default SlashDB, is used in various places where the name of the API is needed. For example, the root tag for XML output or the header returned when using the count query parameter - SlashDB-All-Record-Count.

This value is also in the API settings endpoint https://demo.slashdb.com/settings.json under the key product.

The XML root tag in XML output can be also renamed for branding purposes using by setting the xml_sdb.root_tag option.

Default: SlashDB

Example:

branding.name = AwesomeAPI

Configuration Files

slashdb_env - path to the default folder with SlashDB configuration files. This value can be be used in other INI settings such as databases_path, users_path, querydefs_path, license, auth_config_path. 

slashdb_env = /etc/slashdb

databases_path - path to the file with database configurations.

Database configurations are stored in a YAML file in the /etc/slashdb folder. The path can be modified to point to another file if the configuration is stored in a different location.

Default: /etc/slashdb/databases.cfg

Example:

databases_path = /mnt/remote-storage/slashdb/databases.cfg

users_path - path to the location of the file with user configurations.

User configurations are stored in a YAML file in the /etc/slashdb folder. The path can be modified to point to another file if the configuration is stored in a different location.

Default: /etc/slashdb/users.cfg

Example:

users_path = /mnt/remote-storage/slashdb/users.cfg

querydefs_path - path to the file with query configurations.

Query configurations are stored in a YAML file in the /etc/slashdb folder. The path can be modified to point to another file if the configuration is stored in a different location.

Default: /etc/slashdb/querydefs.cfg

Example:

querydefs_path = /mnt/remote-storage/slashdb/querydefs.cfg

initial_state_path - path to the file that indicates if SlashDB has been initialized already.

This option tells SlashDB what file to use when running SlashDB for the first time. The file is removed by SlashDB after setting up the admin password. Don't modify this value unless configuration files are stored in a different folder than /etc/slashdb on first run.

Default: /etc/slashdb/regular-initial

Example:

initial_state_path = /mnt/remote-storage/slashdb/regular-initial

license - path to the file with license details.

This option tells SlashDB where to find the license file. The path can be modified to point to another file if the configuration is stored in a different location.

Default: /etc/slashdb/license.key

Example:

license = /mnt/remote-storage/slashdb/license.key

auth_config_path - path to the file with authentication settings.

This option tells SlashDB where to find the file with configuration of supported authentication methods like SAML, OpenID Connect, login form, cookies, JWT or API keys.

Typically the file is stored in the /etc/slashdb folder with other configuration files.

To find out more, see the chapter on Authentication in SlashDB

Default: No default path.

If the path is not provided, the default configuration is used, which enables authentication using the login form, cookies or API keys.

Example:

auth_config_path = /etc/slashdb/auth.cfg

Caching Database Models

caches_folder - path to the folder where reflected database models are cached.

This option tells SlashDB where it should store any schemas that are cached. If the given path does not exist, or is not usable for any reason, then there will be debug logs on startup warning that caching will not function without a valid path.

Default: /var/cache/slashdb/models/

Example:

caches_folder = /var/cache/slashdb/models/

Initial Setup

require_details_in_terms_and_conditions - makes accepting terms and conditions required in welcome slides for development license.

Default: True

Example:

Initial setup won't require accepting terms and conditions.

require_details_in_terms_and_conditions = False

registration_url - URL used to save user details when registering the product on initial startup. Do not modify.

session.secret - unique secret that is needed to create and preserve sessions securely when the SlashDB service is restarted.

Instances running in a cluster should have the same secret key. If a value is not set, sessions won't be preserved - users will be logged out after each service restart. The value for session.secret should be a long alphanumeric string. Secrets with 30 characters or longer are recommended.

Please generate a new secret for SlashDB instance and keep the production secret safe!

Default: Random value that is generated every time the service starts. As a result, sessions are not preserved.

Example:

session.secret = XaaJj6o9OpgR9PuqYKMxZ1ARA8Blmf

session.timeout - defines how long a non-active session is valid in seconds.

Default: 3600

Example:

Session that are inactive longer than 10 minutes will be invalidated.

session.timeout = 600

session.cookie_expires - defines how long a cookie is valid in seconds.

This is the maximum time a single session can last. This invalidates a session after the expiry time, regardless of the user's activity. By default, it is 24h.

Default: 86400

Example:

Forcefully end a session after 8h (28800 seconds).

session.cookie_expires = 28800

session.data_dir - path to a directory in the file system where user session data should be stored.

Default: /var/lib/slashdb/sessions/data

Example:

Session data will be stored in /tmp/sessions/data

session.data_dir = /tmp/sessions/data

session.lock_dir - path to a directory in the file system where session locks should be stored.

Default: /var/lib/slashdb/sessions/lock

Example:

Session locks will be stored in /tmp/sessions/lock

session.lock_dir = /tmp/sessions/lock

cookie_http_only - controls the HttpOnly flag that prevents browser scripts from accessing cookie data.

See Restrict access to cookies for details.

Default: True

Example:

cookie_http_only = True

cookie_secure - sets the cookie secure flag.

The value may be set to True, False or auto. When the value is auto, the secure flag is set automatically if the authentication request was sent using HTTPS protocol.

See Restrict access to cookies for details.

Default: auto

Example:

Always set the secure flag for session cookies. 

cookie_secure = True

Passwords

min_password_strength - sets the minimum password strength requirement.

Value is a number from 0 to 4. For more information please check the documentation on password strength

Default: 3

Example:

Allows use of simple passwords.

min_password_strength = 1

allow_empty_password - if True then user accounts can be configured with empty password.

Default: False

Example:

allow_empty_password = False

API Key

A user can be authenticated by passing an API key as a URL query string parameter or in a request header. The name of the parameter and header can be configured.

appid_name - name of the parameter that contains an app id for authentication using two parameters API key.

Default: appid

Example:

Changes the name of the app id parameter to AID

appid_name = AID

apikey_name - name of the parameter that contains an API key for authentication using API key.

Default: apikey

Example:

Changes the name of the API key parameter to AK

apikey_name = AK

Example:

Changed apikey_name to "secret".

# Query string/header parameter authentication.
# Two parameter credential authentication uses parameters appid and apikey (called app_id mode in 3Scale).
# Single parameter credential authentication uses parameter apikey(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

allow_apikey_in_query_string - whether to allow authentication through the apikey query string parameter. If set to False, authentication through the parameter will not be allowed and will result in a 403 Forbidden response.

It is recommended to set this value to False and instead authenticate through HTTP headers for better security.

Valid values: True or False.

Default: True

Example:

Disable authentication through the apikey query string parameter:

allow_apikey_in_query_string = False

Privilege hierarchy

userdef_enforce_privilege_hierarchy - controls whether privilege hierarchy should be enforced.

If enabled, a user can only create new users that have at most the same privileges as them and the user can't edit privileges of other users that they themselves don't have.

It is recommended to have this setting enabled, for better security of your application.

Default: False

Example:

Enable enforced privilege hierarchy:

userdef_enforce_privilege_hierarchy = True

Models package

models_package - defines where automatically reflected models are stored in package structure. Only for advanced setup.

models_package = slashdb.models

Memcached

SlashDB can work in either multi-thread or multi-process mode. When using multi-process mode, a memcached server must be configured to synchronize the various instances of SlashDB. See the UWSGI section for information on how to switch between these modes.

memcached_server - defines host and port where a memcached service is available. When defined and available, SlashDB instances and processes will be synchronized. This allows for horizontal scaling of the application.

Default: No default value.

Example:

SlashDB instances will be synchronized using Memcached server located at 127.0.0.1:11211

memcached_server = 127.0.0.1:11211

memcache_timeout - the maximum time in seconds SlashDB will wait to connect to memcached server before timing out.

Default: 15

Example::

Configure SlashDB to wait for up to 30 seconds for Memcached server.

memcache_timeout = 15

memcache_root_key - a prefix for keys stored in Memcached. A key prevents key name collisions and protects data from accidental overwrites by other processes that share the same Memcached server.

Default: slashb

Example:

Sets SDB17783 as the Memcached root key name for SlashDB instances.

memcache_root_key = SDB17783

memcache_lock_key - a key used for Memcached locking in SlashDB

A SlashDB process will put a lock on a Memcached server when updating the cache to prevent other SlashDB processes from making changes to the cache at the same time. The key used for this purpose can be customized.

Default: slashdb_registry_lock

Example:

The SlashDB lock will be identified in memcache as sdb123_lock. 

memcache_lock_key = sdb123_lock

memcache_lock_sleep_interval - maximum time between attempts to set SlashDB lock in Memcached.

The actual sleep is randomized from 0 to memcache_lock_sleep_interval in seconds.

By default the sleep can be between 0 and 0.1 s

Default: 0.1

Example:

Extends the sleep time to a random time from 0 to 1s.

memcache_lock_sleep_interval = 1

watch_registry_interval - defines how frequently (in seconds) each SlashDB process should be checking the shared registry for tasks waiting in the queue, like connect and disconnect requests.

Default: 3

Example:

Configure SlashDB process to check registry less frequently, every 10 seconds (useful if e.g. connects and disconnects are infrequent). 

watch_registry_interval = 10

JWT and SAML Timeouts

For details on JWT and SAML configuration, see the Authentication section.

jwt_sdb.http_timeout - maximum timeout in seconds for JWT HTTP operations.

Default: 1

Example:

Configure SlashDB to wait up to 2 seconds for HTTP requests made to IDP to verify the JWT.

jwt_sdb.http_timeout = 2

saml_sdb.http_timeout - maximum timeout in seconds for SAML HTTP operations.

Default: 5

Example:

Configure SlashDB to wait up to 10 seconds for HTTP requests made to IDP for SAML SSO authentication.

saml_sdb.http_timeout = 10

Amazon Configuration

amazon_host - hostname/IP of the internal EC2 Metadata API used by SlashDB to acquire the instance id or AMI id. This option should not need to be changed under normal circumstances.

Default: 169.254.169.254

Example:

Configures SlashDB to use 192.168.1.1 as EC2 API host when requesting EC2 Metadata.

amazon_host = 169.254.169.254

amazon_http_timeout - maximum timeout in seconds for requests made by SlashDB to the internal EC2 Metadata API. Since the internal API is very quick, this option should not need to be changed.

Default: 1

Example:

Configures SlashDB to wait up to 2 seconds for responses from the internal EC2 API.

amazon_http_timeout = 2

NULL in Data Discovery URL

datadiscovery.null_str - defines the default placeholder value for NULL values in URLs when filtering resources in Data Discovery.

For example, to filter the Customer resource by Company, where Company is NULL, the URL would look like: /db/Chinook/Customer/Company/<null>.

The default placeholder can be overridden per request using the query string parameter nullStr.

Default: <null>

Example:

Makes __NULL__ the default URL placeholder for NULL filtering. Filtering for records that have NULL for Company would look like: /db/Chinook/Customer/Company/__NULL__ 

datadiscovery.null_str = __NULL__

datadiscovery.common_null_empty_filtering - defines how NULL and empty string ('') values in URLs will be handled by SlashDB when filtering resources in Data Discovery mode.

When set to False (the default): - empty string values are passed onto the SQL database using equality comparison predicates for the value '' in the WHERE clause ("Column" (!)= ''). NULL values are passed onto the SQL database using the "Column" IS (NOT) NULL predicate in the WHERE clause.

When set to True: - for string data types: an empty string value in a URL will be converted to a predicate that includes both empty string and NULL values ("Column" (!)= '' OR "Column" IS (NOT) NULL) - for number or datetime data types: an empty string value in a URL will be converted to a "Column" IS (NOT) NULL predicate

If you want to include NULL values when providing empty string values in Data Discovery filtering queries, set this to True

e.g.: When set to False: - /db/Chinook/Customer/Company/.html will return all Customer records where the Company value is an empty string.

When set to True: - /db/Chinook/Customer/Company/.html will return all Customer records where the Company value is an empty string or is NULL.

Default: False

Example:

datadiscovery.common_null_empty_filtering = False

NULL in SQL Pass-thru URL

sqlpassthru.null_str - defines the default placeholder for NULL values in URLs when passing query parameters in SQL Pass-thru mode. Note that this value cannot be an empty string.

For example, to pass a NULL value for the query parameter FirstName using the add-new-customer query, the URL would look like: /query/add-new-customer/FirstName/<null>

Default: <null>

Example:

sqlpassthru.null_str = <null>

Data Discovery Connect/Retry Parameters

When SlashDB creates a DataDiscovery connection to a database, it needs to scan the schema and create a model in memory for DataDiscovery operations to function. During this scan, DataDiscovery requests cannot be processed. These parameters allow requests that arrive while the scan is happening to be retried a certain number of times before an error message is returned to the client.

datadiscovery.connecting_max_retries - The number of times a request should be retried before a 503 error is returned to the client.

Default: 4

Example:

datadiscovery.connecting_max_retries = 10

datadiscovery.connecting_retry_sleep - The number of seconds to wait between retry attempts. Note that this will pause the SlashDB worker process handling the request for the time period given.

Default: 3

Example:

datadiscovery.connecting_retry_sleep = 5

Database Connection

Configuration specific for sqlachemy_sdb component.

TDS Version for MS SQL

sqlalchemy_sdb.db.{db_id}.TDS_VERSION - defines the TDS Version that should be used for connecting to a specific database, identified by {db_id}.

Depending on the version of Microsoft SQL used in your environment, you may need to use a different version of the TDS driver.

Default: 7.4

Example:

Configures SlashDB to use TDS v7.1 when connecting to the database identified as msChinook.

sqlalchemy_sdb.db.msChinook.TDS_VERSION = 7.1

Connection parameters

Connections to the databases can be adjusted for either all databases of the same type or for a specific database.

Per Database Type

To apply a parameter for all databases of same type, use the below pattern:

sqlalchemy_sdb.{db_type}.engine.{parameter_name} = {parameter_value}

where

  • {db_type} is a database type. It should be one of the below database types:
    • sqlite for SQLite
    • sqlcipher for SQLCipher
    • mysql for MySQL
    • postgresql for PostgreSQL
    • mssql for MS SQL Server
    • oracle for Oracle
    • db2 for DB2
    • mariadb for MariaDB
    • snowflake for Snowflake
    • databricks for Databricks
  • {parameter_name} is the name of the parameter; valid parameters can be found here
  • {parameter_value} is the value for the parameter

Example:

Sets the number of connections that can be opened by each SlashDB user to 30 for MS SQL Server databases. 

sqlalchemy_sdb.mssql.engine.pool_size = 30

Makes the connection pool recycle every 3600s (1h) for MySQL databases.

sqlalchemy_sdb.mysql.engine.pool_recycle = 3600

Per Individual Database

To apply a parameter for an individual database, use the below pattern:

sqlalchemy_sdb.db.{db_id}.engine.{parameter_name} = {parameter_value}

where

Example:

Sets the number of connections that can be opened by each SlashDB user to 30 for database msChinook. 

sqlalchemy_sdb.db.msChinook.engine.pool_size = 30

Makes the connection pool recycle every 3600s (1h) for database Northwind.

sqlalchemy_sdb.db.Northwind.engine.pool_recycle = 3600

Parameters

These parameters can be applied per database type, or per individual database. If the same option is configured for a database type and an individual database, the more granular option (per individual database) overrides the more general option (per database type).

Common for all database types:
  • isolation_level - name of an isolation level which will be set on all new connections unconditionally. Isolation levels are typically a subset of strings "SERIALIZABLE", "REPEATABLE READ", "READ COMMITTED", "READ UNCOMMITTED" and "AUTOCOMMIT", based on what the backend database supports.
  • pool_size - the number of connections to keep open in the connection pool. Default is 5.
  • max_overflow - the number of connections to allow in connection pool “overflow”, that is connections that can be opened above and beyond the pool_size setting. Default is 10.
  • pool_timeout - number of seconds to wait before giving up on obtaining a connection from the pool. Default is 30.
  • pool_recycle - causes the pool to recycle connections after the given number of seconds has passed. Defaults is -1, which means no recycling.
  • pool_pre_ping - True will enable the connection pool “pre-ping” feature that tests and restores connections before attempts to use connections for queries.

There are several useful parameters for specific database types:

PostgreSQL
  • server_side_cursors - when True then named cursors are used on the server side which reduces memory used by SlashDB. False by default.
  • use_native_unicode - enables the usage of Psycopg2 “native unicode” mode per connection. True by default.
Oracle
  • encoding_errors - by default characters that raise encoding errors are replaced with character �.
  • auto_convert_lobs - converts LOB objects to strings
  • arraysize - set the cx_oracle.arraysize value on cursors, defaults to 50. This setting is significant with cx_Oracle as the contents of LOB objects are only readable within a “live” row (e.g. within a batch of 50 rows).
  • coerce_to_unicode
  • coerce_to_decimal
MS SQL Server
  • ignore_no_transaction_on_rollback - set True to avoid transaction-related exceptions on Azure Synapse Analytics.

Changing Database Driver

sqlalchemy_sdb.postgresql_driver - changes the DBAPI driver used for connecting to PostgreSQL databases.

Default: psycopg2

Example:

Use pg8000 for connecting to PostgreSQL databases.

sqlalchemy_sdb.postgresql_driver = pg8000

sqlalchemy_sdb.mysql_driver - changes the DBAPI driver used for connecting to MySQL databases.

Default: mysqldb

Example:

Use mysqlconnector for connecting to MySQL databases.

sqlalchemy_sdb.mysql_driver = mysqlconnector

sqlalchemy_sdb.mariadb_driver - changes the DBAPI driver used for connecting to MariaDB databases.

Default: mysqldb

Example:

Use mariadbconnector for connecting to MySQL databases.

sqlalchemy_sdb.mysql_driver = mariadbconnector

sqlalchemy_sdb.sqlite_driver - changes the DBAPI driver used for connecting to SQLite databases. Currently only pysqlite is supported.

Default: pysqlite

sqlalchemy_sdb.oracle_driver - changes the DBAPI driver used for connecting to Oracle databases. Currently only cx_Oracle is supported.

Default: cx_oracle

sqlalchemy_sdb.mssql_driver - changes the DBAPI driver used for connecting to Microsoft SQL Server databases.

Default: pyodbc

Example:

Use pymssql for connecting to MS SQL Server.

sqlalchemy_sdb.mssql_driver = pymssql

pyodbc.driver.mssql - changes the underlying driver used for connecting to Microsoft SQL Server databases when using the pyodbc DB API driver. The value should correspond to an entry in the /etc/odbcinst.ini file.

Default: the highest version of Microsoft ODBC driver installed on system. If not found, FreeTDS is used.

Example:

Use FreeTDS driver for connecting to MS SQL Server.

pyodbc.driver.mssql = FreeTDS

Reflecting Database Method

sqlalchemy_sdb.use_sqlalchemy_automap - if True, then database models are discovered using a reflection mechanism provided by SQLAlchemy Automap. If False, then a SlashDB v0.8.x legacy method is used.

Default: True

Example:

Makes SlashDB use the legacy method.

sqlalchemy_sdb.use_sqlalchemy_automap = False

Resource Relationship Naming

sqlalchemy_sdb.relationship_pattern - defines the pattern that is used for naming relationships between tables in the model.

In Data Discovery mode, related resources may be included in a result set.
This option allows you to define a pattern for naming the related resources.
The {this_table} and {other_table} placeholders will be replaced by the names of the retrieved resource and the related resource, respectively.
Using a custom pattern for naming can help to prevent resource name collisions (e.g. when a resource contains a column with the same name as a related resource).

Default: {other_table}

Example:

Configures SlashDB to represent relationships using both tables names and underscore.

Assume there is a relationship between two resources Customer and Invoice. The relationship will be named Customer_Invoice in records retrieved from the Customer resource.

sqlalchemy_sdb.relationship_pattern = {this_table}_{other_table}

Reflecting Views

sqlalchemy_sdb.reflect_nopk_views - when set to True, SlashDB will discover and create API endpoints for tables and views without primary keys just like regular tables with a primary key.

Default: True

Example:

Configure SlashDB to ignore tables and views without a primary key.

sqlalchemy_sdb.reflect_nopk_views = False

Tuning The Streaming

sqlalchemy_sdb.yield_per - defines number of rows that are processed at once when using streaming option for data retrieval.

For non-streaming responses, all rows in a response are fetched from the database at once, but for streaming responses the data is fetched incrementally to reduce memory use on the server. The parameter sqlalchemy_sdb.yield_per controls the number of rows that are fetched from the database per increment when streaming. Increasing this value will increase the memory use on the server during streaming operations.

Default: 250

Example:

Configure streaming responses to fetch 1000 rows at a time. 

sqlalchemy_sdb.yield_per = 1000

Connection Timeout

sqlalchemy_sdb.timeout - maximum time in seconds to wait before timing out when checking if connection to a database was successful.

Default: 3

Example:

Configure SlashDB to wait up to 5 seconds for database server to respond. 

sqlalchemy_sdb.timeout = 5

Default values

ignore_default_fields - controls if default value should be set by the database server.

If set to True, it will override the default behavior of the following columns:

  • In MS SQL, columns of TIMESTAMP type will be updated by the server, not by the provided value.

Default: False

Example:

ignore_default_fields = True

Default Limit

db.{db_id}.limit - defines a default row limit to prevent requests with unlimited rows. Configurable per database.

When not set, requests without limit in URL will fetch all rows.
When set, requests without limit in URL are redirected to URL with the defined limit.
The query string parameter limit overrides the default limit and allows to fetch more rows when needed.

To set the limit, add the option using the pattern db.{db_id}.limit = {n} where

  • {db_id} is the unique database id of the database that you want to apply the limit to
  • {n} maximum number of rows to return

Default: No limit.

Example:

Sets the default limit to 10000 rows for database Chinook.

db.Chinook.limit = 10000

Database Password Encryption

secret - defines a secret key that is used by SlashDB to encrypt database passwords in configuration files.

The secret can be defined in environment variable SLASHDB_SECRET which takes precedence over the INI setting secret.

When it is not set then passwords are stored in plain text.

The secret can be:

  • 32 alphanumeric characters or
  • 32 bytes encoded Base64

If SlashDB is configured with secret then all passwords are encrypted. That applies also to configuration files that were using plain text before secret was set. After setting the secret all plain text passwords are encrypted on SlashDB start.

When using a cluster of SlashDB instances that are synchronized via Memcached it is important to set the same secret on all instances.

Default: No encryption

Example:

Sets an alphanumeric secret. 

secret = w6T0MvIkOYIq1ZazUGIB59FWCa3Brt8Q

Sets a Base64 encoded secret

secret = tWwNWMXmCVk6Ribi-t3d5oaOl0j9zGpVaTB43dYkcZQ=

Decrypting passwords

The config files can be decrypted with the command /opt/slashdb/bin/slashdb-secret decrypt.

A secret to decrypt will be taken from environment variable or INI file. A decrypted version will overwrite the original configuration files.

Re-encrypting passwords

In case config files have to be re-encrypted with new secret the command /opt/slashdb/bin/slashdb-secret decrypt should be used.

A new secret is taken from environment variable or INI file. The command requires additional argument --old-secret to decrypt configuration files.

A typical update procedure should be as follows:

  1. Update the environment variable SLASHDB_SECRET or secret in the INI file with a new secret key.
  2. Run command with old secret
    /opt/slashdb/bin/slashdb-secret decrypt --old-secret [old secret key]

Example:

Using decrypt command with new secret in environment variable or INI file and the old secret w6T0MvIkOYIq1ZazUGIB59FWCa3Brt8Q passed as an argument to re-encrypt the configuration files.

/opt/slashdb/bin/slashdb-secret decrypt --old-secret w6T0MvIkOYIq1ZazUGIB59FWCa3Brt8Q

Allowed Connection String Parameters

By default, only connection string parameters that are used internally by SlashDB are allowed.

If you want to use a parameter that isn't allowed by default, you need to add it using the allowed_connection_string_parameters setting. This setting takes a list of comma separated names.

Default: empty list

Example:

Allow connection string parameters Options and Enlist.

allowed_connection_string_parameters = Options, Enlist

Allowed Localhost Database Ports

By default SlashDB blocks database connections to localhost. The behavior can be overridden in case a database is installed on the same host by providing a comma separated list of allowed ports in the ini option allowed_localhost_database_ports.

Default: empty list

Example:

Allow connection to databases on localhost on ports 1433 or 3306.

allowed_localhost_database_ports = 1433, 3306

Output Formats Settings

Settings related to rendering of result sets.

HTTP responses encoding

output_encoding - defines the character encoding of the output.

Default: utf-8

Example:

Makes output encoded in latin1.

output_encoding = latin1

General Stream by Default

stream_by_default - if set to True, then all responses in all formats will be streamed by default.

It is important to remember that HTML, XSD and TXT formats do not support streaming yet. If the general stream_by_default option is True, then the html_sdb.stream_by_default, xsd_sdb.stream_by_default and txt_sdb.stream_by_default options should be set to False.

Default: No default value.

Example:

Configure SlashDB to stream all responses by default.

stream_by_default = True

HTML / GUI

html_sdb.stream_by_default - controls if HTML responses should be streamed by default.

Since streaming responses are not implemented for HTML, this option is used only when the general stream_by_default option is True.

Default: False

Example:

Configure SlashDB to stream all responses except for HTML.

stream_by_default = True
html_sdb.stream_by_default = False

html_limit - limits the number of records returned by requests in the GUI (HTML). This parameter is added to every URI string: limit=29. Pagination is enabled so all records can be viewed. This option is enabled to prevent users from accidentally requesting records from a table that contains thousands of entries and could freeze their browser.

Default: 29

Examples:

Changes the default GUI record limit to 101. 

html_limit = 101

html_sdb.float_decimal_digits - defines rounding decimal precision for float values (i.e. the number of decimal digits appearing in HTML output).

Default: Maximum precision.

Example:

Configure SlashDB to round float values to 7 decimal digits. 

html_sdb.float_decimal_digits = 7

html_sdb.datadiscovery.null_display_str - defines what string will be used to display NULL values when retrieving resources in HTML format in Data Discovery mode.

Default: <null>

Example:

Makes NULL appear in Data Discovery in HTML format as __NULL__.

html_sdb.datadiscovery.null_display_str = __NULL__

html_sdb.datadiscovery.empty_display_str - defines what string will be used to display empty string values ('') when retrieving resources in HTML format in Data Discovery mode.

Default: The default value is an empty string.

Example:

Makes database values that are empty strings appear in Data Discovery in HTML format as __EMPTY__.

html_sdb.datadiscovery.empty_display_str = __EMPTY__

html_sdb.sqlpassthru.null_display_str - defines what string will be used to display NULL values when retrieving resources in HTML format in SQL Pass-thru.

Default: <null>

Example:

Makes NULL values appear in the SQL Pass-thru as __NULL__ 

html_sdb.sqlpassthru.null_display_str = __NULL__

html_sdb.sqlpassthru.empty_display_str - defines what string will be used to display empty string values ('') when retrieving resources in HTML format in SQL Pass-thru mode.

Default: The default value is an empty string.

Example:

Makes database values that are empty strings appear in SQL Pass-thru results in HTML format as __EMPTY__.

html_sdb.sqlpassthru.empty_display_str = __EMPTY__

JSON

refid_prefix - defines the name of the attribute for references in JSON.

This option defines the name of the attribute used in JSON format to store a resource URL. For example, the Artist resource has a __href attribute pointing to itself and to a related object list Album.

[
  {
    "Album": {
      "__href": "/db/Chinook/Artist/ArtistId/1/Album.json"
    },
    "ArtistId": 1,
    "Name": "AC/DC",
    "__href": "/db/Chinook/Artist/ArtistId/1.json"
  }
]

Default: __href

Example:

Set the JSON reference attribute name to be "__resource_url".

refid_prefix = __resource_url

json_sdb.href - if True, then JSON objects representing resources have additional an attribute with a path to the resource. The attribute name is defined in option refid_prefix.

Default: True

Example:

Configure SlashDB to not add a reference attribute to the resource in JSON format.

json_sdb.href = `False`

json_sdb.indent - the number of spaces used for JSON indentation. When set to None, or if the json_sdb.minimize parameter is set to True, the JSON output engine will generate JSON faster, which improves response times when requesting large result sets in JSON format.

Default: No default indentation.

Example:

Configure SlashDB to render JSON with indentation of 4 spaces.

json_sdb.indent = 4

json_sdb.minimize - when set to True, the rendered JSON has no indents or whitespace, which reduces the size of the final document. It will also increase the performance of the JSON output engine, which improves response times when requesting large result sets in JSON format.

Default: False

Example: True

Configure SlashDB to render minimized JSON.

json_sdb.minimize = True

json_sdb.scalar_object - when set to True, the rendered scalar values are wrapped in a JSON object structure. 

{
  "Name": "AC/DC"
}

When False then only the value itself is returned.

"AC/DC"

Default: True

Example:

Configure SlashDB to render JSON scalar with value only.

json_sdb.scalar_object = False

json_sdb.stream_by_default - if set to True, responses in JSON format are streamed by default.

Default: False

Example:

Configure SlashDB to stream JSON output by default.

json_sdb.stream_by_default = True

json_sdb.nan_inf_encoding - this parameter controls the JSON encoding behavior for floating point columns that contain nan (Not a Number), inf (positive infinity) or -inf (negative infinity) values. These values are recognized as valid floating point numbers according to the IEEE 754-1985 spec, and are supported in Postgresql, Oracle, and Snowflake databases. They may be present in floating point colums in Data Discovery, or in queries that return floating point columns in SQL Pass Thru.

For JSON data retrieval using GET requests:

  • when null: any column with these values will be converted to a Javascript null value - note that the data in the response may not conform to the schema for the data record if null values are not present in the schema definition for the columns in question.

  • when number: any column with these values will be encoded as Javascript NaN, Infinity or -Infinity - note that this may break standard JSON parsing utilities, since these values are not part of the official JSON specification

For JSON data uploads using POST or PUT requests:

  • when null: a 400 response will be returned when trying to parse NaN, Infinity or -Infinity values
  • when number: NaN, Infinity, and -Infinity values will be parsed and converted to values appropriate for the target database.
# GET request to a column with NaN/inf/-inf values
curl "http://slashdb/db/postgres-db/FloatTable/id/6.json"

# when set to null
{
    "__href": "/db/beta-postgres-dbtesting/FloatTable/id/6.json",
    "id": 6,
    "col_float": null,
    "col_real": null,
    "col_double": null
}

# when set to number
{
    "__href": "/db/beta-postgres-dbtesting/FloatTable/id/6.json",
    "id": 6,
    "col_float": NaN,
    "col_real": Infinity,
    "col_double": -Infinity
}

# PUT request to update a record with floating point columns with NaN/inf/-inf values
curl -X PUT "http://slashdb/db/postgres-db/FloatTable/id/6.json" -d '{"col_float": NaN, "col_real": Infinity, "col_double": -Infinity}'

# when set to null - 400 response
{"http_code": 400, "description": "ValueError | Expecting value: line 1 column 15 (char 14)"}

# when set to number - 204 response
HTTP/1.1 204 No Content

Default: null

Example:

Configure SlashDB to recognize Javascript NaN, Infinity, and -Infinity as values for floating point columns.

json_sdb.nan_inf_encoding = number

CSV

csv_sdb.stream_by_default - if set to True then responses in CSV format are streamed by default.

Default: False

Example:

Configure SlashDB to stream CSV output by default.

csv_sdb.stream_by_default = True

csv_sdb.headers_by_default - a switch that configures whether or not column headers are included in output in CSV format.

Default: True

Example:

Configures SlashDB to render CSV ouptut without headers by default.

csv_sdb.headers_by_default = False

csv_sdb.csv_null_str - a placeholder that represents NULL values in a CSV payload that is sent to SlashDB.

When an HTTP request with CSV data in the body is sent to SlashDB,empty values in the CSV are interpreted as empty strings by default. This option sets a value that should be treated as NULL when sending CSV data to SlashDB.

Default: No default placeholder for NULL values. Empty values are treated as empty strings.

Example:

Configure SlashDB to treat <null> strings in CSV data as NULL when committing to a database.

csv_sdb.csv_null_str = <null>

XML

xml_sdb.root_tag - name of the XML root tag in XML responses.

Default: SlashDB

Example:

Configure SlashDB to return <AwesomeAPI> as XML root tag in XML responses.

xml_sdb.root_tag = AwesomeAPI

xml_sdb.xmlns - defines XML namespace generated in XML responses.

Default: http://www.vtenterprise.com/slashdb

Example:

Changes the namespace in XML responses to http://my.custom.xml.namespace

xml_sdb.xmlns = http://my.custom.xml.namespace

xml_sdb.nil_visible - if set to True, items with NULL values will appear in the XML response as empty tags e.g. <Company/>. If set to False, NULL values are not rendered at all. This reduces the size of XML responses.

Default: False

Example:

Configure SlashDB to render NULL values as empty tags.

xml_sdb.nil_visible = True

xml_sdb.stream_by_default - if set to True, XML responses are streamed by default.

Default: False

Example:

Configure SlashDB to stream XML responses by default.

xml_sdb.stream_by_default = True

xml_sdb.href - if True, XML tags representing resources have an additional attribute href with a path to the resource e.g. 

<Customer href="/db/Chinook/Customer/CustomerId/2.xml">
    <CustomerId>1</CustomerId>    
</Customer>

Disabling this option reduces the size of XML responses.

Default: True

Example:

Configure SlashDB to not add references to XML responses by default.

xml_sdb.href = False

Using the above configuration, the Customer resource output would be:

<Customer>
    <CustomerId>1</CustomerId>    
</Customer>

xml_sdb.recordset_command_timeout - sets the value of the CommandTimeout property when retrieving XML records using the MS XML Persistance Format. The value is used when rendering XML in adPersistXMLformat

Default: 30

Example:

Configure SlashDB to render the XML Recordset attribute with CommandTimeout="60"

xml_sdb.recordset_command_timeout = 60

XSD

Deprecated - recommended to use xml_sdb.root_tag value

xsd_sdb.root_tag - defines the attribute name in the XML schema root element. This should match the xml_sdb.root_tag value.

Default: SlashDB

Example:

Configure SlashDB to render <xsd:element name="AwesomeAPI"> as the root tag in XML schema responses.

xsd_sdb.root_tag = AwesomeAPI

Deprecated - recommended to use xml_sdb.xmlns value

xsd_sdb.xmlns - defines the XML namespace generated in XML schema responses. This should match the xml_sdb.xmlns value.

Default: http://www.vtenterprise.com/slashdb

Example:

Changes the namespace in XML schema responses to http://my.custom.xml.namespace.

xsd_sdb.xmlns = http://my.custom.xml.namespace

Deprecated - recommended to use xml_sdb.stream_by_default value

xsd_sdb.stream_by_default - controls if XSD responses should be streamed by default.

Since streaming responses are not implemented for XSD, this option is used only when the general stream_by_default option is True.

Default: False

Example:

Configure SlashDB to stream all responses except for XSD.

stream_by_default = True
xsd_sdb.stream_by_default = False

TXT

Vector and scalar resource types have textual representation.

txt_sdb.nil_visible - if set to True, items with NULL values will appear in the TXT response as empty lines. If set to False, NULL values are not rendered at all. This reduces the size of the TXT response.

Default: False

Example:

Configure SlashDB to render NULL values in TXT output as empty lines.

txt_sdb.nil_visible = True

txt_sdb.stream_by_default - controls if TXT responses should be streamed by default.

Since streaming responses are not implemented for TXT, this option is used only when the general stream_by_default option is True.

Default: False

Example:

Configure SlashDB to stream all responses except for TXT.

stream_by_default = True
txt_sdb.stream_by_default = False

Logging Settings

This section is located between the lines labeled # Logging Settings and # End of Logging Settings and contains configuration for loggers, handlers and formatters. The format of this section is the standard file config for Python 3 logging.

For more details, see:

Log configuration is in Python configuration file format. The most important sections are [loggers], [handlers], [formatters] and several [logger_*], [handler_*] and [formatter_*].

The details on configuration of logs can be found here

Middleware Settings

These settings configure the WSGI middleware package that answers CORS preflight requests and adds headers to the response.

Middleware Entry Point

use - defines the middleware entry point. Do not modify.

CORS Settings

More information regarding these headers can be found here and here.

free_origin - sets the Access-Control-Allow-Origin header (indicates whether response can be shared with requesting code from the given origin)

Default: copy

free_headers - sets the Access-Control-Allow-Headers preflight header (indicates which HTTP headers can be used for a request)

Default: *

free_expose_headers - sets the Access-Control-Expose-Headers preflight header (allows server to indicate which response headers are available to scripts running in browser)

Default: Set-Cookie, Warning

free_methods - sets the Access-Control-Allow-Methods preflight header (specifies which methods are allowed for accessing a resource)

Default: HEAD, OPTIONS, GET, POST, PUT, DELETE

free_maxage - sets the Access-Control-Max-Age preflight header (how long the results of a preflight request can be cached, in seconds)

Default: 180

free_credentials - sets the Access-Control-Allow-Credentials preflight header (tell browser whether the server allows cross-origin HTTP requests to include credentials)

Default: true

policy - sets which CORS policies the middleware should use

Default: free

uWSGI Settings

The settings for the uWSGI server are located in the section labeled [uwsgi]. For full documentation on these settings, refer to the uWSGI Project Documentation.

Modifying these values can negatively affect performance or break the application if set incorrectly. If in doubt, leave the defaults.

socket - The IP and port that uWSGI should bind to.

Default: 127.0.0.1:8001

virtualenv - location of SlashDB's Python virtual environment

Default: /opt/slashdb

master - use the uWSGI built-in multi-worker management mode; workers are forked from a master process that is created on first execution.

Default: true

enable-threads - enable threading within uWSGI

Default: true

single-interpreter - load all applications using the same Python interpreter

Default: true

lazy-apps - loads application one time per worker

Default: true

need-app - prevent uWSGI from starting if it cannot find SlashDB application module

Default: true

processes - number of uWSGI processes to create

Default: 1

threads - number of threads to create per process

Default: 2

paste - use uWSGI with Pyramid INI configuration

Default: config:%p

paste-logger - use logging config as defined in Pyramid INI

Default: %p

vacuum - clean up temp files and sockets on shutdown

Default: true

auto-procname - create uWSGI processes with identifiable names

Default: true

procname-prefix-spaced - add specified prefix to uWSGI process names

Default: slashdb

master-fifo - location of file that uWSGI master process monitors for commands

Default: /run/slashdb/master-fifo

listen - size of uWSGI listen queue

Default: 100

Full INI file example

By default the file is located in /etc/slashdb/slashdb.ini

[app:sdbapp]

# Pyramid Settings
use = egg:slashdb
mako.directories = slashdb.formats.html_sdb:templates
static_path = slashdb.formats.html_sdb:static

# SlashDB Settings
branding.name = SlashDB
slashdb_env = /etc/slashdb
databases_path = %(slashdb_env)s/databases.cfg
users_path = %(slashdb_env)s/users.cfg
querydefs_path = %(slashdb_env)s/querydefs.cfg
initial_state_path = %(slashdb_env)s/regular-initial
license = %(slashdb_env)s/license.key
require_details_in_terms_and_conditions = True
auth_config_path = %(slashdb_env)s/auth.cfg
caches_folder = /var/cache/slashdb/models/

html_limit = 29
ignore_default_fields = False
refid_prefix = __href


# IMPORTANT: Please generate a new secret key for this SlashDB instance.
# Instances running in a cluster should have the same secret key.
# Keep the secret key used in production secret!
session.secret = 84eXRmVUdsMCRzSDycbLEQmej8wKRR

# How long a session is valid in sec.
session.timeout = 3600

# How long a cookie is valid in sec.
session.cookie_expires = 86400

# Where session data should be stored
session.data_dir = /var/lib/slashdb/sessions/data

# Where session locked data should be stored
session.lock_dir = /var/lib/slashdb/sessions/lock

# Cookie httpOnly and secure flags
cookie_http_only = True
cookie_secure = auto

# Password Authentication
# set password strength requirement from 0 to 4
min_password_strength = 3
allow_empty_password = False

# Memcached Server Settings
;memcached_server = 127.0.0.1:11211
;memcache_root_key = slashdb
# name of SlashDB memcache lock key
;memcache_lock_key = slashdb_registry_lock
# max time in seconds to wait before trying to access memcache when lock exists
;memcache_lock_sleep_interval = 0.1

# API Key Authentication Settings
# 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

# Should SlashDB stream data by default
stream_by_default = False

# Database Connection Settings
sqlalchemy_sdb.yield_per = 100
# sqlalchemy mysql diver: mysql+[driver_name]://
sqlalchemy_sdb.mysql_driver = mysqldb
sqlalchemy_sdb.reflect_nopk_views = True
# per database SQLAlchemy engine config
;sqlalchemy_sdb.db.Chinook.engine.pool_size = 1
;sqlalchemy_sdb.db.Chinook.engine.max_overflow = 0
;sqlalchemy_sdb.db.Chinook.engine.pool_recycle = 900
;sqlalchemy_sdb.db.Chinook.engine.pool_timeout = 10

# Default limit to prevent request with unlimited rows. Configurable per database.
# When not set, requests without limit in URL will fetch all rows.
# When set, requests without limit in URL are redirected to URL with the defined limit.
;db.Chinook.limit = 10000

# JWT Authentication Settings
# default timeout in seconds for JWT HTTP operations
jwt_sdb.http_timeout = 1

# SAML Authentication Settings
# default timeout in seconds for SAML HTTP operations
saml_sdb.http_timeout = 5

# Amazon Settings
amazon_host = 169.254.169.254
# default timeout in seconds for Amazon HTTP operations
amazon_http_timeout = 1

# HTML_SDB Settings
html_sdb.float_decimal_digits = 7

# JSON_SDB Settings
json_sdb.indent = 4
json_sdb.minimize = False
json_sdb.stream_by_default = False
json_sdb.href = True

# CSV_SDB Settings
csv_sdb.stream_by_default = False
csv_sdb.headers_by_default = True
;csv_sdb.csv_null_str = nil

# XML_SDB Settings
xml_sdb.root_tag = SlashDB
xml_sdb.xmlns = http://www.vtenterprise.com/slashdb
xml_sdb.nil_visible = True
xml_sdb.stream_by_default = False
xml_sdb.href = True
# default CommandTimeout in seconds when using adPersistXML option
xml_sdb.recordset_command_timeout = 30

# XSD_SDB Settings
xsd_sdb.root_tag = SlashDB
xsd_sdb.xmlns = http://www.vtenterprise.com/slashdb

# TXT_SDB Settings
txt_sdb.nil_visible = 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 Settings

[loggers]
keys = root, slashdb, exc_logger, sqlalchemy
# sqlachemy_engine, sqlachemy_pool

[handlers]
keys = file, file_slashdb, exc_handler

[formatters]
keys = generic, exc_formatter, slashdb

[logger_root]
level = INFO
handlers = file

[logger_slashdb]
level = INFO
handlers = file_slashdb
qualname = slashdb
propagate = 0

[logger_exc_logger]
level = ERROR
handlers = exc_handler
qualname = exc_logger
propagate = 1

[logger_sqlalchemy]
level = WARNING
handlers =
qualname = sqlalchemy
propagate = 1

[logger_sqlalchemy_engine]
level = INFO
handlers =
qualname = sqlalchemy.engine
propagate = 1

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

[handler_file]
class = handlers.WatchedFileHandler
args = ("/var/log/slashdb/slashdb.log",'a', 'utf-8')
level = NOTSET
formatter = generic

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

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

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

[formatter_slashdb]
format = %(asctime)-.19s | %(created)d%(msecs)03d | sdbapp | %(levelname)-5.5s | %(processName)s | %(threadName)s | %(name)s | %(module)s:%(funcName)s:%(lineno)d | %(user_id)s | %(message)s | pid: %(process)d

[formatter_generic]
format = %(asctime)-.19s | %(created)d%(msecs)03d | sdbapp | %(levelname)-5.5s | %(processName)s | %(threadName)s | %(name)s | %(module)s:%(funcName)s:%(lineno)d |  | %(message)s | pid: %(process)d

# End of Logging Settings


# uWSGI Server Settings
[uwsgi]
socket = 127.0.0.1:8001
virtualenv = /opt/slashdb
master = true
enable-threads = true
single-interpreter = true
lazy-apps = true
need-app = true
processes = 1
threads = 2

;harakiri = n                   ; Reload worker after n seconds waiting for response
;max-requests = n               ; Reload worker after n requests serviced
;max-worker-lifetime = n        ; Reload worker after n seconds
;reload-on-rss = n              ; Reload worker once resident memory goes over n megabytes
;evil-reload-on-rss = n         ; Reload worker forcefully once resident memory goes over n megabytes
;worker-reload-mercy = n        ; How long to wait before forcefully killing worker

paste = config:%p
paste-logger = %p
vacuum = true
auto-procname = true
procname-prefix-spaced = slashdb
master-fifo = /run/slashdb/master-fifo
listen = 100

# uWSGI Logging Settings
logto = /var/log/slashdb/uwsgi.log
logfile-chown = slashdb:slashdb
# 20 MB
log-maxsize = %(20 * 1024 * 1024)
log-encoder = format ${strftime:%%Y-%%m-%%d %%H:%%M:%%S} | ${millis} | uwsgi  | INFO  |  |  |  |  |  | ${msgnl}
# requests-logging
log-format = "%(method) %(uri) %(proto)" | pid: %(pid) wid: %(wid) | %(addr) | %(status) | %(secs) s |  | resp %(size) bytes | ipktsize: %(pktsize) bytes | reqbody: %(cl) bytes | %(headers) headers | in %(hsize) bytes | %(switches) switches | on core %(core)