Database Setup

Database Setup

FCDex uses PostgreSQL for persistent data storage and Prisma to interact with the database.

This guide covers the database setup process and important precautions for self-hosters.

Warning

FCDex is under active development. Do not run migrations against an existing production database until you have reviewed the schema, migration history, and backup.

Requirements

You need:

• A PostgreSQL database
• Valid database connection settings
• The FCDex dependencies installed
• The project's Prisma schema

PostgreSQL can run locally or be hosted by a database provider.

Configure the database connection

Configure the database connection required by your FCDex instance.

Keep database credentials private. Never commit passwords or connection strings to GitHub.

Generate the Prisma client

After installing dependencies, run:

bun run db:generate

This generates the Prisma client from the project's Prisma schema.

Generating the client does not create or update database tables.

Database schema

The Prisma schema defines the models and relationships used by FCDex.

Before changing the schema:

1. Review the existing models and relationships.
2. Identify which features depend on the affected models.
3. Back up important data.
4. Review existing migrations.
5. Test changes against a development database first.

Database migrations

FCDex includes the following command:

bun run db:migrate

This invokes Prisma's development migration workflow.

Do not assume this command is suitable for production databases. Review the migration plan before applying schema changes, especially when working with an existing database.

Using an existing BallsDex database

FCDex intends to support migration from BallsDex so existing self-hosters can preserve their data.

The dedicated migration tool is planned for a later development phase, after the core bot and administration panel are developed.

Until that tool is implemented:

• Do not point FCDex at a live BallsDex database and run migrations.
• Do not assume the BallsDex schema matches the FCDex schema.
• Keep the original database unchanged.
• Create and verify a backup before testing data conversion.

The goal is to provide a safe, documented migration process once FCDex's data models are finalized.

Database inspection

You can launch Prisma Studio with:

bun run db:studio

Use it to inspect your database. Be careful when editing or deleting records.

Backups and data safety

Before performing database migrations or schema changes:

1. Create a database backup.
2. Verify that the backup can be restored.
3. Test the change against a separate database.
4. Validate the resulting records.
5. Keep the original backup until everything has been verified.

Never experiment with destructive database operations on your only copy of important data.

Troubleshooting

If the database connection fails, check:

• PostgreSQL is running and reachable.
• The connection settings are correct.
• The database exists.
• The configured account has the necessary permissions.
• Network and firewall settings allow the connection.

If the issue persists, open a GitHub issue.

Remove passwords, connection strings, and other sensitive information before sharing logs.

Related pages

• Installation
• Configuration
• Running FCDex
• Troubleshooting