Documentation

Getting Started

From zero to your first query in under 2 minutes. This guide walks you step by step through getting started with Lampion.

Create an account

Head to the console and create your account. You have three options:

Google OAuth

One click, no password to remember. Your personal organization is created automatically.

GitHub OAuth

Ideal if your workflow is centered around GitHub. Same experience, same speed.

Email + password

Classic sign-up. Pick a strong password and you're set.

When you sign up, Lampion automatically creates your personal organization and assigns you the owner role. You start on the Free plan by default (3 projects, 3 branches per project).

Create a project

A project is a full PostgreSQL database with branching, monitoring, scale to zero, and backups built in. From the dashboard, click New Project and choose your cloud and region.

Required fields

name Your project's name (e.g.: my-app)

region Region (default: fr-par-1, Paris)

Available clouds and regions

scw-fr-par-1 — Paris, Scaleway (Vitry-sur-Seine)

ovh-gra-1 — Gravelines, OVH Cloud

nl-ams-1 — Amsterdam (Schiphol-Rijk) COMING SOON

On creation, Lampion automatically provisions:

Timeline

Main branch

Compute

PostgreSQL instance

Password

Generated & unique

Connection string

Ready to use

Server response

{
  "id": "abc123",
  "name": "my-app",
  "region": "fr-par-1",
  "endpoint_id": "ep-abc",
  "connection_string": "postgresql://cloud_admin:[email protected]:5432/ep-abc.postgres?sslmode=require",
  "pg_password": "YaQYfbg...",
  "host": "db-test.lampion.cloud",
  "port": 5432
}

Connect to the database

Copy the connection string from the dashboard and use it with your favorite tool. TLS (Transport Layer Security) is mandatory — your data is encrypted in transit.

psql — Native PostgreSQL client

$ psql "postgresql://cloud_admin:[email protected]:5432/ep-abc.postgres?sslmode=require"

psql (17.5) — SSL connection (protocol: TLSv1.3)
ep-abc.postgres=>

Node.js — pg / node-postgres

import pg from 'pg'

const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
  ssl: { rejectUnauthorized: true }
})

const { rows } = await pool.query('SELECT version()')
console.log(rows[0].version)

Python — psycopg2 / asyncpg

import psycopg2

conn = psycopg2.connect(os.environ["DATABASE_URL"])
with conn.cursor() as cur:
    cur.execute("SELECT version()")
    print(cur.fetchone())

Connection pooling — Lampion bundles PgBouncer in transaction mode. To enable it, connect using the options parameter rather than the database name. The TCP proxy handles multiplexing and wake-on-connect transparently.

Run queries

Two ways to interact with your database: the web console (SQL Editor) or directly via your client.

Via the SQL Editor (web console)

Multiple tabs — work on several queries in parallel

History — find your last 100 queries

Explain Analyze — execution plan in one click

CSV export — download the results

SQL import — load a .sql file

Shortcuts — Ctrl+Enter (run), Ctrl+S (save)

psql meta-commands — \dt, \d, \l supported

Saved queries — organize your snippets

Via psql or your client

ep-abc.postgres=> CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT UNIQUE,
  created_at TIMESTAMPTZ DEFAULT now()
);
CREATE TABLE

ep-abc.postgres=> INSERT INTO users (name, email) VALUES ('Alice', '[email protected]');
INSERT 0 1

ep-abc.postgres=> SELECT * FROM users;
 id | name  |       email        |         created_at
----+-------+--------------------+----------------------------
  1 | Alice | [email protected]  | 2026-03-31 10:23:45.123+00

Scale to zero — if your compute is suspended (after 5 minutes of inactivity), the first connection wakes it up automatically in under a second. No action needed on your part.

Create a branch

Branching is Lampion's killer feature. Like git branch, but for your data. Each branch is an instant CoW (Copy-on-Write) fork: it shares unmodified pages with the parent branch.

Use cases

Testing a migration

Branch, run your ALTER TABLE, validate. No risk to production.

Staging environment

A full fork of your production database, read/write, with no copy.

Preview for CI/CD (Continuous Integration/Delivery)

One branch per pull request. Automatable via the API.

How it works

1. Lampion captures the current LSN (Log Sequence Number)

2. The pageserver creates a CoW fork at that LSN

3. A new compute starts on that fork

4. Seed scripts run automatically

5. You receive a dedicated connection string

Console — or via the API

Creation

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -d '{"name":"staging","parent_id":"main-tid"}' \
  https://api-test.lampion.cloud/v1/projects/{id}/branches

Response

{
  "id": "new-tid",
  "name": "staging",
  "compute_id": "ep-new",
  "pg_port": 55436
}

Monitoring and metrics

Every project has a real-time monitoring dashboard accessible from the console.

Connections

Total, active, idle, waiting. Visualize your database's network load in real time.

Performance

Cache hit ratio, committed/rolled back transactions, compute CPU and memory.

Storage

Logical size, physical size, and WAL (Write-Ahead Log). Size per database.

24h history

Interactive charts with a snapshot every 30 seconds. Up to 72h via the API.

Query Analysis

Top slow queries via pg_stat_statements. Sort by total time, mean time, or call count.

Backups and restore

Lampion offers two complementary backup mechanisms.

Snapshots (PITR)

Capture your database's exact state at a point in time via the pageserver's LSN (Log Sequence Number). Restore to a new branch in one click — your production data is never touched.

POST /v1/projects/{id}/backups
{"name": "before-migration", "branch_id": "main-tid"}

POST /v1/projects/{id}/backups/{bid}/restore
→ Creates a branch at that exact LSN

pg_dump via the API

Export your database in standard SQL format. Useful for migrating to another provider, archiving, or debugging. Table filtering available.

GET /v1/projects/{id}/endpoints/{eid}/dump
→ Downloads a .sql file

GET ...?table=users
→ Dump of a single table

Invite your team

Lampion is built for teamwork. Invite colleagues and assign granular roles.

ROLE	PERMISSIONS	USE CASE
`owner`	Everything (create, delete, invitations, webhooks, audit)	Team admin
`developer`	Create/edit projects, branches, queries, API keys	Day-to-day developer
`viewer`	Read-only (GET only)	Stakeholder, QA (Quality Assurance), monitoring
`analyst`	Read-only, anonymized branches only. Dedicated connection string (masked data).	Data analyst, external contractor, access without PII (Personally Identifiable Information)

Audit log — every action (project creation, invitation, role change, deletion) is logged in your organization's audit trail. Available to owners via GET /v1/orgs/audit-log.

Use the API

Everything you do in the console can be done via the REST API. Create a key in Settings > API Keys.

Authentication

# Every request requires a Bearer token
curl -H "Authorization: Bearer lmp_live_xxx" \
  https://api-test.lampion.cloud/v1/projects

Key format

Prefix: lmp_live_

Scope: current organization

Permissions: role developer

The key is shown only once

For the complete reference of all endpoints, see the API documentation — 40+ endpoints covering projects, branches, computes, SQL, metrics, webhooks, and more.

Go further

You know the basics. Here are the advanced features to get the most out of Lampion.

Database Seeding

Attach SQL scripts to your project. They run automatically on every new branch — test data, fixtures, utility functions.

Query Replay

Capture queries from one branch, replay them on another. Catch performance regressions before merging a migration.

Read Replicas

Add read-only replicas on a branch to spread the load of your analytical queries.

Webhooks

Receive signed HTTP notifications (HMAC-SHA256) on events: creation, deletion, suspend/resume.

Extensions

Install pgvector, PostGIS, pg_cron, and other PostgreSQL extensions in one click from the console or API.

Data Residency

Check where your data physically resides: region, datacenter, provider, ISO 27001 / HDS certifications.

Ready to get started?

Create your first PostgreSQL database in seconds.

Create an account API Documentation