Core Concepts

Projects

A project is an isolated environment with its own database, storage bucket, and API keys. Think of it as a separate app backend — each project you create gets a dedicated PostgreSQL database and a unique API key.

You can create multiple projects for different apps or environments (staging, production).

Database

Each project gets a dedicated PostgreSQL 15 database hosted in Lagos, Nigeria. You can create tables, insert data, and query via:

• The NaijaBase dashboard (table editor — coming soon)
• The @naijabase/js SDK
• Direct PostgreSQL connection string (visible on the Dashboard tab)
• Any PostgreSQL client: pgAdmin, TablePlus, psql

API Keys

Each project has two types of keys:

Key type	Where to use	Access level
anon / public key	Frontend code, mobile apps	Restricted by RLS policies
service_role key	Server-side code only	Full access, bypasses RLS

Never expose your service_role key in client-side code.

Row Level Security (RLS)

RLS lets the database itself enforce who can read and write each row — at the database level, not just the application level.

-- Example: users can only read their own profile
CREATE POLICY "users see own data"
ON profiles
FOR SELECT
USING (auth.uid() = user_id);

With RLS, even if there's a bug in your app, the database blocks unauthorized access. Essential for NDPA 2023 compliance on multi-tenant apps.

Data Residency

All NaijaBase data is stored at:

Rack Centre, Victoria Island, Lagos, Nigeria Availability Zone: nobus-wa-az1

Data never leaves Nigeria without your explicit consent. This makes NaijaBase compliant with NDPA 2023 Section 41 on cross-border data transfers.

The SDK

@naijabase/js is the official JavaScript/TypeScript client library. Install it with:

npm install @naijabase/js

It follows the { data, error } pattern — it never throws, so you always handle errors explicitly:

const { data, error } = await naijabase.from('orders').select('*')
if (error) {
  // handle gracefully
}