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

# Connecting your own database to MSP Recapp

> Free-tier workspaces must provide a PostgreSQL 14+ database. Learn how to connect your own database and which providers work best with MSP Recapp.

MSP Recapp stores all operational data — integrations, synced devices, organizations, and mappings — in a PostgreSQL database. On the **Free plan**, you bring your own PostgreSQL 14+ database (BYOD). **Starter**, **Pro**, and **Enterprise** plans include a managed database hosted and maintained by MSP Recapp, so no database setup is required on those plans.

If you are on the Free plan and have not yet connected a database, most features that read or write operational data will not work until you complete this setup.

<Tip>
  Upgrading to the Starter plan (\$20/mo) or higher removes the database requirement entirely — MSP Recapp provisions and manages the database for you.
</Tip>

## Supported database providers

You can use any PostgreSQL 14+ host. The following providers have been tested and work well:

<CardGroup cols={2}>
  <Card title="Supabase" icon="database" href="https://supabase.com">
    Free tier includes a PostgreSQL database. Create a project, grab the connection string from the project settings, and you're ready.
  </Card>

  <Card title="Neon" icon="database" href="https://neon.tech">
    Serverless PostgreSQL with a generous free tier and automatic scaling. Recommended for getting started quickly.
  </Card>

  <Card title="Railway" icon="database" href="https://railway.app">
    Developer-focused platform with a PostgreSQL plugin. Simple setup with a built-in connection string viewer.
  </Card>

  <Card title="Any PostgreSQL 14+ host" icon="server">
    Self-hosted, AWS RDS, Google Cloud SQL, Azure Database for PostgreSQL — any host that supports standard PostgreSQL connections works.
  </Card>
</CardGroup>

## Connect your database

<Steps>
  <Step title="Create a PostgreSQL 14+ database">
    Sign up with Supabase, Neon, Railway, or your preferred provider and create a new PostgreSQL database. Note down the **host**, **port** (usually `5432`), **database name**, **username**, and **password**.
  </Step>

  <Step title="Go to Settings > Database">
    In MSP Recapp, open **Settings** from the main navigation and click the **Database** tab.
  </Step>

  <Step title="Enable the external database toggle">
    Switch on **Use External Database**. The connection form appears below the toggle.
  </Step>

  <Step title="Enter connection details">
    Fill in the following fields:

    | Field         | Example                |
    | ------------- | ---------------------- |
    | Host          | `db.xxxx.supabase.co`  |
    | Port          | `5432`                 |
    | Database Name | `postgres`             |
    | Username      | `postgres`             |
    | Password      | Your database password |
  </Step>

  <Step title="Test the connection">
    Click **Test Connection**. MSP Recapp attempts to connect to your database and reports success or failure. You must see a successful test before you can save.
  </Step>

  <Step title="Initialize the schema">
    After a successful test, an **Initialize Schema** button appears. Click it to create the required tables in your database. Only run this once when setting up a new database.
  </Step>

  <Step title="Save">
    Click **Save Database Settings**. Your workspace is now connected and operational data will flow to your external database.
  </Step>
</Steps>

## What data is stored where

MSP Recapp splits data between two storage layers:

| Data type                          | Stored in                    |
| ---------------------------------- | ---------------------------- |
| Integrations and synced devices    | Your external database       |
| Organizations and mappings         | Your external database       |
| Scheduled reports                  | Your external database       |
| Dismissed discrepancies            | Your external database       |
| Tenant metadata (name, slug, plan) | MSP Recapp platform database |
| Encrypted database credentials     | MSP Recapp platform database |

Your database credentials are encrypted with **AES-256-GCM** server-side before being stored. They are never saved or transmitted to client-side storage.

## Switching from managed to BYOD

If you are on a Pro or Enterprise plan and want to move to your own database, the Database tab shows a **Switch to Your Own Database** option. Enter and verify your target database connection, optionally enable **Migrate existing data**, then confirm the switch.

<Warning>
  Switching from a managed database to your own database will cancel your current Pro or Enterprise subscription and move your workspace to the Free plan immediately. Your managed database is preserved for 30 days after the switch.
</Warning>

## Troubleshooting connection failures

If the connection test fails, verify the following:

* The **host** value does not include a protocol prefix (`postgresql://` or `postgres://`). Enter only the hostname.
* The **port** is open and accessible from external networks. Some providers require you to allow external connections in their dashboard or firewall settings.
* The **username** and **password** are correct. Copy them directly from your provider's dashboard to avoid typos.
* If your provider uses SSL, ensure SSL is enabled on the database — MSP Recapp connects with `sslmode=require`.

For more specific error messages, see [Troubleshoot common MSP Recapp issues](/troubleshooting).