$ psql "$FREEBASE_DSN"
psql (16.2)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384)
Type "help" for help.

appdb=> SELECT version();
 PostgreSQL 16.2 on x86_64-pc-linux-gnu

free-postgresql-database

Getting from no database to that prompt — and then to working code in five different stacks. This repository is the practical half: no comparison tables, no evaluation matrix, just the shortest path to a Postgres 16 instance with a real connection string and code that talks to it.

---

The sixty seconds

1. Open freebase.cloud and sign up. No card.
2. Create a session and choose PostgreSQL as the engine.
3. Copy the connection string out of the dashboard.
4. Export it and connect:

export FREEBASE_DSN='postgresql://USER:PASSWORD@HOST:5432/DBNAME?sslmode=require'
psql "$FREEBASE_DSN" -c 'SELECT now(), current_database(), current_user;'

If that returns a row, you are done with setup. Everything below is about using the thing.

The engine page is free PostgreSQL cloud instance if you want the details before signing up.

---

The connection string, taken apart

Most connection problems are a misread DSN, so it is worth knowing which part is which.

postgresql://  freebase  :  hunter2  @  db.example.net  :  5432  /  appdb  ?sslmode=require
└─ scheme ─┘   └─ role ┘    └─ pw ─┘    └─── host ───┘    └port┘   └ db ┘   └── options ──┘

Part	Notes
scheme	postgresql:// and postgres:// are both accepted by libpq and every driver built on it.
role	Not necessarily your account name. Read it off the dashboard.
password	Percent-encode it if it contains @ : / ? # [ ] %. This is the single most common cause of "authentication failed" on a password that is definitely correct.
host	A DNS name. Do not assume it resolves to a stable IP.
port	5432 unless the provider says otherwise.
database	The database inside the cluster, not the cluster.
options	sslmode=require at minimum for anything crossing the internet.

There is a script in this repository that does the taking-apart for you and prints the equivalent configuration for each client:

python3 dsn.py                 # reads $FREEBASE_DSN
python3 dsn.py --only prisma
python3 dsn.py --redact        # password masked — safe to paste into an issue

Standard library only, and it never opens a socket.

---

Connecting from five stacks

psql

psql "$FREEBASE_DSN"                     # URI form
psql -h HOST -p 5432 -U USER -d DBNAME   # discrete flags; password via PGPASSWORD
psql "$FREEBASE_DSN" -f examples/bookshelf.sql

Useful once you are in: \l databases, \dt tables, \d books one table, \timing on to see how long the round trip actually takes, \x to flip wide rows onto their side.

Prisma

echo "DATABASE_URL=\"$FREEBASE_DSN\"" > .env
npx prisma db push

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

Full models: examples/prisma/schema.prisma. Use db push while the database is scratch and migrate dev once it holds something you care about.

SQLAlchemy

SQLAlchemy needs the driver named in the scheme; a bare postgresql:// picks the default dialect, which may not be the driver you installed.

from sqlalchemy import create_engine

engine = create_engine(
    os.environ["FREEBASE_DSN"].replace("postgresql://", "postgresql+psycopg://", 1),
    pool_size=2, max_overflow=0, pool_pre_ping=True,
)

pool_pre_ping=True matters here: hosted instances close idle connections, and without it the first query after a quiet period raises instead of reconnecting. Working script: examples/sqlalchemy_quickstart.py.

pgx (Go)

cfg, err := pgxpool.ParseConfig(os.Getenv("FREEBASE_DSN"))
cfg.MaxConns = 4
pool, err := pgxpool.NewWithConfig(ctx, cfg)

pgx takes the URI unchanged — no scheme rewriting. Full program: examples/pgx_quickstart.go.

Drizzle

import { drizzle } from "drizzle-orm/postgres-js";
import postgres from "postgres";

const client = postgres(process.env.FREEBASE_DSN!, { max: 3 });
export const db = drizzle(client);

Schema, config and a query script live in examples/drizzle/. npx drizzle-kit push applies the schema straight to the instance.

---

Confirming it is genuinely Postgres

Wire-protocol compatibility is easy to claim and easy to test. Run this:

SELECT version();                                    -- real version banner
SELECT '{"a":[1,2,3]}'::jsonb @? '$.a[*] ? (@ > 2)'; -- jsonpath, PG 12+
WITH RECURSIVE t(n) AS (SELECT 1 UNION ALL SELECT n+1 FROM t WHERE n < 5)
SELECT sum(n) FROM t;                                -- recursive CTE
SELECT row_number() OVER (ORDER BY 1);               -- window function
SELECT ssl, version FROM pg_stat_ssl WHERE pid = pg_backend_pid();

The hosted instance runs PostgreSQL 16.2 and answers on port 5432 over the native protocol, so pg_dump, pg_restore, pgAdmin, DBeaver and anything else built on libpq work without adaptation. That last property is the one to check on any host: an HTTP-only "Postgres-compatible" API will fail the pg_dump test.

---

Same database, from an assistant

freebase.cloud also exposes each connection over the Model Context Protocol, which means a model can query the instance your application is connected to rather than a copy of it. Four tools are published per connection, prefixed with the connection name. With a connection called bookshelf:

• bookshelf_query — run SQL, get rows back
• bookshelf_store — insert and upsert
• bookshelf_list_tables — enumerate what exists
• bookshelf_annotate_table — attach a description to a table, so the model stops guessing what details holds

Postgres connections also surface pg_dump, pg_restore and pg_tables.

Get the URL from Settings → MCP → New Token, then:

# Claude Code
claude mcp add --transport http bookshelf https://freebase.cloud/api/mcp/YOUR_TOKEN

// Cursor — ~/.cursor/mcp.json
{ "mcpServers": { "bookshelf": { "url": "https://freebase.cloud/api/mcp/YOUR_TOKEN" } } }

// VS Code / Copilot Chat — .vscode/mcp.json (top-level key is "servers")
{
  "servers": {
    "bookshelf": { "type": "http", "url": "https://freebase.cloud/api/mcp/YOUR_TOKEN" }
  }
}

For Claude Desktop and Claude on the web there is no config file: Settings → Connectors → Add custom connector, paste the URL, then enable it per conversation from the + button. The free tier allows one custom connector. Step-by-step: how to connect Claude to PostgreSQL.

A project-scoped .mcp.json sample is in this repository. Note that a url entry with no "type" is a hard error in Claude Code, while Cursor infers it — the two formats differ, which is not obvious from either set of docs.

---

When it does not work

What you see	Usually means	What to do
password authentication failed	Special characters in the password are not percent-encoded	Run python3 dsn.py --redact and check the parsed user matches what the console shows
no pg_hba.conf entry ... SSL off	The host requires TLS and the client did not offer it	Append ?sslmode=require
could not translate host name	Copied the host with surrounding whitespace or a trailing slash	Re-copy; quote the DSN in the shell
too many connections for role	Pool defaults are larger than the instance allows	Lower pool_size / max / MaxConns; check SELECT count(*) FROM pg_stat_activity
Works locally, times out in CI	Egress from the runner is filtered	Confirm outbound 5432 is permitted from the runner
First query after an idle period fails	The server closed an idle connection	Enable pre-ping or connection retry; do not raise the pool size
relation "books" does not exist	Connected to a different database than the one you migrated	SELECT current_database();

---

What the free tier is for

Development, prototyping and small production workloads. That is the honest framing and this repository will not stretch it further: there are no published uptime commitments, no backup guarantees and no storage figures to quote. Treat a free instance the way you would treat any single-copy database — if losing it would hurt, keep a dump somewhere else:

pg_dump "$FREEBASE_DSN" -Fc -f bookshelf.dump
pg_restore -d "$OTHER_DSN" bookshelf.dump

Because the wire protocol is the real one, that dump restores into any Postgres 16 anywhere. Portability is the practical answer to free-tier risk, and it is worth checking on any provider before you build on it.

---

FAQ

Is this a real PostgreSQL server or a compatibility layer? Real, and testable: SELECT version() reports 16.2, and pg_dump works over the same connection. Compatibility layers generally fail on one or the other.

Which extensions can I use? CREATE EXTENSION works for the common set — uuid-ossp, pgcrypto, hstore, citext among them. Confirm on your own instance with SELECT name FROM pg_available_extensions ORDER BY name; before depending on one.

Can I point pgAdmin or DBeaver at it? Yes. Both speak libpq. Enter the parts from the table above, or paste the URI into the connection dialog if your version accepts one.

Do I need a card at any point? No.

Can I use it from a serverless function? Yes, with the usual caveat that applies to every Postgres host: one connection per invocation exhausts a small instance quickly. Use a pooler or a driver with a hard connection cap.

How do I get my data out? pg_dump. There is no export ticket to file and no proprietary format.

---

What is in here

dsn.py                  parse one DSN, print the config for five clients
.mcp.json               project-scoped MCP server sample for Claude Code
examples/               the reading-log schema in SQL, Python, Go and TypeScript
examples/README.md      how to run each one

---

freebase.cloud is an independent service and is not affiliated with the PostgreSQL Global Development Group, Prisma, the SQLAlchemy project, Drizzle Team, Anthropic, Microsoft, or Cursor.