WattleDB guide

You do everything from the console. The Free plan doesn't need payment details.

1. Open console.wattledb.com.au. You'll see Create your workspace.
2. Fill in Work email, Organisation name and Password (8 characters or more).
3. Click Create workspace.
4. Click the link in the verification email.
5. Back in the console, click I’ve verified.

Already have an account? Enter your email and password and click Log in. With two-factor on, you'll also need a code from your authenticator app.

Each database is a separate PostgreSQL instance in Sydney with its own plan.

1. In the sidebar, click Databases, then New database.
2. Click a plan card. The plan table below has the same figures.
3. Type a Name if you like. It's only a label.
4. Free plan: click Create Free database.
5. Paid plan: click Continue to billing, check your billing details, then click Purchase & provision.

A new row on Databases. When its status reads Active (usually after a minute or two), it's ready.

Every database has two connection strings: pooled for your app, direct for migrations, psql and pg_dump.

1. On Databases, click Connection on the database's row.
2. Copy DATABASE_URL · pooled (transaction) into your app's environment.
3. Copy DIRECT_URL · direct (session, for migrations) for migrations and psql.

# DIRECT_URL holds the direct string from the console
psql "$DIRECT_URL" -c 'select version();'

import pg from 'pg';

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
const { rows } = await pool.query('select now() as ts');
console.log(rows[0].ts);

The SQL editor is the quickest way to create your first tables.

1. On Databases, click Open on the database's row. This opens its Studio.
2. Click the SQL editor tab.
3. Paste your SQL and click Run, or press Ctrl + Enter (⌘ Return on a Mac).

create table todo (
  id       bigint generated always as identity primary key,
  owner_id uuid not null,
  title    text not null,
  done     boolean not null default false
);

insert into todo (owner_id, title)
values ('00000000-0000-0000-0000-000000000001', 'Try the REST API');

The Tables tab lets you look through data and fix a value without SQL.

1. In the Studio, click Tables.
2. Pick a table on the left. Filter tables narrows a long list.
3. Switch between Data (rows) and Schema (columns). Click a heading to sort, or use Add filter.
4. To change a value, double-click the cell, edit it and click Save.

The REST API gives every table an HTTP endpoint (PostgREST, at https://<id>.api.wattledb.com.au).

1. In the Studio, click REST API.
2. Click Enable REST API. If it says it's starting, wait and click Refresh.
3. Copy the Base URL. Each table under Endpoints takes GET, POST, PATCH and DELETE.
4. Under Authentication, click Generate authenticated token and copy the token.
5. Call the API with the token:

# read: filter, sort and page with query parameters
curl "https://t1a2b3c4d.api.wattledb.com.au/todo?select=*&order=id.desc&limit=10" \
  -H "Authorization: Bearer $TOKEN"

# insert
curl -X POST "https://t1a2b3c4d.api.wattledb.com.au/todo" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"owner_id":"00000000-0000-0000-0000-000000000001","title":"Buy milk"}'

No token means the anon role. The test token is valid for a year, so treat it like a password. Rotate on the JWT secret cancels every existing token. PostgREST clients such as @supabase/postgrest-js work against the Base URL.

Check who can read each table

• ⚠ public · no token needed: anyone with the URL can read the table. Click Make private in the warning and confirm.
• ⚠ no RLS · all rows: any token for this database reads and writes every row. That's OK for one trusted backend. If each user gets a token, turn on RLS.
• 🔒 RLS On: callers see only what your policies allow.

Give each user only their own rows (RLS)

1. Click Secure (RLS) next to the table. This turns on Row-Level Security with one allow-everything policy, authenticated_all.
2. In the SQL editor, add your own policy and drop authenticated_all. Policies are OR'd, so if you leave it your policy changes nothing.

-- sub is the user id in the token; cast it to your column's type
create policy own_rows on public.todo for all to authenticated
  using (owner_id = (current_setting('request.jwt.claims', true)::json->>'sub')::uuid);

drop policy authenticated_all on public.todo;

3. Click Reveal JWT secret and keep it on your server. Anyone with it can make tokens.
4. Sign a token for each user in your backend:

import jwt from 'jsonwebtoken';

const token = jwt.sign(
  { role: 'authenticated', sub: user.id },
  process.env.WATTLEDB_JWT_SECRET,
  { algorithm: 'HS256', expiresIn: '1h' },
);

The badge reads 🔒 RLS On, and each user's token returns only their rows. The console's test token has no sub, so it now returns nothing.

When Make private isn't enough

Make private only takes back grants we made. If you granted access yourself, the warning names it and gives you the REVOKE to run.

Every database starts with one login, app, which owns it. Use app for migrations and give everything else its own login.

1. In the Studio, click Roles.
2. Under Add a role, type a name (for example reporting_ro) and choose an access level.
3. Click Create role.
4. Copy the password now. It's shown once and we don't keep it.

You can also manage roles in SQL. app holds CREATEROLE, and roles you create this way show up on the Roles tab.

create role reporting_ro login password 'use-a-long-random-password';
grant connect on database app to reporting_ro;
grant usage on schema public to reporting_ro;
grant select on all tables in schema public to reporting_ro;

-- tables app creates later; FOR ROLE app is required
alter default privileges for role app in schema public
  grant select on tables to reporting_ro;

You can't create a superuser, grant BYPASSRLS, or change the REST API's roles (anon, authenticated, authenticator).

If a password leaks

1. On the Roles tab, under Rotate the built-in credential, click Rotate app password…
2. Click Yes, rotate it.
3. Deploy the new DATABASE_URL and DIRECT_URL. The old password stops working.

For other roles, use New password or Delete on the row. Tables a deleted role created pass to app.

Each database can have a private S3-compatible bucket. Its size depends on the plan, and uploads are refused once it's full.

1. In the Studio, click Storage. The bucket is set up the first time you open this tab.
2. Copy the Endpoint, Bucket, Region and Access key. Click Reveal to see the Secret key.
3. Use any S3 client with path-style addressing (forcePathStyle: true in the AWS SDK):

aws --endpoint-url https://storage.wattledb.com.au --region au-syd-1 \
  s3 cp ./report.pdf s3://tenant-t1a2b3c4d/report.pdf

Backups run on their own: daily at 1am Sydney time (Free, Hobby), at an hour you choose (Launch), or hourly (Scale), with changes archived in between. They're stored in Melbourne. You can restore to any moment in the last 7 days, or 30 on Scale. A restore makes a new database and leaves the original alone.

1. On Databases, click the entry in the Backups column (for example Healthy), or Backups in the Studio.
2. Click Restore… next to the database.
3. Under Restore point, pick Latest, a listed backup, or Specific time… (Sydney time, to the second).
4. Check the plan. It's the original's plan; a Free database restores onto a paid plan you choose.
5. Tick the box to say you understand it's a new, separately billed database, then click Confirm & create restored database.
6. When it's active, check the data, point your app at it, and delete the database you don't need.

A new row on Databases, billed as a normal database from the day it's ready. There's no restore fee.

A masked clone copies a Scale database into a new one and replaces common personal fields with fake values, for staging and testing. Masked clones aren't charged at the moment.

1. Open the Scale database's Studio and click Masked clone.
2. Under Target & duration, pick a plan for the clone and an Expires on date. It must be at least 7 days away (AEST).
3. Click Create clone.

A new row on Databases marked cloning. When it's done, Open appears. To keep it longer, click Extend on its row and pick a new date.

Changing plan resizes the same database. The connection string doesn't change. Only the workspace owner can do it.

1. In the Studio, click Change plan.
2. Click the plan you want.
3. Read the cost. An upgrade credits your unused days, charges them at the new rate, and adds the difference to your next invoice.
4. Click Pay A$… and switch (or Switch to the plan when there's nothing to pay).

A brief restart while the new limits apply.

Check the logs when a request fails or a connection is refused.

1. In the Studio, click Logs.
2. Choose REST API (each request's method, path and status) or Database (connections, errors and notices from PostgreSQL).
3. Use Filter, Refresh or Download as needed.

History records what happened in your workspace and to your account: databases, plan changes, invoices and sign-ins. The newest event is first.

1. In the sidebar, under Account, click History.
2. To go further back, go to the last page and click Load older events.

Read the By column closely:

• You: something you did.
• A member: someone else in your workspace.
• Support: someone at WattleDB acting on your account. If you didn't ask for it, email support@wattledb.com.au.
• Platform: the system on its own, such as cleaning up after a deleted database.

Planned maintenance and platform changes go to the bell in the console's top bar. A dot means something unread.

During a deployment you may see The console is briefly unavailable. Your database connections, REST API and file storage don't go through the console and keep working.

You can share a workspace once it has a Launch database (5 people) or a Scale database (20 people), counting the owner and unaccepted invitations. Free and Hobby are for one person.

1. In the sidebar, click Team.
2. Under Invite someone, enter their Email address and choose a Role.
3. Click Send invitation. The link lasts 7 days and only works for that address.

• Owner: everything, including billing, deleting databases and managing access.
• Developer: create and manage databases, connect, restore from a backup. Can't change billing or delete a database.
• Analyst: see the workspace and its databases. Can't connect or change anything.

Each Developer gets their own database login, removed when they leave or become an Analyst.

Your console login controls your databases. Turn on two-factor.

1. In the sidebar, click Settings.
2. Under Two-factor authentication, click Enable two-factor.
3. Enter your password.
4. Scan the QR code with an authenticator app.
5. Enter the 6-digit code from the app and click Enable two-factor.
6. Save the recovery codes (each works once), tick the box to say you have, and click Done.

Enabled. Your other devices are signed out and will ask for a code.

Settings also has Change password, which signs out other devices, and Log out of all devices for a lost laptop or phone.