Get Started
Setup
- Installation
- Configuration
- Learn more
Extend the Default MindsDB Configuration
To follow this guide, install MindsDB locally via Docker or PyPI.
Starting MindsDB with Default Configuration
Start MindsDB locally with the default configuration.
- Activate the virtual environment:
source mindsdb/bin/activate
- Start MindsDB:
python -m mindsdb
- Access MindsDB locally at
127.0.0.1:47334.
By default, MindsDB starts the http and mysql APIs. You can define which APIs to start using the api flag as below.
python -m mindsdb --api http,mysql,postgres,mongodb
If you want to start MindsDB without the graphical user interface (GUI), use the --no_studio flag as below.
python -m mindsdb --no_studio
Starting MindsDB with Extended Configuration
Start MindsDB locally with your custom configuration by providing a path to the config.json file that stores custom config parameters listed in this section.
python -m mindsdb --config=/path-to-the-extended-config-file/config.json
Below are all of the custom configuration parameters that should be set according to your requirements and saved into the config.json file.
{
"permanent_storage": {
"location": "absent",
"bucket": "s3_bucket_name" # optional, used only if "location": "s3"
},
The permanent_storage parameter defines where MindsDB stores copies of user files, such as uploaded files, models, and tab content. MindsDB checks the permanent_storage location to access the latest version of a file and updates it as needed.
The location specifies the storage type.
absent(default): Disables permanent storage and is recommended to use when MindsDB is running locally.local: Stores files in a local directory defined withconfig['paths']['storage'].s3: Stores files in an Amazon S3 bucket. This option requires thebucketparameter that specifies the name of the S3 bucket where files will be stored.
If this parameter is not set, the path is determined by the MINDSDB_STORAGE_DIR environment variable. MindsDB defaults to creating a mindsdb folder in the operating system user’s home directory.
"paths": {
"root": "/home/mindsdb/var", # optional (alternatively, it can be defined in the MINDSDB_STORAGE_DIR environment variable)
"content": "/home/mindsdb/var/content", # optional
"storage": "/home/mindsdb/var/storage", # optional
"static": "/home/mindsdb/var/static", # optional
"tmp": "/home/mindsdb/var/tmp", # optional
"cache": "/home/mindsdb/var/cache", # optional
"locks": "/home/mindsdb/var/locks", # optional
},
The paths parameter allows users to redefine the file paths for various groups of MindsDB files. If only the root path is defined, all other folders will be created within that directory. If this parameter is absent, the value is determined by the MINDSDB_STORAGE_DIR environment variable.
The root parameter defines the base directory for storing all MindsDB files, including models, uploaded files, tab content, and the internal SQLite database (if running locally).
The content parameter specifies the directory where user-related files are stored, such as uploaded files, created models, and tab content. The internal SQLite database (if running locally) is stored in the root directory instead.
If the ['permanent_storage']['location'] is set to 'local', then the storage parameter is used to store copies of user files.
The static parameter is used to store files for the graphical user interface (GUI) when MindsDB is run locally.
The tmp parameter designates a directory for temporary files. Note that the operating system’s default temporary directory may also be used for some temporary files.
If the ['cache']['type'] is set to 'local', then the cache parameter defines the location for storing cached files for the most recent predictions. For example, if a model is queried with identical input, the result will be stored in the cache and returned directly on subsequent queries, instead of recalculating the prediction.
The locks parameter is used to store lock files to prevent race conditions when the content folder is shared among multiple applications. This directory helps ensure that file access is managed properly using fcntl locks. Note that this is not applicable for Windows OS.
"auth":{
"http_auth_enabled": true,
"http_permanent_session_lifetime": 86400,
"username": "username",
"password": "password"
},
The auth parameter controls the authentication settings for APIs in MindsDB.
If the http_auth_enabled parameter is set to true, then the username and password parameters are required. Otherwise these are optional.
In local instances of MindsDB, users can enable simple HTTP authentication based on Flask sessions, as follows:
-
Enable the authentication for the HTTP API by setting the
http_auth_enabledparameter totrueand providing values for theusernameandpasswordparameters. Alternatively, users can set the environment variables -MINDSDB_USERNAMEandMINDSDB_PASSWORD- to store these values.. -
The default lifetime of a session is set to 31 days. It can be modified by providing a value in seconds to the
http_permanent_session_lifetimeparameter. Alternatively, users can set one of the environment variables -MINDSDB_HTTP_PERMANENT_SESSION_LIFETIMEorFLASK_PERMANENT_SESSION_LIFETIME- to store this value.
"gui": {
"autoupdate": true
},
The gui parameter controls the behavior of the MindsDB graphical user interface (GUI) updates.
The autoupdate parameter defines whether MindsDB automatically checks for and updates the GUI to the latest version when the application starts. If set to true, MindsDB will attempt to fetch the latest available version of the GUI. If set to False, MindsDB will not try to update the GUI on startup.
"api": {
"http": {
"host": "127.0.0.1",
"port": "47334",
"restart_on_failure": true,
"max_restart_count": 1,
"max_restart_interval_seconds": 60,
"server": {
"type": "server_type",
"config": {
// waitres
{
"threads": 16,
"max_request_body_size": (1 << 30) * 10, # 10GB
"inbuf_overflow": (1 << 30) * 10
}
// flask
{}
// gunicorn
{
'workers': min(multiprocessing.cpu_count(), 4),
'timeout': 600,
'reuse_port': True,
'preload_app': True,
'threads': 4
}
}
}
},
"mysql": {
"host": "127.0.0.1",
"port": "47335",
"database": "mindsdb",
"ssl": true,
"restart_on_failure": true,
"max_restart_count": 1,
"max_restart_interval_seconds": 60
},
"mongodb": {
"host": "127.0.0.1",
"port": "47336",
"database": "mindsdb"
}
},
The api parameter contains the configuration settings for running MindsDB APIs.
Currently, the supported APIs are:
http: Configures the HTTP API. It requires thehostandportparameters. Alternatively, configure HTTP authentication for your MindsDB instance by setting the environment variablesMINDSDB_USERNAMEandMINDSDB_PASSWORDbefore starting MindsDB, which is a recommended way for the production systems.mysql: Configures the MySQL API. It requires thehostandportparameters and additionally thedatabaseandsslparameters.mongodb: Configures the MongoDB API. It requires thehostandportparameters and additionally thedatabaseparameter.
Connection parameters within each block include:
host: Specifies the IP address or hostname where the API should run. For example,"127.0.0.1"indicates the API will run locally.port: Defines the port number on which the API will listen for incoming requests. The default ports are47334for HTTP,47335for MySQL, and47336for MongoDB.database(for MySQL and MongoDB): Specifies the name of the database that MindsDB uses. Users must connect to this database to interact with MindsDB through the respective API.ssl(for MySQL API): Indicates whether SSL support is enabled for the MySQL API.
Additional setup for the HTTP API and the MySQL API:
restart_on_failure: If it is set totrue(andmax_restart_countis not reached), the restart of MindsDB will be attempted after the MindsDB process was killed - with code 9 on Linux and MacOS, or for any reason on Windows.max_restart_count: This defines how many times the restart attempts can be made. Note that 0 stands for no limit.max_restart_interval_seconds: This defines the time limit during which there can be no more thanmax_restart_countrestart attempts. Note that 0 stands for no time limit, which means there would be a maximum ofmax_restart_countrestart attempts allowed.typewithinserver: This specifies the server type used by MindsDB. It iswaitressby default. Other values includeflaskandgunicorn. Alternatively, you can set theMINDSDB_DEFAULT_SERVERenvironment variable to define the server.configwithinserver: This stores the selected server configuration. Any options that are supported by the selected server (taht is, waitress, flask, or gunicorn) can be set there, except forhostandportthat are defined underconfig['api']['http'].
Here is a usage example of the restart features:
Assume the following values:
- max_restart_count = 2
- max_restart_interval_seconds = 30 seconds
Assume the following scenario:
- MindsDB fails at 1000s of its work - the restart attempt succeeds as there were no restarts in the past 30 seconds.
- MindsDB fails at 1010s of its work - the restart attempt succeeds as there was only 1 restart (at 1000s) in the past 30 seconds.
- MindsDB fails at 1020s of its work - the restart attempt fails as there were already max_restart_count=2 restarts (at 1000s and 1010s) in the past 30 seconds.
- MindsDB fails at 1031s of its work - the restart attempt succeeds as there was only 1 restart (at 1010s) in the past 30 seconds.
"cache": {
"type": "local",
"connection": "redis://localhost:6379" # optional, used only if "type": "redis"
},
The cache parameter controls how MindsDB stores the results of recent predictions to avoid recalculating them if the same query is run again. Note that recent predictions are cached for ML models, like Lightwood, but not in the case of large language models (LLMs), like OpenAI.
The type parameter specifies the type of caching mechanism to use for storing prediction results.
none: Disables caching. No prediction results are stored.local(default): Stores prediction results in thecachefolder (as defined in thepathsconfiguration). This is useful for repeated queries where the result doesn’t change.redis: Stores prediction results in a Redis instance. This option requires theconnectionparameter, which specifies the Redis connection string.
The connection parameter is required only if the type parameter is set to redis. It stores the Redis connection string.
"logging": {
"handlers": {
"console": {
"enabled": true,
"level": "INFO" # optional (alternatively, it can be defined in the MINDSDB_CONSOLE_LOG_LEVEL environment variable)
},
"file": {
"enabled": False,
"level": "INFO", # optional (alternatively, it can be defined in the MINDSDB_FILE_LOG_LEVEL environment variable)
"filename": "app.log",
"maxBytes": 524288, # 0.5 Mb
"backupCount": 3
}
}
},
The above parameters are implemented based on Python’s Logging Dictionary Schema.
The logging parameter defines the details of output logging, including the logging levels.
The handler parameter provides handlers used for logging into streams and files.
console: If theenabledparameter is set totrue, then the logging output is saved into a stream. Users can define the logging level in thelevelparameter or in theMINDSDB_CONSOLE_LOG_LEVELenvironment variable - one ofDEBUG,INFO,WARNING,ERROR,CRITICAL.file: If theenabledparameter is set totrue, then the logging output is saved into a file. Users can define the logging level in thelevelparameter or in theMINDSDB_FILE_LOG_LEVELenvironment variable - one ofDEBUG,INFO,WARNING,ERROR,CRITICAL. Additionally, thefilenameparameter stores the name of the file that contains logs, and themaxBytesandbackupCountparameters determine the rollover process of the file - that is, if the file reached the size ofmaxBytes, then the file is closed and a new file is opened, where the number of files is defined by thebackupCountparameter.
"ml_task_queue": {
"type": "local",
"host": "localhost", # optional, used only if "type": "redis"
"port": 6379, # optional, used only if "type": "redis"
"db": 0, # optional, used only if "type": "redis"
"username": "username", # optional, used only if "type": "redis"
"password": "password" # optional, used only if "type": "redis"
},
The ml_task_queue parameter manages the queueing system for machine learning tasks in MindsDB. ML tasks include operations such as creating, training, predicting, fine-tuning, and retraining models. These tasks can be resource-intensive, and running multiple ML tasks simultaneously may lead to Out of Memory (OOM) errors or performance degradation. To address this, MindsDB uses a task queue to control task execution and optimize resource utilization.
The type parameter defines the type of task queue to use.
local: Tasks are processed immediately as they appear, without a queue. This is suitable for environments where resource constraints are not a concern.redis: Tasks are added to a Redis-based queue, and consumer process (which is run with--ml_task_consumer) ensures that tasks are executed only when sufficient resources are available.- Using a Redis queue requires additional configuration such as the
host,port,db,username, andpasswordparameters. - To use the Redis queue, start MindsDB with the following command to initiate a queue consumer process:
python3 -m mindsdb --ml_task_queue_consumer. This process will monitor the queue and fetch tasks for execution only when sufficient resources are available.
- Using a Redis queue requires additional configuration such as the
"file_upload_domains": [],
The file_upload_domains parameter restricts file uploads to trusted sources by specifying a list of allowed domains. This ensures that users can only upload files from the defined sources, such as S3 or Google Drive ("file_upload_domains": ["https://s3.amazonaws.com", "https://drive.google.com"]).
If this parameter is left empty ([]), users can upload files from any URL without restriction.
"web_crawling_allowed_sites": [],
The web_crawling_allowed_sites parameter restricts web crawling operations to a specified list of allowed IPs or web addresses. This ensures that the application only accesses pre-approved and safe URLs ("web_crawling_allowed_sites": ["https://example.com", "https://api.mysite.com"]).
If left empty ([]), the application allows access to all URLs by default (marked with a wildcard in the open-source version).
The default_llm parameter specifies the default LLM that will be used with knowledge bases, the LLM() function, the TO_MARKDOWN() function, and agents.
"default_llm": {
"provider": "azure_openai",
"model_name" : "gpt-4o",
"api_key": "sk-abc123",
"base_url": "https://ai-6689.openai.azure.com/",
"api_version": "2024-02-01",
"method": "multi-class"
}
Learn more about the parameters following the documentation of the reranking_model of knowledge bases.
The default_embedding_model parameter specifies the default embedding model used with knowledge bases.
"default_embedding_model": {
"provider": "azure_openai",
"model_name" : "text-embedding-3-large",
"api_key": "sk-abc123",
"base_url": "https://ai-6689.openai.azure.com/",
"api_version": "2024-02-01"
}
}
Learn more about the parameters following the documentation of the embedding_model of knowledge bases.
First, create a config.json file.
{
"permanent_storage": {
"location": "absent"
},
"paths": {
"root": "/path/to/root/location"
},
"auth":{
"http_auth_enabled": true,
"http_permanent_session_lifetime": 86400,
"username": "username",
"password": "password"
},
"gui": {
"autoupdate": true
},
"api": {
"http": {
"host": "127.0.0.1",
"port": "47334",
"restart_on_failure": true,
"max_restart_count": 1,
"max_restart_interval_seconds": 60
},
"mysql": {
"host": "127.0.0.1",
"port": "47335",
"database": "mindsdb",
"ssl": true,
"restart_on_failure": true,
"max_restart_count": 1,
"max_restart_interval_seconds": 60
},
"mongodb": {
"host": "127.0.0.1",
"port": "47336",
"database": "mindsdb"
}
},
"cache": {
"type": "local"
},
"logging": {
"handlers": {
"console": {
"enabled": true,
"level": "INFO"
},
"file": {
"enabled": false,
"level": "INFO",
"filename": "app.log",
"maxBytes": 524288,
"backupCount": 3
}
}
},
"ml_task_queue": {
"type": "local"
},
"file_upload_domains": [],
"web_crawling_allowed_sites": []
}
Next, start MindsDB providing this config.json file.
python -m mindsdb --config=/path-to-the-extended-config-file/config.json
Modifying Config Values
Users can modify config values by directly editing the config.json file they created.
Was this page helpful?