Adding Databases

​

Introduction

​

Supported Databases

• PostgreSQL: Full SQL support, enterprise-grade features
• MySQL: Popular open-source database
• SQLite: File-based database, perfect for local development
• MongoDB: NoSQL document database

​

Connection Methods

• Go to Databases in the sidebar, then Add Connection

• Edit db_connections.json directly (see file location below)

• macOS: ~/Library/Application Support/DBFlow/db_connections.json
• Linux: ~/.config/dbflow/db_connections.json
• Windows: %APPDATA%\DBFlow\db_connections.json

​

PostgreSQL

​

Connection Parameters

• Connection Name: Unique identifier (e.g., “production_postgres”)
• Host: Database server address (e.g., “localhost” or “db.example.com”)
• Port: Usually 5432 (default PostgreSQL port)
• Database Name: Name of your database (e.g., “mydb”)
• Username: Database user (e.g., “postgres”)
• Password: User password

• SSL Mode: Enable for secure connections
• Application Name: Identifies DBFlow in PostgreSQL logs

​

Example

Connection Name: local_postgres
Database Type: postgresql
Host: localhost
Port: 5432
Database Name: myapp
Username: postgres
Password: mypassword123

​

MySQL

​

Connection Parameters

• Connection Name: Unique identifier
• Host: Database server (e.g., “localhost”)
• Port: Usually 3306 (default MySQL port)
• Database Name: Your database name
• Username: Database user
• Password: User password

​

Example

Connection Name: local_mysql
Database Type: mysql
Host: localhost
Port: 3306
Database Name: myapp
Username: root
Password: mypassword

​

SQLite

​

Connection Parameters

• Connection Name: Unique identifier
• Database Name: Path to SQLite file

​

Example

Connection Name: local_sqlite
Database Type: sqlite
Database Name: ./data/mydb.sqlite

​

File Path Tips

• Relative: ./data/mydb.sqlite (relative to where DBFlow is running)
• Absolute (macOS/Linux): /home/username/data/mydb.sqlite
• Absolute (Windows): C:\Users\YourName\data\mydb.sqlite

​

MongoDB

​

Connection Parameters

• Connection Name: Unique identifier
• Host: MongoDB server (e.g., “localhost”)
• Port: Usually 27017 (default MongoDB port)
• Database Name: Database name
• Username: MongoDB user (if authentication is enabled)
• Password: User password (if authentication is enabled)

• Auth Source: Authentication database (usually “admin”)

​

Example

Connection Name: local_mongo
Database Type: mongodb
Host: localhost
Port: 27017
Database Name: myapp
Username: (leave empty if no auth)
Password: (leave empty if no auth)

​

Managing Multiple Databases

​

Switching Between Databases

• “Switch to production_db”
• “Use database my_postgres”
• “Switch to production_db and show me all tables”

​

Verifying Connections

​

Troubleshooting

​

Connection Refused

• Verify the database is running:
  • PostgreSQL: pg_isready or sudo systemctl status postgresql
  • MySQL: sudo systemctl status mysql or mysqladmin ping
  • MongoDB: mongosh --eval "db.adminCommand('ping')" or sudo systemctl status mongod
• Check that the host and port are correct
• Ensure firewall rules allow connections on the database port
• For remote databases, verify security groups or network access rules allow your IP

​

Authentication Failed / Access Denied

• Double-check username and password
• Verify the user exists and has permissions to connect to the specified database
• PostgreSQL: Check pg_hba.conf for allowed connection methods
• MySQL: Run SHOW GRANTS FOR 'username'@'host'; to verify permissions
• MongoDB: Verify the auth source is correct (usually “admin”) and run db.getUsers() to confirm the user exists

​

Database Does Not Exist

• Verify the database name is correct (check for typos)
• Create the database if needed: CREATE DATABASE mydb;
• Ensure the user has access to the database

​

Connection Timeout

• Check general network connectivity — can you reach the host? (ping db.example.com)
• Verify firewall rules on both ends
• For cloud databases, ensure your IP is whitelisted and security groups are configured

​

SSL/TLS Errors

• Cloud-hosted databases (especially MongoDB Atlas) often require SSL
• Enable SSL in the connection settings if available
• For development environments, you may be able to configure the database to allow non-SSL connections

​

SQLite: File Not Found or Permission Denied

• The parent directory must exist — create it with mkdir -p ./data/ if needed
• Ensure DBFlow has read/write access to both the file and its directory:
  Copy

  chmod 664 database.sqlite
  chmod 755 ./data/
  
• If the database is locked, close other applications using the file

​

Platform-Specific Issues

• Windows: Check that the database service is running in Services and that Windows Firewall / antivirus aren’t blocking connections
• macOS: Check if the service is running with brew services list and verify firewall settings
• Linux: Check service status with systemctl and firewall with sudo ufw status

​

Still Stuck?

1. Try connecting with a standalone database client (psql, mysql, mongosh) to rule out DBFlow-specific issues
2. Check the database server logs for more detail
3. Delete and re-add the connection with corrected information
4. Contact support@dbflow.ai if issues persist

​

Next Steps

1. Verify the connection - If you see “Connection added successfully”, it’s working
2. Switch to the connection - Click on it in the Databases view to make it active
3. View tables - Click the chevron icon to expand and see available tables
4. Run your first query - See User Guide for query examples

• User Guide - Complete user guide
• API Keys Setup - Setting up API keys

• Check error messages for specific guidance
• Verify database is accessible with a database client first
• Ensure credentials and connection details are correct
• Contact support@dbflow.ai if issues persist