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

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

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.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

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

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

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

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

The settings of the uWSGI server are located in section [uwsgi].

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)