Table definition template, sample & how-to

What is a table definition?

What to include in a table definition

Filling in at least these attributes per column makes the definition ready for implementation and review.

Logical name

Human-facing name (e.g. Email). Used in UI labels and spec discussions.

Physical name

Actual DB column name (e.g. email). Snake_case is common.

Data type

uuid / varchar(n) / integer / numeric(p,s) / boolean / timestamptz, etc. Note length/precision.

Primary key (PK)

Uniquely identifies a row. uuid + gen_random_uuid(), or an identity sequence.

NOT NULL

Whether the column is required.

Default

Value used when unspecified (e.g. now(), 'member', gen_random_uuid()).

Unique / FK / Index

Add UNIQUE, FOREIGN KEY, and INDEX where needed.

Description

Meaning, constraints, expected values — for review and future maintenance.

Copy-paste template (Markdown sample)

Copy the table below and adapt it to your table (a users example). It’s Markdown, so it pastes into GitHub / Notion / issues. Prefer Excel? d-bye can generate a real Excel table definition straight from your DB design, for free (see below).

| Logical name | Physical name | Type | PK | NOT NULL | Default | Description |
|--------------|---------------|------|:--:|:--------:|---------|-------------|
| ID | id | uuid | x | x | gen_random_uuid() | Primary key |
| Email | email | varchar(255) |  | x |  | Login ID (unique) |
| Name | name | varchar(100) |  | x |  | Display name |
| Role | role | varchar(20) |  | x | 'member' | Permission role |
| Created at | created_at | timestamptz |  | x | now() | Created timestamp |
| Updated at | updated_at | timestamptz |  | x | now() | Updated timestamp |

How to write a table definition (steps)

1. State the table’s purpose in one line (e.g. users = login & permissions).
2. Choose the primary key (uuid + gen_random_uuid() or a sequence).
3. List the columns and fill in logical name, physical name, and data type.
4. Decide NOT NULL, defaults, and length/precision per column.
5. Add unique constraints, foreign keys (FK), and indexes.
6. Write the description (meaning and constraints) and get it reviewed.
7. Turn it into CREATE TABLE (d-bye generates this for you, free).

With d-bye: your definition becomes a free Excel doc and DDL

d-bye treats the design spec as the single source of truth: you define tables, columns, constraints, and FKs visually. Building the same users definition above gets you this PostgreSQL DDL and a downloadable Excel table definition (.xlsx) — free, no signup required.

CREATE TABLE users (
  id          uuid         PRIMARY KEY DEFAULT gen_random_uuid(),
  email       varchar(255) NOT NULL UNIQUE,
  name        varchar(100) NOT NULL,
  role        varchar(20)  NOT NULL DEFAULT 'member',
  created_at  timestamptz  NOT NULL DEFAULT now(),
  updated_at  timestamptz  NOT NULL DEFAULT now()
);

• ✓DDL (switch PostgreSQL / SQLite) and the Excel table definition (.xlsx) are free — no account, no credit card.
• ✓Want CRUD screens (React/TypeScript) and an API (Rust or Node.js) too? Export everything as a ZIP on a paid plan.
• ✓Every generation passes type checks and a compile check, so it never ships broken code.
• ✓Edit the definition and regenerate — the spec stays the single source of truth, ending Excel/code duplication.

FAQ

What are the minimum fields in a table definition?

Logical name, physical name, data type, primary key, NOT NULL, default, and description. Adding unique constraints, foreign keys, indexes, and length/precision makes it directly implementable.

Is there a tool that auto-generates a table definition?

Yes. Design your tables, columns, and relations visually in d-bye’s DB Builder, and download an Excel table definition (.xlsx) plus PostgreSQL/SQLite DDL — free, no signup required. See the dedicated table definition generator page for the full walkthrough.

Excel or Markdown — which is better?

Either, per your team’s convention. Excel is easy to distribute; Markdown reviews well (diffs). d-bye goes further by making the definition the source of working code, so it can generate the Excel doc, DDL, and screens directly — the definition and code never diverge.

Can I auto-generate CREATE TABLE from the definition?

In d-bye, the visual DB design generates PostgreSQL/SQLite DDL for free. CRUD screens and an API are also available as a one-click generation on a paid plan. With Excel alone, you write the DDL by hand.

How is it different from an ER diagram?

An ER diagram shows relationships between tables; a table definition rigorously fixes one table’s columns and constraints. They complement each other.