How to Use NocoDB: The Beginner's Guide (First Base, First Table, Links, Formulas, and the Free API)

CodexFuse Team · 2026-10-31T09:36:10.020Z · 15 min read

Learn how to use NocoDB: pick SQLite or Postgres, install with Docker, build your first base, link tables, add formulas, and call the free REST API.

How to Use NocoDB: The Beginner's Guide (First Base, First Table, Links, Formulas, and the Free API)

Learning how to use NocoDB is the moment a person finally gets a real database without learning a database. NocoDB is a free, open-source, self-hosted no-code database platform that wraps a proper relational database — PostgreSQL, MySQL, SQL Server, or SQLite — in a spreadsheet-style web interface anyone can use. Teams that outgrow spreadsheets but cannot hire a database developer use it to build internal tools, trackers, and prototypes; the moment a record is saved, NocoDB also exposes it through an auto-generated REST API, so developers and automation tools can read and write the same data. This NocoDB tutorial runs the complete beginner arc in one guide: choosing between SQLite and Postgres, installing with Docker, meeting the super-admin rule, creating your first base, building tables with relational fields, adding links, lookups, rollups and formulas, and calling the free REST API with a real example. If you are coming from a spreadsheet because you need relationships between tables, skim the Airtable beginner guide first for the mental model — NocoDB is the self-hosted, no-subscription answer to the same itch, with the data on your own server.

What is the fastest way to start using NocoDB?

The fastest beginner path is: pick SQLite for a throwaway test or Postgres for anything real, install with the quickstart installer, create the first user (who becomes super admin), create your first base, add a table with real field types, link two tables, add a formula, and generate an API token. In plain order, the steps are:

1. Decide the backend before you type anything: SQLite is fine for an afternoon of learning, Postgres is the choice for anything you will keep. Without an explicit database NocoDB creates a local SQLite file, and moving to Postgres later is a migration you do not want.
2. Install with the official quickstart on a machine that has Docker: curl -fsSL https://install.nocodb.com/noco.sh | bash -s -- --quick. This spins up four containers — the NocoDB app, a background worker, Postgres, and Redis — and serves the UI at http://localhost:8080.
3. Open http://localhost:8080 and sign up with an email and password. The first user you create is the super admin; there is no separate admin account to find later.
4. Create your first base. A base is NocoDB's word for one database project: a container that holds your tables plus their views, automations, and permissions.
5. Add your first table and give its fields real types: Single Line Text for names, Date for dates, Single Select for statuses, Attachment for photos, Long Text for notes. Click the plus, pick the type, name it — no SQL required.
6. Link two tables with a Links field, add a Lookup to pull a value across the link, a Rollup to count or sum, and one Formula to compute something. This is the moment NocoDB stops being a spreadsheet and becomes a relational database.
7. Generate an API token under Account Settings, then call GET /api/v1/db/data/noco/<Your Base>/<Your Table>?limit=10 with an xc-token header. If JSON comes back, your database is now also an API — that is the free part nobody charges extra for.

That is the whole loop. Everything below explains each step in detail: the backend decision, the two install paths, the super-admin rule, the field types that matter, the relational fields, views, the REST API, the honest comparison with Airtable and Supabase, and the beginner mistakes that eat people's data.

What is NocoDB, and why do beginners compare it with Airtable?

NocoDB is an open-source Airtable alternative you run yourself. The comparison exists because the core experience is deliberately familiar: data lives in rows and columns, fields have types (text, numbers, dates, attachments), you can add views like Grid, Form, Gallery, Kanban, and Calendar, and you invite teammates with role-based permissions. The difference is ownership: Airtable is a hosted SaaS with a per-seat bill, while NocoDB runs on your own server, stores data in your own database, and the project has passed roughly 65,000 GitHub stars as a self-hostable project.

The honest version of the nocodb airtable alternative question has two sides. Airtable is smoother out of the box and its ecosystem of extensions is bigger; it is the easier choice if you never want to touch infrastructure. NocoDB is the better choice when the spreadsheet is becoming load-bearing — when you want the data in Postgres you can query directly, when per-seat pricing is starting to hurt, or when the data simply should not live on someone else's servers.

One boundary keeps beginners out of trouble: NocoDB is not a backend-as-a-service. If you need authentication, file storage, and serverless functions in one hosted bundle, that is the lane the Supabase beginner guide covers. NocoDB's lane is the no-code database itself: the spreadsheet UI on top of a real relational database, plus the free REST API that makes every table programmable.

Should you self-host NocoDB or use the cloud version?

Self-host if you want the data, the database, and the bill under your control; use the cloud version if you want to try the UI without touching a server. NocoDB ships in two variants: self-hosted, where you run it on your own machine or server, and cloud-hosted SaaS, which the official docs recommend for brand-new users who just want to evaluate the interface.

For a beginner guide this matters because the two paths diverge at the database decision. The cloud version abstracts the backend away. The self-hosted path forces the one decision that actually matters — SQLite or Postgres — and that decision is where the rest of this guide starts. Since the audience of this NocoDB tutorial is people who want their own instance, the guide teaches the self-hosted path and shows how to try it locally for free first.

Should NocoDB run on SQLite or Postgres?

Use SQLite for learning and throwaway experiments; use Postgres for anything you care about. This is the single most important decision in the whole NocoDB install, and the official environment-variable reference makes the mechanics plain: the NC_DB variable is marked mandatory for production, and if you do not set it NocoDB quietly creates a local SQLite database. SQLite is not a bug — it is the reason the quickstart is one command — but it is a single-file, single-process database, and it is the wrong home for data you cannot afford to lose.

The good news is that the official quickstart installer already chose for you: it ships Postgres, Redis, the app, and a worker as four containers. You only face the SQLite-vs-Postgres question if you install NocoDB with the bare docker run one-liner — and the writer's recommendation is simple: if you already know this project might matter, start with the quickstart's Postgres instead of migrating later.

How do you install NocoDB with Docker?

There are two Docker paths: the bare one-liner for a quick look, and the official quickstart for a real setup. The one-liner is the fastest way to see the UI:

docker run -d \
  --name noco \
  -v "$(pwd)"/nocodb:/usr/app/data/ \
  -p 8080:8080 \
  nocodb/nocodb:latest

That volume mount is not decoration — it is the rule. NocoDB writes its SQLite file into /usr/app/data/ inside the container, and without the mount that data dies the moment the container is recreated. Mount it or use a named volume; never run the one-liner naked and then store anything you value.

The quickstart installer is the better path and still one command. Per the official quickstart docs (crawled this run, 2026-10-31), it writes a four-container Compose stack into a nocodb/ directory and starts it on port 8080:

curl -fsSL https://install.nocodb.com/noco.sh | bash -s -- --quick

Docker keeps the data in named volumes (postgres_data, redis_data, nocodb_data), so your data survives restarts and even docker compose down. Run the day-to-day commands from inside the nocodb/ directory: docker compose logs -f nocodb to tail logs, docker compose down to stop (data stays), docker compose up -d to start again, and docker compose pull && docker compose up -d to update. If the noco.sh installer feels unfamiliar, the Docker beginner guide explains what each of those commands actually does to your machine.

How do you install NocoDB on your own server with HTTPS?

Run the same installer without the --quick flag and give it a domain. The single-server install is one command that produces NocoDB with Postgres and Redis plus Traefik with automatic Let's Encrypt SSL — the full production shape on one machine:

curl -fsSL https://install.nocodb.com/noco.sh | bash

Before you run it, meet the requirements the official single-server docs list: Docker with the Compose v2 plugin, ports 80 and 443 reachable on the host, and the domain's DNS A record already pointing at the server's public IP. The installer asks four things, and the writer cautions you to read each prompt because they change over time: a domain (leave it blank or use localhost for local mode on port 8080; a bare IP gives plaintext HTTP on port 80 with no SSL), Postgres as bundled or existing, Redis as bundled or existing, and a Let's Encrypt email for certificate renewal notices. You will need a server to point all this at — the what is VPS hosting guide explains what to rent and why the smallest tier is enough for a first NocoDB.

After the stack is up, the official docs give a production checklist worth honoring: allow only ports 22, 80, and 443 through the firewall; keep the installer-generated docker.env and nocodb/db.json at 600 permissions; pin your image tags instead of tracking latest; make a daily pg_dump plus an attachment tarball; and know that NocoDB phones home to app.nocodb.com on TCP 443 every six hours for license activation — if your firewall filters egress, allowlist exactly that URL, or look up the airgapped-license docs for fully offline servers. Updates ship through ./update.sh in the nocodb/ directory, which pulls, restarts, and prunes old images.

What happens the first time you open NocoDB?

You create the super admin, and you should know that before you type the email. The first user created on a fresh NocoDB is the super admin with full control — roles, billing-adjacent settings, user management — and there is no separate "admin" account created for you. Choose a real email you control and a password you have stored, because this account is the keys to the building.

After signup you land on the dashboard with a default workspace. The structure NocoDB uses is: workspace at the top, bases inside it (each base is one database project), tables inside each base, and views on top of the tables. A fresh install creates a sample "Getting Started" base so you can poke around before making your own; when you are done poking, create a new base with a real name. That name will appear in your REST API URLs later, so pick something URL-friendly and stable — renaming a base means rewriting any integrations that point at it.

How do you build your first table in NocoDB?

Start with the thing you track, and give every column a real type instead of dumping everything into text. Take a concrete example a beginner can copy — a "Plants" table for a small greenhouse, from the community build story this guide leans on: Name (Single Line Text), Species (Single Line Text), Planting Date (Date), Status (Single Select: Healthy, Needs Attention, Sick), Bed Location (Single Line Text), Photo (Attachment), Notes (Long Text). Adding a field is three clicks: hit the plus, pick the type, name it.

Two habits separate a clean table from a spreadsheet-shaped mess. First, prefer typed fields over Long Text for everything — dates as Date fields sort correctly, Single Select keeps your statuses spelled the same way, Numbers stay numbers for rollups. Second, resist the urge to put related data in one giant table: a "Daily Logs" table (temperature, humidity, soil pH, notes) linked to "Plants" is ten times easier to maintain than one wide table with repeating plant names. That second habit is where NocoDB earns the word "relational".

How do links, lookups, rollups, and formulas work?

These four field types are the whole reason NocoDB beats a spreadsheet, and beginners should learn them in exactly this order. A Links field connects records across tables: add a Links field on "Daily Logs" pointing at "Plants" (a "Has Many" link), and NocoDB automatically creates the reverse link on the Plants side — each plant now shows its logs, each log shows its plant. A Lookup pulls a value across a link without retyping it: a lookup on Daily Logs can show the plant's Species right inside the log row.

A Rollup computes across a link: count how many log entries each plant has, or average the soil pH across a plant's readings. A Formula computes from the record itself with spreadsheet-style functions — IF, CONCAT, DATETIME_DIFF — like this flag for sick plants:

IF({Status} = "Sick", "Needs Immediate Action", "OK")

The mental model is one sentence: Links create the relationship, Lookups read across it, Rollups aggregate across it, and Formulas compute within the record. Once you can say that sentence from memory, you know how to use NocoDB's data model.

What can views do for people who never want to touch the database?

Views are the same table shown different ways, and they are how you hand NocoDB to non-technical people. Every table can have many views, each with its own fields, filters, and sorting: a Grid view filtered to show only Sick plants by default, a Gallery view using the Photo field as a visual catalog, a Kanban view grouped by Status so health is visible at a glance, a Calendar view over Planting Date, and a Form view for data entry.

The Form view deserves special attention because it is NocoDB's quiet superpower for teams. Make a "Daily Log Input" form, hide the admin-only fields, and put a password on it — the people who water the plants open the link on their phones and submit readings without accounts, without seeing the database. Public links and embeds go further: you can share a view publicly or embed it on a website, with field-level control over what is visible.

How do you use the free NocoDB REST API?

Every table you create is already an API; you just need a token to call it. Generate the token under Account Settings, pass it in the xc-token header, and the pattern for every call is the same: /api/v1/db/data/noco/<Base Name>/<Table Name>. Three calls teach the whole shape, using the greenhouse base from earlier:

# List plants (first 10)
curl -X GET "http://localhost:8080/api/v1/db/data/noco/Greenhouse%20Manager/Plants?limit=10" \
  -H "xc-token: YOUR_API_TOKEN"

# Create one
curl -X POST "http://localhost:8080/api/v1/db/data/noco/Greenhouse%20Manager/Plants" \
  -H "xc-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"Name": "Cherry Tomato", "Species": "Solanum lycopersicum", "Status": "Healthy"}'

# Filter and sort: sick plants, newest first
curl -X GET "http://localhost:8080/api/v1/db/data/noco/Greenhouse%20Manager/Plants?where=(Status,eq,Sick)&sort=-Planting_Date" \
  -H "xc-token: YOUR_API_TOKEN"

The query language supports compound filters like where=(Status,eq,Sick)~and(Bed_Location,like,A%), and an official Node SDK (nocodb-sdk) wraps the same endpoints for JavaScript. This is also the moment NocoDB meets the rest of your stack: webhooks can fire on record changes (one community user posts a Discord message when greenhouse temperature passes 35°C), and the n8n beginner guide shows how to wire NocoDB into automations — n8n reads and writes NocoDB through this exact API, so the two are partners, not competitors. Treat API tokens like passwords: scope them to what the integration needs, and rotate them if they ever leak.

NocoDB vs Airtable vs Supabase vs Baserow: which should a beginner pick?

Pick the one whose lane matches your actual problem, not the one with the loudest marketing. All four are compared here as what they are — a beginner choosing one of them — never as separate guides:

The lane rule is simple: NocoDB and Baserow compete for the self-hosted no-code database slot; Airtable owns the zero-infrastructure slot; Supabase owns the full-backend slot. Choose NocoDB when the spreadsheet experience matters AND the data must live on your infrastructure.

What beginner mistakes destroy NocoDB data?

The same five mistakes appear in every community horror story, and all of them are preventable before the first real record:

Sources

Facts in this guide were verified at write time (2026-10-31) against: the official NocoDB single-server installation docs and quickstart docs (crawled 2026-10-31), the official NocoDB environment-variables reference (NC_DB, NC_AUTH_JWT_SECRET, NC_ADMIN_EMAIL/NC_ADMIN_PASSWORD semantics), the official NocoDB getting-started product guide (workspace/base/table/view structure, field types, roles, automations, NocoAI), the GitHub nocodb/nocodb releases API (tag 2026.10.1 released 2026-10-29; ~65,396 stars), the community build story "Learning NocoDB from Scratch: Creating a Simple Greenhouse App" by emka.web.id (October 2026 — the docker one-liner, volume-mount rule, base/fields/links/lookups/rollups/formula arc, views, REST API curl patterns, Node SDK, webhooks, CSV import, ERD view, snapshots), and the community Docker guide by dev.to/wimadev (SQLite file location under /usr/app/data, Postgres container wiring, JWT secret).

Frequently asked questions

Is NocoDB really free?

The open-source core you self-host is free — the installer, the spreadsheet UI, the relational fields, and the full REST API cost nothing. Paid plans exist for the cloud-hosted version and for enterprise features; the beginner arc in this guide uses nothing paid.

Does NocoDB replace my database?

NocoDB sits on top of a database, it does not replace it. Your data lives in Postgres (or SQLite/MySQL/SQL Server), and you can connect to that database directly with any client alongside NocoDB. Think of NocoDB as the friendly UI and API layer, not the storage engine.

Can I point NocoDB at an existing Postgres database?

Yes. You can create a base by connecting to an external database instead of creating tables from scratch — NocoDB then gives your existing tables a spreadsheet UI instantly. This is one of its most underused features for teams that already have data somewhere.

Where do attachments go, and is there a size limit?

Attachments are stored in NocoDB's storage (local disk by default, S3-compatible storage configurable). The default maximum is 20 MiB per attachment and 10 attachments per cell, both adjustable with environment variables. Include attachments in your backup plan — a pg_dump alone does not save them.

Is it safe to expose self-hosted NocoDB to the internet?

Yes, if you do the production checklist: run behind HTTPS (the single-server installer sets up Traefik + Let's Encrypt), restrict the firewall to 22/80/443, set a real NC_AUTH_JWT_SECRET, keep docker.env at 600 permissions, and pin image tags. Never expose the raw quickstart port 8080 to the world.