Skip to main content
Better Skills uses PostgreSQL with Drizzle ORM for type-safe database operations.

​
Database options

You can use either:
  • Local PostgreSQL - Best for offline development
  • Neon Postgres - Managed cloud database with connection pooling

​
Local PostgreSQL setup

​
Install PostgreSQL

brew install postgresql@17
brew services start postgresql@17

​
Create a database

creatdb better_skills
Or connect with psql: 
psql postgres
CREATE DATABASE better_skills;

​
Set DATABASE_URL

Add to apps/server/.env:
apps/server/.env
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/better_skills

​
Neon database setup

1

Create a Neon project

Sign up at Neon and create a new project.
2

Copy connection string

From your Neon dashboard, copy the connection string (with pooling enabled).
3

Set DATABASE_URL

Add to apps/server/.env:
apps/server/.env
DATABASE_URL=postgresql://user:[email protected]/dbname?sslmode=require
Neon provides a pooled connection string for production use. This is recommended for serverless environments.

​
Sync Neon to local (optional)

If you’re using Neon for production, you can sync it to a local PostgreSQL instance: 
bash scripts/sync-neon-to-local.sh
This script:
  1. Dumps your Neon database
  2. Imports it into your local PostgreSQL
  3. Preserves schema and data

​
Schema management

Better Skills uses Drizzle Kit for database migrations and schema management.

​
Push schema changes

Apply schema changes directly to your database (development only): 
bun run db:push
db:push is for development only. It will drop and recreate tables. Use migrations for production.

​
Generate migrations

Create a new migration from schema changes: 
bun run db:generate
This generates SQL migration files in packages/db/migrations/.

​
Run migrations

Apply pending migrations to your database: 
bun run db:migrate

​
Open database studio

Launch Drizzle Studio to browse and edit data: 
bun run db:studio
This opens a web UI at https://local.drizzle.studio.

​
Database schema location

All schema definitions live in: 
packages/db/src/schema/
The schema includes:
  • User tables (Better Auth)
  • Skills and skill relationships
  • Graph links and mentions
  • Sessions and accounts

​
Environment variables

The database connection is configured through:
apps/server/.env
DATABASE_URL=postgresql://user:password@host:5432/dbname
Drizzle Kit reads DATABASE_URL from apps/server/.env when running:
  • bun run db:push
  • bun run db:generate
  • bun run db:migrate
  • bun run db:studio

​
Common workflows

​
First-time setup

1

Install PostgreSQL

Follow the installation steps above.
2

Create database

createdb better_skills
3

Set DATABASE_URL

Configure apps/server/.env with your connection string.
4

Push schema

bun run db:push

​
Modify schema

1

Edit schema files

Update files in packages/db/src/schema/.
2

Generate migration

bun run db:generate
3

Review migration SQL

Check the generated SQL in packages/db/migrations/.
4

Apply migration

bun run db:migrate

​
Reset database

To completely reset your local database: 
dropdb better_skills
createdb better_skills
bun run db:push
This deletes all data. Only use in development.

​
Troubleshooting

PostgreSQL is not running. Start it:
# macOS
brew services start postgresql@17

# Linux
sudo systemctl start postgresql

# Docker
docker start better-skills-db
Ensure apps/server/.env exists and contains DATABASE_URL. Drizzle Kit reads from this location.
If migrations conflict:
  1. Review migration files in packages/db/migrations/
  2. Manually resolve conflicts in SQL
  3. Re-run bun run db:migrate

​
Next steps

Environment Variables

Configure all required environment variables

Development Setup

Return to development setup guide

Build docs developers (and LLMs) love

Get started for freeTalk to us