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

# Set Up a Database for Your Site

> Provision a PostgreSQL database or bring your own

If your site needs to store data — users, posts, orders, form submissions — you'll want a database. Hiveku gives you three options.

<CardGroup cols={3}>
  <Card title="No Database" icon="circle-minus">
    Best for static sites
  </Card>

  <Card title="Hiveku Database" icon="database">
    PostgreSQL, managed for you
  </Card>

  <Card title="Bring Your Own" icon="link">
    Use Supabase, Neon, etc.
  </Card>
</CardGroup>

## Option 1: No Database

If your site is marketing pages, a blog, or portfolio — you probably don't need a database. Pick this during project creation and skip the rest.

You can always add one later from **Settings > Database**.

## Option 2: Hiveku Database (Managed PostgreSQL)

We provision and manage a PostgreSQL instance for your project.

<Steps>
  <Step title="Enable during project creation">
    When creating a new project, pick **Hiveku Database** in the database step.

    Already have a project? Go to **Settings > Database** and click **Provision Database**.
  </Step>

  <Step title="Wait for provisioning">
    Takes about 30-60 seconds. You'll see status updates in the UI.
  </Step>

  <Step title="Confirm DATABASE_URL is set">
    Hiveku auto-injects a `DATABASE_URL` environment variable into your container. You don't need to copy or paste anything — just use `process.env.DATABASE_URL` in your code.
  </Step>
</Steps>

## Option 3: Bring Your Own Database (BYOD)

If you already use Supabase, Neon, PlanetScale, Railway, or any PostgreSQL-compatible provider, paste the connection string.

<Steps>
  <Step title="Copy your connection string">
    From your existing provider, grab the connection string. It looks like:

    ```
    postgresql://user:password@host:5432/dbname
    ```
  </Step>

  <Step title="Paste into Hiveku">
    Go to **Settings > Database** and select **Bring Your Own**. Paste the connection string and save.
  </Step>

  <Step title="Test the connection">
    Click **Test Connection**. Hiveku verifies the credentials and sets `DATABASE_URL` in your environment.
  </Step>
</Steps>

<Info>
  BYOD means you manage your own backups, scaling, and billing on the provider side. Hiveku just connects.
</Info>

## Using the Database in Code

Once a database is connected, `DATABASE_URL` is available as an env var.

<Tabs>
  <Tab title="Prisma">
    ```typescript theme={null}
    import { PrismaClient } from "@prisma/client";

    const prisma = new PrismaClient();
    // Reads process.env.DATABASE_URL automatically
    ```
  </Tab>

  <Tab title="Drizzle">
    ```typescript theme={null}
    import { drizzle } from "drizzle-orm/node-postgres";
    import { Pool } from "pg";

    const pool = new Pool({ connectionString: process.env.DATABASE_URL });
    export const db = drizzle(pool);
    ```
  </Tab>

  <Tab title="Plain pg">
    ```typescript theme={null}
    import { Pool } from "pg";

    const pool = new Pool({ connectionString: process.env.DATABASE_URL });
    ```
  </Tab>
</Tabs>

## The SQL Editor

Run queries directly from the browser.

<Steps>
  <Step title="Open the Database tab">
    In your project, click **Database** in the sidebar.
  </Step>

  <Step title="Pick SQL Editor">
    The editor is a full-featured Postgres console — autocomplete, history, and query saving.
  </Step>

  <Step title="Run a test query">
    Try:

    ```sql theme={null}
    SELECT 1;
    ```

    You should see `1` in the result panel.
  </Step>
</Steps>

## Let the AI Create Tables

The fastest way to set up schema is to ask.

```
Create a users table with email, name, and created_at
```

```
Add a posts table with title, slug, content, author_id, and published_at
```

The AI writes the migration, runs it, and shows you the schema.

## Backups

<Tabs>
  <Tab title="Automatic">
    Hiveku Database takes **daily automatic backups** with a rolling retention window. View and restore from **Settings > Database > Backups**.
  </Tab>

  <Tab title="Manual">
    Trigger a backup any time by clicking **Create Backup** on the Backups page. Great before a risky migration.
  </Tab>

  <Tab title="Checkpoints">
    Before big changes, the AI can create an **instant checkpoint** — a lighter-weight snapshot you can roll back to in seconds.
  </Tab>
</Tabs>

## Connection Pooling

For serverless deploys, always use a pooler to avoid exhausting connection limits.

Add pooling params to your connection string:

```
postgresql://user:password@host:5432/dbname?connection_limit=15&pool_timeout=30
```

* `connection_limit=15` — max concurrent connections per instance
* `pool_timeout=30` — seconds to wait for a connection before erroring

<Tip>
  Hiveku Database's default connection string already includes reasonable pool settings. BYOD users should check their provider's recommended params.
</Tip>

## Verifying Setup

Run `SELECT 1;` in the SQL Editor. If you get `1` back, the database is connected and your app can reach it.

Then in your app, add a simple query (`SELECT NOW()`) behind a route like `/api/db-test` and visit it in the browser.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection failed">
    Check that `DATABASE_URL` exists in **Settings > Environment**. For BYOD, confirm the string you pasted matches your provider's dashboard exactly — copy-paste errors are the most common cause.
  </Accordion>

  <Accordion title="Pool exhaustion errors">
    Your app is opening more connections than the pool allows. Raise `connection_limit` in the connection string, or use a connection pooler like PgBouncer (Supabase and Neon both offer pooler URLs — use those instead of the direct URL).
  </Accordion>

  <Accordion title="'Too many connections' from Postgres">
    Each serverless invocation opens a new connection by default. Switch to a pooler connection string, or make sure you're reusing a single `Pool` instance across requests rather than creating a new one each time.
  </Accordion>

  <Accordion title="BYOD provider blocks Hiveku">
    Some providers have IP allowlists. Check your provider's networking settings and ensure outbound connections from Hiveku are allowed, or use "allow from anywhere" if your provider supports it.
  </Accordion>

  <Accordion title="I ran the wrong DROP TABLE">
    Restore from the most recent backup or checkpoint in **Settings > Database > Backups**. This is exactly what backups are for.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Environment Variables" icon="key" href="/how-tos/env-vars">
    Manage secrets and config
  </Card>

  <Card title="Build with AI" icon="wand-magic-sparkles" href="/how-tos/build-with-ai">
    Let the AI design your schema
  </Card>
</CardGroup>