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

# Back Up Your Database

> Create, download, and manage SQL backups of your project database

Create a snapshot of your database you can download, archive, or restore from. Hiveku also runs automatic backups in the background — manual backups are for extra peace of mind before risky migrations or as a compliance record.

## Where to Find Backups

In your project, go to **Database > Backups** tab.

You'll see a list of existing backups with ID, branch, description, table count, row count, size, and creation date.

## Create a Backup

<Steps>
  <Step title="Open the Backups tab">
    Go to **Database > Backups**.
  </Step>

  <Step title="Click + Create Backup">
    A form opens for the new backup.
  </Step>

  <Step title="Choose the branch">
    Most projects have at least two database branches:

    * **main** — production schema and data
    * **dev** — staging or development

    Pick the branch whose data you want to snapshot.
  </Step>

  <Step title="Add a description">
    Optional but recommended. A short note like "before adding `users.stripe_customer_id`" helps you find the right backup months later.
  </Step>

  <Step title="Click Create">
    The backup runs in the background. Small databases finish in seconds; larger ones can take several minutes.
  </Step>

  <Step title="Wait for completion">
    The new backup appears in the list once done, with row count and size filled in.
  </Step>
</Steps>

## What Gets Backed Up

A Hiveku backup is a full SQL dump of the selected branch:

* All tables (schema)
* All rows (data)
* Indexes, constraints, and relations
* Stored functions and views

Roles and extension state are not included — those are managed at the project level.

## Download a Backup

<Steps>
  <Step title="Find the backup in the list">
    Backups are sorted newest first.
  </Step>

  <Step title="Click Download">
    You get a `.sql` file containing the full dump. The download link is signed and short-lived — if it expires, click download again.
  </Step>

  <Step title="Store it safely">
    Backups may contain PII, auth tokens, or other sensitive fields. Store downloaded backups encrypted, and limit access.
  </Step>
</Steps>

<Warning>
  Backup files often contain user data. Treat them like production secrets — don't leave them in Downloads, don't email them, and delete them when you no longer need them.
</Warning>

## Delete a Backup

Click the trash icon next to any backup and confirm. Deletion is immediate and irreversible.

## Automatic Backups

Hiveku runs automatic backups on a regular schedule regardless of your manual backups. Retention depends on your plan. See the [backups reference](/database/backups) for schedule and retention details.

Manual backups are useful when:

* You're about to run a migration and want a rollback point
* You need a compliance snapshot with a known description
* You want a dated archive you control

## Restoring a Backup

Hiveku doesn't have a one-click restore button in the dashboard today. Your two options:

<Tabs>
  <Tab title="Ask AI (Recommended)">
    In the project's AI tab:

    ```
    Restore my database from the backup created yesterday labeled 
    "before adding stripe_customer_id". Keep a fresh backup of current 
    data first in case we need to roll back.
    ```

    The AI creates a safety backup, runs the restore, and reports what changed.
  </Tab>

  <Tab title="DIY via SQL Editor">
    For small restores or partial data recovery:

    1. Download the backup `.sql` file
    2. Open your project's SQL editor
    3. Paste the relevant statements and run them
    4. For full restores, drop the affected tables first, then run the backup file

    This works well for a single table. For full database restores, use AI chat or contact support.
  </Tab>
</Tabs>

<Warning>
  Restoring replaces current data. Always create a fresh backup of your current state before restoring, in case you want to undo. Ask AI to do this for you — it's easy to forget.
</Warning>

## Storage & Retention

Backups are stored in S3 with encryption at rest. Retention is determined by your plan — see [Database > Backups settings](/database/backups) for your project's retention policy and storage usage.

## Verify a Backup

<Steps>
  <Step title="Download the .sql file">
    Use the Download button.
  </Step>

  <Step title="Open it and scan">
    The file starts with `CREATE TABLE` statements, then `INSERT` statements for data. Confirm all your expected tables are listed.
  </Step>

  <Step title="Spot-check row counts">
    For a key table (e.g., `users`), count `INSERT` lines (`grep -c "INSERT INTO users" backup.sql`) and compare to the row count shown in the Backups tab.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Backup failed partway">
    Usually means the database is very large and timed out during dump. Contact support — they can run a custom backup with extended timeouts or incremental snapshots.
  </Accordion>

  <Accordion title="Download link expired">
    Download links are signed and short-lived. Click **Download** again on the same backup row to generate a fresh link. If the backup is older than your plan's retention, it may have been deleted — create a new backup from the current state.
  </Accordion>

  <Accordion title="Need to restore right now">
    Ask AI in your project: *"Restore the database from backup ID X."* For time-sensitive production restores, contact support — they can do emergency restores and handle complex cases (cross-branch, partial recovery).
  </Accordion>

  <Accordion title="Backup size unexpectedly large">
    Usually one or two tables with `jsonb` or `bytea` columns storing large blobs. Check table sizes in the SQL editor:

    ```sql theme={null}
    SELECT
      relname AS table_name,
      pg_size_pretty(pg_total_relation_size(relid)) AS total_size
    FROM pg_catalog.pg_statio_user_tables
    ORDER BY pg_total_relation_size(relid) DESC
    LIMIT 10;
    ```

    Consider moving large blobs to object storage and keeping only references in the database.
  </Accordion>

  <Accordion title="Row counts don't match between branches">
    Expected — `main` and `dev` branches diverge as you test. Back up each branch separately if you want snapshots of both.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Set Up Your Database" icon="database" href="/how-tos/setup-database">
    Create tables and relationships
  </Card>

  <Card title="Backups Reference" icon="floppy-disk" href="/database/backups">
    Automatic schedules and retention policies
  </Card>
</CardGroup>