> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dbflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Adding Databases

> How to connect databases to dbflow.ai

## Introduction

DBFlow supports multiple database types and allows you to manage several database connections simultaneously. You can add databases through the user interface or manually via configuration files.

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

**UI Method (Recommended):**

* Go to **Databases** in the sidebar, then **Add Connection**

**Manual Method:**

* Edit `db_connections.json` directly (see file location below)

**Where is `db_connections.json`?**
Connections are stored in the app's user data directory:

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

***

## PostgreSQL

PostgreSQL is a powerful, open-source relational database system.

### Connection Parameters

**Required:**

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

**Optional:**

* **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
```

For **remote or cloud databases** (AWS RDS, DigitalOcean, Azure, GCP), replace `localhost` with the provided endpoint URL (e.g., `db-1234.us-east-1.rds.amazonaws.com`) and use your cloud-provided credentials. Cloud connections may require SSL — this is typically handled automatically, but verify your server's SSL settings if the connection fails.

***

## MySQL

MySQL is a widely-used open-source relational database.

### Connection Parameters

**Required:**

* **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
```

For **remote or cloud databases**, replace `localhost` with the provided endpoint and use your cloud-provided credentials. XAMPP/WAMP users typically connect with `root` and an empty or default password.

***

## SQLite

SQLite is a file-based database — no host, port, or credentials needed. Just provide a path to the database file.

### Connection Parameters

**Required:**

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

You can use relative or absolute paths:

* **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`

SQLite will create the file if it doesn't exist, but the parent directory must already exist.

***

## MongoDB

MongoDB is a NoSQL document database that stores data in JSON-like documents.

### Connection Parameters

**Required:**

* **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)

**Optional:**

* **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)
```

If authentication is enabled, provide your username, password, and set **Auth Source** to `admin` (or your auth database).

For **MongoDB Atlas**, use the cluster connection string as the host (e.g., `cluster0.xxxxx.mongodb.net`), provide your database user credentials, and ensure your IP address is whitelisted in the Atlas dashboard. Atlas requires SSL/TLS, which is typically handled automatically.

***

## Managing Multiple Databases

You can add as many database connections as you need. Go to **Databases** in the sidebar to see all your connections, their type, host, and status.

Only one connection is **active** at a time — this is the database that gets queried. Active connections show a green indicator; inactive connections show gray.

### Switching Between Databases

**From the UI:** Click on any connection in the Databases view to make it active.

**Via chat:** Ask DBFlow to switch using natural language:

* "Switch to production\_db"
* "Use database my\_postgres"
* "Switch to production\_db and show me all tables"

Switching is instant and doesn't require reconnection.

***

## Verifying Connections

Connections are automatically tested when you add them. If successful, you'll see "Connection added successfully." If it fails, you'll see an error message explaining what went wrong.

To manually verify a connection is working, switch to it in the Databases view, click the chevron icon to expand and view tables, or run a simple query like "List all tables."

***

## Troubleshooting

### Connection Refused

The database server isn't reachable at the specified host and port.

* 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

Credentials are incorrect or the user lacks permissions.

* 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:
  ```bash theme={null}
  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](mailto:support@dbflow.ai) if issues persist

***

## Next Steps

After adding your database:

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](/introduction) for query examples

For more information:

* [User Guide](/introduction) - Complete user guide
* [API Keys Setup](/API_KEYS_SETUP) - Setting up API keys

***

**Need Help?**

* 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](mailto:support@dbflow.ai) if issues persist