Documentation
Documentation
Introduction

Getting Started

Getting started
Getting StartedInstallationQuick StartProject Structure

Configuration

Configuration
ConfigurationEnvironment ConfigurationEdge ConfigDatabaseAuth SecretStripeFirebaseStorageGoogle Maps And Cloud Service AccountOAuth ProvidersEmail DeliverySentryFeature Flags

Architecture

Architecture
Architecture OverviewTech StackoRPC MiddlewareDesign Principles

Patterns

Patterns
Code Patterns & ConventionsFeature ModulesError HandlingType Safety

Database

Database
DatabaseSetupSchema DefinitionDatabase OperationsMigrationsCaching
Data Tables

API

oRPCProceduresRoutersoRPC Proxy Setup
APIsOpenAPIREST Endpoints

Auth & Access

AuthenticationConfigurationOAuth ProvidersRolesSession Management
AuthorizationUser RolesPermissions

Routing & i18n

RoutingDeclarative RoutingNavigation
InternationalizationTranslationsLocale Routing

Components & UI

ComponentsButtonsFormsNavigationDialogs
StylesTailwind CSSThemingTypography

Storage

Storage
StorageConfigurationUsageBuckets
Stripe Billing

Extra

Caching

Templates

Templates
Template GuidesCreate New FeatureCreate New PageCreate Database TableCreate oRPC RouterAdd Translations

Development

Development
DevelopmentCommandsAI AgentsBest Practices
Pulling Updates

Setup

Initialize your PostgreSQL database for Row Level Security

Before running npm run db:push, you need to set up the required database roles and functions for Row Level Security (RLS) policies.

[!IMPORTANT] This setup is required once per database. Without it, db:push will fail with errors like:

role "authenticated" does not exist

Quick Setup

Run the setup command:

npm run db:setup

This creates all required roles and functions automatically.

What It Creates

PostgreSQL Roles

RolePurpose
authenticatedLogged-in users
anonymousPublic/unauthenticated access
adminAdministrative operations
serviceServer-side operations

Auth Schema & Functions

ItemPurpose
auth schemaNamespace for auth helper functions
auth.user_id()Returns current user's UUID from session

Manual Setup

If you prefer to run the SQL manually (or if the script fails), execute this SQL in your database:

-- Create roles for RLS policies
DO $$
BEGIN
  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'authenticated') THEN
    CREATE ROLE authenticated;
  END IF;
  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'anonymous') THEN
    CREATE ROLE anonymous;
  END IF;
  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'admin') THEN
    CREATE ROLE admin;
  END IF;
  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'service') THEN
    CREATE ROLE service;
  END IF;
END $$;

-- Create auth schema and user_id function
CREATE SCHEMA IF NOT EXISTS auth;

CREATE OR REPLACE FUNCTION auth.user_id() RETURNS uuid AS $$
  SELECT NULLIF(current_setting('auth.user_id', true), '')::uuid;
$$ LANGUAGE SQL STABLE;

-- Grant usage to roles
GRANT USAGE ON SCHEMA auth TO authenticated, anonymous, admin, service;

Running Manual SQL

  1. Open your Neon Dashboard
  2. Select your project and database
  3. Go to SQL Editor
  4. Paste and run the SQL above
# Option 1: Direct connection
psql $DATABASE_URL -c "$(cat scripts/db-setup.sql)"

# Option 2: Interactive
psql $DATABASE_URL
# Then paste the SQL

Connect using TablePlus, pgAdmin, DBeaver, or your preferred tool:

  1. Connect to your database using DATABASE_URL
  2. Open a new query
  3. Paste and execute the SQL above

Verification

After setup, verify the roles exist:

SELECT rolname FROM pg_roles
WHERE rolname IN ('authenticated', 'anonymous', 'admin', 'service');

Expected output:

    rolname
---------------
 admin
 anonymous
 authenticated
 service

Troubleshooting

Permission Denied

If you see permission errors, your database user may not have CREATE ROLE privileges. Contact your database administrator or use a connection with superuser access.

Neon Serverless

Neon supports custom roles. The setup script works out of the box.

Supabase

Supabase already has these roles built-in. You may skip the role creation but still need the auth.user_id() function if using custom RLS policies.

Next Steps

After setup completes:

# Push schema to database
npm run db:push
  • Schema Definition - Define your tables
  • Migrations - Manage schema changes
  • Operations - CRUD operations

On this page

Quick Setup
What It Creates
PostgreSQL Roles
Auth Schema & Functions
Manual Setup
Running Manual SQL
Verification
Troubleshooting
Permission Denied
Neon Serverless
Supabase
Next Steps