Add a Data Source
Before you can analyze data in Frappe Insights, you need to connect a data source. A data source can be a database, a CSV or Excel file, or your site’s built-in database. Once connected, the data becomes available for creating queries, charts, and dashboards.
Prerequisites
Before connecting a database, gather the required connection details from your database administrator. You must also have the Insights Admin role to create or manage data sources.
Required Connection Information
| Field | Description |
|---|---|
| Host | Database server address, such as db.mycompany.com or localhost. |
| Port | Database connection port (for example, 3306 for MariaDB/MySQL or 5432 for PostgreSQL). |
| Database Name | The name of the database you want to connect to. |
| Username | Database login username. |
| Password | Password for the specified database user. |
| SSL (Optional) | Enable if your database requires a secure SSL connection. |
Add a Database Data Source
Step 1: Open Data Sources
- Open the Data Sources page from the sidebar.
- Click + Add Data Source.
- Select the type of database you want to connect.
Step 2: Enter Connection Details
Fill in the required connection information.
Example (MariaDB):
- Title: A friendly name for the connection (for example, Production Database).
- Host: Database server address.
- Port: 3306 (automatically filled for MariaDB).
- Database Name: Database to connect to.
- Username: Database username.
- Password: Database password.
- Use SSL: Enable if required by your database server.
Step 3: Save the Connection
- Click Add Data Source.
- Insights validates the connection.
- If successful, the database tables become available for creating queries and reports.
Tip
Use descriptive names for your data sources, especially when managing multiple databases. This makes them easier to identify while building reports and dashboards.
Upload a CSV or Excel File
Uploading a spreadsheet is a quick way to analyze data without connecting to a database. This option is ideal for testing Insights or working with small datasets.
Upload a File
- Click + Add Data Source.
- Select Upload CSV or Excel.
- Choose a file or drag and drop it into the upload area.
- Preview the imported data.
- Rename the table if required.
- Click Import Table.
Supported Formats
- CSV (
.csv) - Excel (
.xlsx)
Maximum file size: 50 MB (may vary depending on your administrator’s configuration).
Best Practices
- Ensure the first row contains column headers.
- Use clear and descriptive column names.
- Keep date formats consistent throughout the file.
- Remove unnecessary blank rows before uploading.
Site Database (Auto-Configured)
When Insights is installed on the same Frappe site as ERPNext or another Frappe application, the site’s database is connected automatically.
This built-in data source provides immediate access to your application data without requiring any additional configuration.
Features
- No manual configuration required.
- No database credentials are needed.
- All DocTypes are available as database tables.
- Relationships between linked DocTypes are automatically configured.
Note
The Site Database is available only when Frappe Insights and your Frappe application are installed on the same site.
Troubleshooting
Connection Refused
Verify that the Host and Port are correct and that the database server is accessible.
Access Denied
Check that the database Username and Password are correct and that the user has permission to access the selected database.
Unknown Database
Ensure that the Database Name is entered correctly and that the database exists on the server.
