quickstart

six steps, about five minutes, and at the end of it there is a row in a real postgresql 18 database that you put there. no local install, no docker, nothing to uninstall afterwards if you decide against us.

1 · create an account

Go to sign up and use an email address and a password, or ask for a one-time code and take it out of your inbox. Either way you land in the dashboard with an organisation of your own, and everything you make from here belongs to it.

2 · create a database

In the dashboard, open databases and create one. Give it a name you will recognise later — notes is fine. What you get is not a sandbox or a shared schema: it is a real PostgreSQL 18 database, and pgvector is installed inside it at creation, so there is no extension to add before you can store an embedding.

The free plan allows one database. That is enough for everything on this page.

3 · get your connection string

Reveal the connection string from the database’s page in the dashboard. It arrives in this shape:

connection string

postgresql://r_3f9c2a17b4e0d85c:••••••••@<your-host>:5432/db_7a1e4c093b62df85?sslmode=require

Two things surprise people. The database name in the URL is not notes — the friendly name you typed is a label we keep on our side, and the URL carries an opaque db_ name instead. And the role is a generated r_ name rather than your email. Both are correct; copy the string exactly as it is given to you. Connecting takes the string apart piece by piece.

Every reveal is written to the audit log, and the password is stored encrypted rather than hashed — which means you can reveal it again later instead of having to reset it and update everything that used it.

4 · connect

You have two ways in, and they are equally real. Pick whichever suits where your code runs.

with psql

Paste the whole string in quotes so your shell does not eat the ? or anything after it.

bash

psql "postgresql://r_3f9c2a17b4e0d85c:your-password@<your-host>:5432/db_7a1e4c093b62df85?sslmode=require"

or over plain http

If your code runs somewhere that cannot hold a socket open — an edge function, a worker, a CI job — you do not need a driver at all. Make an API key in the dashboard at api keys. You choose a name, whether it is limited to one database or works across the organisation, whether it is read-only, and when it expires: never, or in 30, 90, 365 or 730 days.

the key is shown to you once, at the moment you create it. briven keeps only a sha-256 hash of it and the last four characters, so if you lose it nobody can recover it for you — not support, not us. put it in your password manager or your environment file before you close the dialog. keys look like brk_ followed by 43 characters, 47 in total.

bash

curl -sS https://briven.tech/api/v1/sql \
  -H "Authorization: Bearer $BRIVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"select version()","database":"notes"}'

Note that the HTTP endpoint takes the friendly name — notes — not the opaque one from the URL. The full endpoint, including how to pass parameters safely, is on sql over http.

5 · create a table and insert a row

This is ordinary PostgreSQL. Nothing on this page is a briven dialect, and none of it will need rewriting if you ever move.

sql

create table notes (
  id         bigint generated always as identity primary key,
  title      text        not null,
  body       text        not null default '',
  created_at timestamptz not null default now()
);

insert into notes (title, body)
values ('first note', 'written from the quickstart')
returning id, title, created_at;

The same thing over HTTP, one statement per request, with the value passed as a parameter rather than glued into the string:

bash

curl -sS https://briven.tech/api/v1/sql \
  -H "Authorization: Bearer $BRIVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query":"insert into notes (title, body) values ($1, $2) returning id, title",
    "params":["first note","written from the quickstart"],
    "database":"notes"
  }'

Read it back with select * from notes; and you are done — that is the whole loop, and everything after this is detail.

6 · where to go next

Connecting is the one to read next, and read it before you ship rather than after. Every connection goes through a pooler in transaction mode, and that changes the behaviour of session settings, of LISTEN / NOTIFY, and of prepared statements in Prisma and node-postgres. It is a short page and it saves a bad afternoon.

Sql over http covers the endpoint properly — the response shape, parameters, and the fact that the Neon serverless client @neondatabase/serverless works against it unmodified.

Vector search is where pgvector earns its place: the column type, the index, and the query to actually write.

there is a cli, and it does the same jobs from a terminal — but it is not published to npm, so there is no install line we can honestly give you here. see cli for how it is run today.