> ## 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**
* **Tip:** you can paste a full connection URI (e.g. `postgresql://user:pass@host/db`, a Neon/Supabase connection string, or a MongoDB Atlas `mongodb+srv://` URI) straight into the **Host** field — DBFlow splits it into the individual fields for you

**Manual Method:**

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

### No Database Handy? Try the Demo

If you just want to explore DBFlow before connecting real data, open **Databases** and click **"…or try the demo database"** (shown when you have no connections yet). This adds `demo_retail` — a bundled SQLite dataset with customers, products, orders, and order items spanning a full year — and makes it active, so you can immediately try queries like:

```
Show me monthly revenue as a bar chart
```

```
Which product category sells best?
```

The demo is copied into your user data directory, so it's safe to experiment with, and you can delete it like any other connection when you're done.

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

Use an absolute path, or a `~`-path (expanded automatically):

* **macOS/Linux:** `/Users/yourname/data/mydb.sqlite` or `~/data/mydb.sqlite`
* **Windows:** `C:\Users\YourName\data\mydb.sqlite`

The file must already exist — DBFlow is a read-only query tool and will not create a new database file, so a typo in the path fails with a clear error instead of silently connecting to an empty database.

***

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

***

## SSH Tunnels

If your database isn't directly reachable — it only accepts connections from inside a private network, a VPC, or the database server itself — DBFlow can connect through an SSH tunnel (a "bastion" or "jump host").

When adding or editing a connection, toggle **Connect via SSH tunnel** and fill in:

* **SSH Host** — the bastion/jump server address
* **SSH Port** — usually 22
* **SSH User** — your user on the SSH server
* **Authentication** — one of:
  * **Private key** (recommended) — pick your key file (e.g. `~/.ssh/id_ed25519`) with the file picker; add the passphrase if the key has one
  * **Password** — your SSH user's password

Enter the database's **Host** and **Port** as they appear *from the SSH server's point of view* — often `localhost:5432` when the database runs on the bastion itself, or the private/internal address inside the VPC.

SSH passwords and key passphrases are stored in your OS keychain, like database credentials — never in plain-text config files. The tunnel is established automatically whenever the connection is used.

**Strict host key checking** is off by default for convenience. Security-sensitive deployments can enable it by setting the environment variable `DBFLOW_SSH_STRICT_HOST_KEYS=1`, which verifies the SSH server against your `~/.ssh/known_hosts`.

***

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

### SSH Tunnel Failures

* Test the tunnel manually first: `ssh -L 15432:localhost:5432 user@bastion` then connect a client to `localhost:15432`
* Verify the key file path and that the key isn't rejected (`ssh -i /path/to/key user@bastion`)
* Remember the database Host/Port are resolved **from the SSH server** — `localhost` there means the bastion, not your machine
* If you enabled `DBFLOW_SSH_STRICT_HOST_KEYS=1`, make sure the host is in `~/.ssh/known_hosts` (connect once with plain `ssh` to add it)

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