DEV Community: Varun Krishnan

Django Auth Tables and Permissions Explained

Varun Krishnan — Thu, 10 Sep 2026 14:34:00 +0000

Django creates 5 core auth tables: auth_user, auth_group, auth_permission, django_content_type, and two join tables (auth_user_groups, auth_group_permissions). The permission system is built on content types each model gets a default add, change, delete, and view permission, and you can create custom ones.

The core tables

auth_user

Column	Type	What it means
`id`	int (PK)	Auto-incrementing primary key.
`password`	varchar(128)	Hashed password (PBKDF2 by default).
`last_login`	datetime	When the user last logged in. Null if never.
`is_superuser`	bool	Bypasses all permission checks.
`username`	varchar(150)	Unique username.
`first_name`	varchar(150)	User's first name.
`last_name`	varchar(150)	User's last name.
`email`	varchar(254)	Email address. Not necessarily unique.
`is_staff`	bool	Can access the Django admin.
`is_active`	bool	Set to False instead of deleting users.
`date_joined`	datetime	Registration time.

auth_group

Column	Type	What it means
`id`	int (PK)	Auto-incrementing ID.
`name`	varchar(150)	Unique group name (e.g., "Editors", "Moderators").

Groups are role containers. Assign permissions to groups, then add users to groups.

auth_permission

Column	Type	What it means
`id`	int (PK)	Auto-incrementing ID.
`name`	varchar(255)	Human-readable name (e.g., "Can add post").
`content_type_id`	int (FK)	Which model this permission applies to.
`codename`	varchar(100)	Code identifier (e.g., `add_post`).

Each model gets 4 default permissions: add_modelname, change_modelname, delete_modelname, view_modelname.

django_content_type

Column	Type	What it means
`id`	int (PK)	Auto-incrementing ID.
`app_label`	varchar(100)	The Django app (e.g., `blog`).
`model`	varchar(100)	The model name (e.g., `post`).

This table maps every model in your project to an ID. The permission system uses it to know which model a permission applies to.

auth_user_groups

Join table for many-to-many: users ↔ groups.

Column	Type	What it means
`id`	int (PK)	Auto-incrementing ID.
`user_id`	int (FK)	→ `auth_user.id`.
`group_id`	int (FK)	→ `auth_group.id`.

auth_group_permissions

Join table for many-to-many: groups ↔ permissions.

Column	Type	What it means
`id`	int (PK)	Auto-incrementing ID.
`group_id`	int (FK)	→ `auth_group.id`.
`permission_id`	int (FK)	→ `auth_permission.id`.

How permissions work

User ──M──M── Group ──M──M── Permission ──M──1── ContentType

A permission is tied to a content type (a specific model).
Groups collect permissions (e.g., "Editors" get add_post, change_post).
Users are added to groups to inherit their permissions.
You can also assign permissions directly to users (bypass groups).

In code:

# Check permission
user.has_perm('blog.add_post')

# Add user to group
from django.contrib.auth.models import Group
editors = Group.objects.get(name='Editors')
user.groups.add(editors)

# Create custom permission
from django.contrib.auth.models import Permission
from django.contrib.contenttypes.models import ContentType
from blog.models import Post
content_type = ContentType.objects.get_for_model(Post)
custom_perm = Permission.objects.create(
    codename='publish_post',
    name='Can publish post',
    content_type=content_type,
)

What to change

Add a role field to auth_user if you need simple role-based access (or use groups).
Add an avatar field for profile pictures.
Create custom permissions for fine-grained access control (e.g., publish_post, archive_post).
Add unique=True to email if you want unique emails.

What to leave alone

Don't modify django_content_type it's managed by Django's migration framework.
Don't change auth_permission.codename it's referenced by has_perm() and decorators.
Don't delete auth_user.is_active use it instead of deleting users (preserves foreign keys).

FAQ

Does Django create all these tables automatically?

Yes. Running python manage.py migrate creates all auth tables. They're part of Django's built-in django.contrib.auth app.

Can I use Django without the permission system?

Yes. Remove django.contrib.auth from INSTALLED_APPS and you lose the permission tables but keep the auth_user model (or replace it entirely).

What's the difference between `is_superuser` and `is_staff`?

is_superuser bypasses all permission checks. is_staff only controls access to the Django admin. A superuser automatically has is_staff=True.

How do I see my Django auth tables?

Use dbdiagramr paste your connection string and get a visual schema of your Django auth tables.

NextAuth / Auth.js Database Schema Explained

Varun Krishnan — Mon, 07 Sep 2026 18:30:00 +0000

The short version

NextAuth (now Auth.js) creates 4 tables in your database: users, accounts, sessions, and verification_tokens. The users and accounts tables have a one-to-one relationship via accounts.user_id. Sessions link to users via sessions.user_id. Verification tokens are short-lived and self-cleaning.

The 4 tables

users

Column	Type	What it means
`id`	text / UUID	Primary key. Generated by NextAuth.
`name`	text	Display name from the OAuth provider (Google, GitHub, etc.)
`email`	text	User's email. May be null if the provider doesn't share it.
`email_verified`	timestamp	When the email was verified. Null if never verified.
`image`	text	Profile picture URL from the provider.
`created_at`	timestamp	When the user first signed in.
`updated_at`	timestamp	Last profile sync from the provider.

accounts

This table links a user to an OAuth provider. One user can have multiple accounts (e.g., Google + GitHub).

Column	Type	What it means
`id`	text / UUID	Primary key.
`user_id`	text	Foreign key → `users.id`.
`type`	text	Always `"oauth"` or `"oidc"`.
`provider`	text	`"google"`, `"github"`, `"discord"`, etc.
`provider_account_id`	text	The provider's unique ID for this user.
`refresh_token`	text	OAuth refresh token (encrypted in production).
`access_token`	text	OAuth access token (encrypted in production).
`expires_at`	integer	When the access token expires (Unix timestamp).
`token_type`	text	Usually `"Bearer"`.
`scope`	text	Permissions granted by the provider.
`id_token`	text	OIDC ID token (if using OIDC).
`session_state`	text	Provider-specific session state.

sessions

Active sessions for each user. NextAuth creates a new row here on every sign-in.

Column	Type	What it means
`id`	text / UUID	Primary key.
`session_token`	text	The session token stored in the user's cookie.
`user_id`	text	Foreign key → `users.id`.
`expires`	timestamp	When this session expires.

verification_tokens

Short-lived tokens for email verification, password reset, etc. Self-cleaning old tokens are deleted automatically.

Column	Type	What it means
`identifier`	text	Email or user ID the token is for.
`token`	text	The actual token value.
`expires`	timestamp	When this token expires.

How they connect

users ──1──1── accounts
   │
   1
   │
   ∞
sessions

users ──1──∞── verification_tokens (via identifier)

One user → one or more accounts (Google, GitHub, etc.)
One user → many sessions (different devices/browsers)
Verification tokens are temporary and don't have a foreign key

What to change

Add a role column to users if you need role-based access control.
Add a phone_number column to users if you're using SMS auth.
Encrypt access_token and refresh_token in production NextAuth doesn't do this by default.

What to leave alone

Don't modify the verification_tokens table it's managed automatically.
Don't change the session_token format it's a signed JWT.
Don't add indexes to provider_account_id unless you're querying it directly (it's already unique).

FAQ

Does NextAuth store passwords?

No. NextAuth is an OAuth-first library. It doesn't handle passwords. If you need email/password auth, use next-auth/providers/credentials with bcrypt, or use a service like Clerk or Lucia.

How do I see what's in my NextAuth tables?

Use dbdiagramr paste your connection string and get a visual schema of your NextAuth tables in seconds.

Can I add custom fields to the users table?

Yes. Add columns to the users table directly. NextAuth will ignore columns it doesn't know about, so you can safely add role, phone_number, preferences, etc.

What happens when a user deletes their account?

NextAuth doesn't cascade deletes by default. You need to manually delete from users, accounts, and sessions. Or add ON DELETE CASCADE to your foreign key constraints.

Is Auth.js the same as NextAuth?

Yes. Auth.js is the rebranded version of NextAuth. The database schema is identical. If you're on NextAuth v4, you're using the same tables.

Laravel Default Database Tables Explained

Varun Krishnan — Thu, 03 Sep 2026 17:00:00 +0000

A fresh Laravel install creates 7-8 tables depending on your packages. The core ones are users, password_resets, failed_jobs, and personal_access_tokens. The cache, sessions, jobs, and batches tables are only created if you run the corresponding Artisan commands. None of them are sacred -- you can rename, extend, or replace any of them.

The core tables

users

Column	Type	What it means
`id`	bigint (PK)	Auto-incrementing primary key.
`name`	varchar(255)	User's display name.
`email`	varchar(255)	Unique email address.
`email_verified_at`	timestamp	When email was verified. Null if unverified.
`password`	varchar(255)	Hashed password (bcrypt). Never store plain text.
`remember_token`	varchar(100)	Token for "remember me" functionality.
`created_at`	timestamp	Registration time.
`updated_at`	timestamp	Last profile update.

password_resets

Column	Type	What it means
`email`	varchar(255)	The email requesting a reset.
`token`	varchar(255)	The reset token (hashed).
`created_at`	timestamp	When the token was generated.

This table is self-cleaning -- old tokens are garbage collected.

failed_jobs

Column	Type	What it means
`id`	bigint (PK)	Auto-incrementing ID.
`uuid`	varchar(255)	Unique identifier for the job.
`connection`	text	Queue connection that failed.
`queue`	queue name	Which queue the job was on.
`payload`	longText	The job's serialized data.
`exception`	longText	The full exception stack trace.
`failed_at`	timestamp	When it failed.

Use this table to debug failed queue jobs. The exception column has the full stack trace.

personal_access_tokens

Created by Laravel Sanctum for API token authentication.

Column	Type	What it means
`id`	bigint (PK)	Auto-incrementing ID.
`tokenable_type`	varchar(255)	The model this token belongs to (e.g., `App\Models\User`).
`tokenable_id`	bigint	The ID of that model.
`name`	varchar(255)	Token name (e.g., "Mobile App").
`token`	varchar(60)	The hashed token value.
`abilities`	text	JSON array of allowed abilities (e.g., `["*"]`).
`last_used_at`	timestamp	When the token was last used.
`expires_at`	timestamp	When the token expires (null = never).

Optional tables

sessions

Created by php artisan session:table. Stores HTTP session data in the database instead of files.

Column	Type	What it means
`id`	varchar(255) (PK)	Session ID (from the cookie).
`user_id`	bigint (FK)	The user this session belongs to. Null for guests.
`ip_address`	varchar(45)	Client IP.
`user_agent`	text	Browser user agent string.
`payload`	longText	Serialized session data.
`last_activity`	integer	Unix timestamp of last activity.

cache

Created by php artisan cache:table. Stores key-value cache entries in the database.

Column	Type	What it means
`key`	varchar(255) (PK)	Cache key.
`value`	longText	Serialized cache value.
`expiration`	integer	Unix timestamp when it expires.

jobs

Created by php artisan queue:table. Stores pending queue jobs.

Column	Type	What it means
`id`	bigint (PK)	Auto-incrementing ID.
`queue`	varchar(255)	Queue name.
`payload`	longText	Serialized job data.
`attempts`	integer	How many times it's been tried.
`reserved_at`	integer	When it was reserved by a worker.
`available_at`	integer	When it can be picked up.
`created_at`	integer	When it was dispatched.

batches

Created by php artisan queue:batches-table. Tracks batch progress for parallel job processing.

Column	Type	What it means
`id`	bigint (PK)	Auto-incrementing ID.
`name`	varchar(255)	Batch name.
`total_jobs`	integer	Total jobs in the batch.
`pending_jobs`	integer	Jobs still to run.
`failed_jobs`	integer	Jobs that failed.
`failed_job_ids`	longText	JSON array of failed job IDs.
`options`	longText	Serialized batch options.
`cancelled_at`	timestamp	When cancelled (null if not).
`created_at`	timestamp	When the batch was created.
`finished_at`	timestamp	When the batch completed.

What to change

Add a role column to users for role-based access.
Add a phone_number column for SMS auth.
Add an avatar_url column for profile pictures.
Rename password_resets to password_reset_tokens (Laravel 8+ convention).

What to leave alone

Don't modify the failed_jobs.exception column -- it needs to hold full stack traces.
Don't remove personal_access_tokens.tokenable_type -- it's a polymorphic relation.
Don't add indexes to cache.key -- it's already the primary key.

FAQ

Does Laravel create all these tables automatically?

No. Only users, password_resets, and failed_jobs are created by php artisan migrate. The others (sessions, cache, jobs, batches) require separate Artisan commands.

Can I use Redis instead of the database tables?

Yes. Laravel supports Redis for sessions, cache, and queues out of the box. Switch your .env driver to redis and the database tables become unnecessary.

What's the difference between `password_resets` and `password_reset_tokens`?

Same table, different names. Laravel 8+ renamed it to password_reset_tokens. If you're on an older version, it's still password_resets.

How do I visualize my Laravel schema?

Use dbdiagramr -- paste your connection string and get a visual schema of all your Laravel tables.

What Is an ER Diagram and How to Read One

Varun Krishnan — Thu, 03 Sep 2026 03:00:00 +0000

The short version

An entity-relationship diagram is a picture of your database's tables, columns, and connections. You read it left to right: boxes are tables, lines are foreign-key relationships, and the symbols on each end tell you one-to-one, one-to-many, or many-to-many.

What each part means

Entities (tables)

Every box is a table. The bold name on top is the table name. The list underneath is the columns. Primary keys are usually marked with a key icon or bolded. Foreign keys have a link icon.

Example:

users
id (PK)
name
email
created_at

Attributes (columns)

Each line under the table name is a column. Common types you'll see:

id -- primary key (unique identifier)
name, email -- simple text fields
created_at -- timestamp of when the row was inserted
user_id -- foreign key pointing to another table (look for the line connecting it)

Relationships (lines)

Lines between boxes represent foreign key references. If you see a line from orders.user_id to users.id, that means "each order belongs to one user."

Cardinality (symbols)

The symbols at the end of each line tell you how many:

1 -- ∞ (one to many): one user has many orders. This is the most common.
1 -- 1 (one to one): one user has one profile.
∞ -- ∞ (many to many): many users have many roles. Usually resolved with a join table.

Reading a real example

Suppose you see this diagram:

users ──1──∞── orders ──1──∞── order_items ──∞──1── products
   │
   1
   │
   ∞
addresses

Reading left to right:

One user has many orders.
One order has many order items.
One product appears in many order items.
One user has many addresses.

The join table here is order_items ,it connects orders and products in a many-to-many relationship.

Why ER diagrams matter

Debugging: "Why is my query returning duplicates?" look for a missing join or unintended many-to-many.
Onboarding: New engineers understand the data model in 5 minutes instead of reading migration files.
Schema reviews: Spot missing indexes, redundant tables, or circular dependencies before they hit production.

Common mistakes

Assuming every line is one-to-many. Check the symbols. A many-to-many without a join table is a red flag.
Ignoring nullable columns. A dashed line or optional symbol means the relationship is optional.
Forgetting to check the foreign key direction. orders.user_id → users.id is different from users.order_id → orders.id.

Try it yourself

Open your own database schema in dbdiagramr and trace the foreign keys. Start from the table you're most familiar with and follow the lines outward.

FAQ

What does PK mean in an ER diagram?

PK stands for primary key the unique identifier for each row in a table. It's usually id and is referenced by foreign keys in other tables.

What does FK mean?

FK stands for foreign key a column in one table that points to the primary key of another table. It creates the relationship between the two tables.

How do you show a many-to-many relationship?

With a join table. For example, users ↔ user_roles ↔ roles. The user_roles table holds user_id and role_id foreign keys, and the many-to-many becomes two one-to-many relationships.

What's the difference between an ER diagram and a schema diagram?

They're the same thing in practice. ER diagram is the academic term; schema diagram is the engineering term. Both show tables, columns, and relationships.

Do I need to draw an ER diagram by hand?

No. Tools like dbdiagramr generate ER diagrams automatically from your Supabase, Neon, or PostgreSQL connection string. Paste your connection string and get a visual schema in seconds.

Supabase Auth Schema Explained: Users, Identities, Sessions

Varun Krishnan — Tue, 25 Aug 2026 15:00:00 +0000

The short version

Supabase stores auth in a separate auth schema not your public schema. Every user has exactly one row in auth.users, one or more rows in auth.identities (one per login provider), and can hold multiple active auth.sessions, each backed by a refresh_tokens row. If you've ever poked at a Supabase database and seen a cluster of tables you didn't create, these are the ones, and this is what they do.

auth.users 1───* auth.identities
auth.users 1───* auth.sessions
auth.sessions 1───* auth.refresh_tokens

Why an `auth` schema at all

Supabase deliberately keeps auth separate from your app's tables. Your public schema is where your own models live; auth is locked down and managed by the auth service (GoTrue). You read from it, you don't write to it. That separation is why your migrations never touch these tables and why introspecting a Supabase database shows you a schema you didn't write.

The four tables that matter

auth.users one row per user.

Column	What it holds
`id`	UUID primary key; the user's stable identifier
`email` / `phone`	Contact + login identity
`encrypted_password`	Bcrypt hash (only for email/password auth)
`raw_app_meta_data`	Provider claims: `provider`, `providers`, `email`
`raw_user_meta_data`	Custom metadata you set on the user
`is_sso_user`	True when sign-in came through SSO
`confirmed_at`	When the primary identity was confirmed

auth.identities - one row per login method.

A user signing in with email and GitHub gets two rows here. provider_id is the provider's identifier for that user; identity_data is the raw claim payload (name, avatar, email) the provider returned. The FK user_id → users.id is what joins them.

auth.sessions - a browser/token session.

One session per logged-in device roughly. aal (assurance level), user_agent, ip, and not_after all live here. factor_id links to MFA factors when you have TOTP enabled.

auth.refresh_tokens - the long-lived token backing a session.

Access tokens are short (JWT, ~1h). Refresh tokens are long and stored here, revoked flag included, with parent used to detect token reuse and rotate.

How they relate (the joins you'll actually write)

select u.email, i.provider, s.id as session_id
from auth.users u
join auth.identities i on i.user_id = u.id
join auth.sessions  s on s.user_id = u.id;

That query is the 80% case: "who is signed in, through which provider, on which sessions." Every relationship is a plain foreign key identities.user_id, sessions.user_id, refresh_tokens.session_id which is exactly what a schema diagram turns into readable arrows. If you'd rather trace them visually, paste a read-only connection string into dbdiagramr and it will pull and render the same tables.

What's usually NOT your business

auth.instances, auth.audit_log_entries, and auth.schema_migrations are Supabase's own bookkeeping. audit_log_entries records admin actions inside the auth service; instances is leftover multi-tenancy plumbing. If a diagram shows them, ignore them your reads live in the other four.

Practical tips

Never write to auth tables directly. Use the Supabase client / Admin API. Direct inserts create inconsistent state (orphaned identities, unhashed passwords).
Foreign-key joins work across schemas. auth.users.id is the same UUID you'd use in public join public.profiles.user_id → auth.users.id for your own profile data.
A user with no identity row is a sign of trouble. Every normal user has at least one. Orphaned identities without a users row point at a cleanup/import bug.
Sessions accumulate. Old sessions linger; your diagram showing many sessions per user isn't a leak, it's devices and tabs.

This whole picture is easier to keep straight when you can see it. The Supabase auth schema diagram was generated by introspecting a live Supabase database users, identities, sessions, and refresh_tokens with their foreign keys rendered as relationships. Open it next time you're debugging a sign-in flow.

FAQ

Where is the Supabase auth schema?
In the auth schema, separate from your public schema auth.users, auth.identities, auth.sessions, auth.refresh_tokens, plus internal tables.

What is auth.users used for?
It's the single source of truth for who can sign in. One row per user, with email/phone, password hash, metadata, and provider flags.

Why does one user have multiple identities?
Each login method is a separate auth.identities row. Email + GitHub + Google = three rows, all pointing at the same users.id.

What's the difference between a session and a refresh token?
A session is the device/token context; the refresh token is the long-lived credential that renews the short-lived JWT. One session maps to one refresh token chain.

Can I join auth tables to my public tables?
Yes the auth schema isn't isolated for queries. Use auth.users.id as the join key with your public.* tables.

Try It

Live: https://dbdiagramr.space

GitHub: https://github.com/VarunKvK/dbdiagramr

If this is useful to you, a GitHub star helps a solo dev keep building in public. I started this tool because I kept needing to visualize exactly these tables after reading migrations.

PostgreSQL Connection String: Supabase, Neon, Railway

Varun Krishnan — Thu, 20 Aug 2026 14:30:00 +0000

The short version

A PostgreSQL connection string is a single URL that tells a client how to reach your database. It looks like this:

postgresql://postgres:[YOUR-PASSWORD]@db.abcdefghij.supabase.co:5432/postgres

Every provider builds on the same format, and the differences that trip people up are almost never the syntax. They're the port and host your provider hands you. Supabase alone has three different strings for the same database, and two of them won't work from serverless apps.

Anatomy of a connection string

postgresql://  user  :  password   @     host        :  port  /  database
     |          |         |              |              |          |
  protocol    username  secret         server        port       db name

Part	Example	Notes
Protocol	`postgresql://`	`postgres://` also works in most clients
User	`postgres`	In Supabase: `postgres.[project-ref]` on pooler URLs
Password	`[your-password]`	URL-encode special characters (`@` → `%40`)
Host	`db.xxxx.supabase.co`	The server; provider-specific
Port	`5432`	6543 = transaction pooler (Supabase/Neon)
Database	`postgres`	Default database name

You can append query parameters after the database. The two you'll actually meet are ?sslmode=require (force TLS) and ?channel_binding=require.

Supabase: three strings for one database

Supabase is where most people hit the connection-string wall, because the right string depends entirely on where your code runs:

Mode	Host	Port	Best for
Direct	`db.[project-ref].supabase.co`	`5432`	Migrations, `pg_dump`, long-lived backend
Shared pooler (session)	`aws-[region].pooler.supabase.com`	`5432`	Persistent backend on IPv4-only networks
Shared pooler (transaction)	`aws-[region].pooler.supabase.com`	`6543`	Serverless / edge / short-lived connections

# Direct
postgresql://postgres:[YOUR-PASSWORD]@db.[project-ref].supabase.co:5432/postgres

# Shared pooler session mode
postgres://postgres.[project-ref]:[YOUR-PASSWORD]@aws-[REGION].pooler.supabase.com:5432/postgres

# Shared pooler transaction mode (the one most apps want)
postgres://postgres.[project-ref]:[YOUR-PASSWORD]@aws-[REGION].pooler.supabase.com:6543/postgres

The gotcha: direct connections run on IPv6. On an IPv4-only network you get an ENOTFOUND, not a friendly error, just a silent failure to connect. The shared pooler is IPv4-only and fixes it. And if your app is serverless (Vercel functions, edge runtimes, Lambda), use transaction mode (port 6543). It's built for the many-short-connections pattern serverless forces.

This exact confusion is why tools that accept a connection string usually ask you to grab the transaction pooler URL. dbdiagramr, for instance, has a step in its how-it-works guide telling you to select the Transaction pooler in the Supabase dashboard before pasting. Otherwise the connection silently fails from IPv4-only hosts.

Neon: pooled vs direct

Neon makes the two variants explicit in the hostname:

# Pooled (through PgBouncer, use by default)
postgresql://user:pass@ep-cool-rain-123456-pooler.us-east-2.aws.neon.tech/neondb?sslmode=require

# Direct
postgresql://user:pass@ep-cool-rain-123456.us-east-2.aws.neon.tech/neondb?sslmode=require

Rule of thumb: use the -pooler host unless you have a specific reason not to. It handles thousands of concurrent clients and is the right call for serverless. Grab both from the Connect button in the Neon dashboard.

Railway: the plain standard

Railway gives you a no-frills connection string with no pooler decision to make:

postgresql://postgres:[YOUR-PASSWORD]@[host].railway.app:5432/railway

It's the textbook format, which makes it the easiest one to read and the easiest to misplace a password in. Store it in Railway's Variables tab as DATABASE_URL, never in code.

All the formats in one table

Provider	Connection string shape
Standard / Railway	`postgresql://user:pass@host:5432/db`
Supabase (direct)	`postgresql://postgres:pass@db.[ref].supabase.co:5432/postgres`
Supabase (session pooler)	`postgres://postgres.[ref]:pass@aws-[region].pooler.supabase.com:5432/postgres`
Supabase (transaction pooler)	`postgres://postgres.[ref]:pass@aws-[region].pooler.supabase.com:6543/postgres`
Neon (pooled)	`postgresql://user:pass@ep-xxx-pooler.region.aws.neon.tech/db?sslmode=require`
Neon (direct)	`postgresql://user:pass@ep-xxx.region.aws.neon.tech/db?sslmode=require`

Gotchas that will actually bite you

IPv4 vs IPv6. Supabase direct connections are IPv6. If you're on an IPv4-only network or using a tool on an IPv4-only host, you'll get ENOTFOUND and no obvious reason why. The pooler strings are IPv4 and sidestep it.
Serverless wants the transaction pooler. Long-lived backends can hold a connection. Serverless functions can't. Each invocation opens a new one. Session-pooling chokes on that pattern; transaction pooling (port 6543) exists for exactly it.
A connection string is a secret. It contains your password in plain text. Never commit it, never paste it into a shared doc, and use a pooler/proxy string when a third-party tool needs it. Most good tools never store it beyond the one request. (dbdiagramr introspects your schema and discards the string immediately.)
URL-encode passwords. A password containing @, :, or / breaks the URL. Encode those characters (@ → %40) before pasting.

Curious what that pooler URL actually contains after it connects? The Supabase auth schema diagram was created by introspecting a live Supabase database through a transaction pooler string. Users, identities, sessions, and refresh_tokens rendered as relationships.

FAQ

What is a PostgreSQL connection string?
It's a single URL containing everything needed to reach a Postgres database: protocol, username, password, host, port, and database name (e.g. postgresql://user:pass@host:5432/db).

Should I use a direct connection or a pooler?
For a persistent backend that can hold a connection open, direct is fine. For serverless or edge functions that open a connection per invocation, use a pooler, either Supabase transaction mode (port 6543) or a Neon -pooler host.

Why does my Supabase connection fail with ENOTFOUND?
You're probably using the direct connection string over IPv4, and Supabase's direct endpoint is IPv6. Switch to a shared pooler string (aws-[region].pooler.supabase.com) or add the IPv4 add-on.

Is my connection string a secret?
Yes, it's your password in plain text. Keep it in environment variables, rotate it if it leaks, and only hand it to tools that won't store it.

Try It

Live: https://dbdiagramr.space

GitHub: https://github.com/VarunKvK/dbdiagramr

If this is useful to you, a GitHub star helps a solo dev keep building in public. I hit the IPv6 wall the first time I tried to visualize a Supabase database from a serverless app. Figured others would save the hour.

How to Visualize a PostgreSQL Schema: 5 Ways Compared

Varun Krishnan — Tue, 18 Aug 2026 14:30:00 +0000

The short version

Your Postgres schema is perfectly readable to the database and almost unreadable to a human. The tables, columns, and foreign keys you need are spread across pg_catalog, information_schema, and a few hundred lines of migration SQL. Visualization means collapsing all of that into a picture you can actually reason about.

There are five practical ways to get there. They are not equivalent. Each makes a different trade between speed, depth, and how current the diagram stays.

The five ways at a glance

Method	Setup	Interactive	Stays current	Best for
`psql` + `pg_catalog`	Zero	No	Always (it's live)	Quick inspection
IDE built-ins (pgAdmin, DBeaver)	Already installed	Partly	Snapshot, manual re-run	One-off look
Manual diagramming (draw.io, dbdiagram.io)	Short	Yes	Drifts (you maintain it)	Designing a new schema
Migrations → DDL (Prisma, Rails)	Medium	No	Re-run on change	Documenting from code
Live connection string (dbdiagramr)	None (paste URL)	Yes	Regenerate in 10 seconds	Understanding a real DB

1. psql and pg_catalog: the baseline

The fastest text-only view is psql. \dt lists all tables, \d table_name shows one table's structure including its foreign keys. To see every relationship in one shot, query information_schema directly:

SELECT tc.table_name,
       kcu.column_name,
       ccu.table_name AS foreign_table_name,
       ccu.column_name AS foreign_column_name
FROM information_schema.table_constraints tc
JOIN information_schema.key_column_usage kcu
  ON tc.constraint_name = kcu.constraint_name
JOIN information_schema.constraint_column_usage ccu
  ON ccu.constraint_name = tc.constraint_name
WHERE tc.constraint_type = 'FOREIGN KEY'
  AND tc.table_schema = 'public';

Precise and always available. But it's a list, not a picture. Past a dozen tables you're reconstructing the graph in your head, which is exactly what visualization is supposed to remove.

2. IDE built-ins: pgAdmin, DBeaver, DataGrip

If you already have a GUI client, it probably ships with an ER diagram generator:

pgAdmin 4: right-click the database → ERD For Database. Free, already installed. Auto-layout struggles past a few dozen tables, and it regenerates by hand.
DBeaver (Community is enough): open the ER Diagram tab. Genuinely free, cross-platform, exports PNG/SVG.
DataGrip: Diagrams → Show Visualization. The best-feeling interactive diagram of the three; paid, single-user.

The honest limitation they all share: any IDE-based diagram is a snapshot. Nothing to share but an exported image, and it drifts the moment someone runs a migration.

3. Manual diagramming: draw.io, dbdiagram.io, DrawSQL

The classic approach, and great for designing a schema you haven't built yet. dbdiagram.io and DrawSQL are excellent editors. You write DBML or drag tables, and get a clean diagram you can export, share, and version.

The catch is drift. The diagram is a hand-made copy of the schema at one moment in time. The day someone adds a column or a foreign key, the diagram is wrong. A wrong diagram is worse than none, because people trust it. Building it from scratch takes 30 minutes to an hour, and it's stale the moment a migration lands.

Use these when you're designing. They struggle to document a real schema over time.

4. Generate from your migrations

If your schema lives in migration files (Prisma, Drizzle, Rails, Flyway), you can derive the structure from code instead of a live connection:

# Dump structure only, never row data
pg_dump --schema-only mydb > schema.sql

Then feed the DDL to any SQL-to-diagram tool. This is the right path when you can't or don't want to expose credentials. The trade-off: it documents the migrations, not necessarily what's actually deployed. Regenerating on every change is automation you have to build and maintain.

5. Paste a live connection string: the "always current in 10 seconds" option

The approach that solves both accuracy and effort: point a tool at the real database and let it introspect the schema itself. No schema code, no hand-arranging, nothing to keep in sync. The diagram is what's in your database right now.

That's exactly what dbdiagramr does. You paste a PostgreSQL connection string into it and it:

Connects and reads the schema, structure only, never your row data
Queries information_schema for tables, columns, primary keys, and foreign keys
Renders an interactive ER diagram you can pan, zoom, drag tables around, and hover over to trace relationships
Exports as SVG or PNG

Because it introspects the live database, there's no drift to manage. Change a migration, paste the same string again, and you have an up-to-date diagram in under 10 seconds. Your connection string is never stored. It's introspected and discarded immediately.

Not sure what an ER diagram even looks like yet? The schema library has live diagrams of the Supabase auth, NextAuth.js, Laravel, and Django schemas you can pan and zoom before you connect your own database.

Why you should care about "stays current"

Every method above the last one shares the same failure mode: the diagram is a snapshot, and keeping it current is your problem. Walk into any team that's been around a while and you'll find a "schema diagram" in a wiki from eight months ago. A wrong diagram is worse than none. It's confidently wrong.

The test that settles it: how much work does it take to make this picture true again? If the answer is "re-export from my IDE" or "drag the boxes by hand one more time," the humans will stop doing it and the diagram will lie to you.

FAQ

What's the easiest way to generate an ER diagram from a Postgres database?
If you have a GUI client open, it's a built-in feature. pgAdmin's ERD For Database, DBeaver's ER Diagram tab, or DataGrip's visualization all generate one in a couple of clicks. For a shareable diagram that matches your database as it is right now, a live-introspection tool is fastest because there's nothing to maintain.

Can I create a Postgres ERD without connecting to the live database?
Yes. Run pg_dump --schema-only and feed the DDL to a SQL-to-diagram tool, or parse your migration files. That's the safer path when you can't or don't want to expose production credentials.

How do I keep a schema diagram up to date?
Manual tools require manual regeneration, so in practice they drift. The reliable fix is introspection: regenerate straight from the live database (a paste of the connection string) or wire documentation generation into CI.

Does pgAdmin make ER diagrams?
Yes. pgAdmin 4 includes an ERD tool. Right-click the database → ERD For Database, or Tools → ERD Tool. Free and built in, though the auto-layout is best on small-to-medium schemas.

How to choose

Just want a quick look? psql or your IDE's built-in diagram. Fast, local, gone tomorrow, which is fine.
Designing a new schema? draw.io, dbdiagram.io, or DrawSQL are the right tools for the job.
Need to understand a database that already exists, or document one that keeps changing? Introspect the live schema. That's the perspective that actually survives contact with real databases.

Try It

Live: https://dbdiagramr.space

GitHub: https://github.com/VarunKvK/dbdiagramr

If this is useful to you, a GitHub star helps a solo dev keep building in public. I got tired of hand-drawing diagrams that went stale. Figured others did too.

I Swapped My Hand-Rolled SVG ER Diagram for React Flow + dagre . Here's What It Cost and What It Won

Varun Krishnan — Thu, 13 Aug 2026 12:00:00 +0000

Where the story starts

I built dbdiagramr paste a PostgreSQL connection string, get an interactive ER diagram in under 10 seconds. The first version rendered everything as pure SVG I generated by hand. No canvas, no diagram library. That was a deliberate choice, and it worked.

But as I pushed it from "a demo" to "a product" with a schema library and homepage previews, the hand-rolled renderer started fighting me. So I swapped the rendering engine for React Flow v12 + dagre. This is that migration what broke, what I chose, and what the trade-offs actually look like in production.

The goal

Interactive diagrams on the homepage demo and every /schema/[slug] detail page
Hover a table → unrelated tables dim to 15% opacity so you can trace foreign-key relationships
The same diagram engine for static (SSG) pages and the client-side interactive canvas
PNG + SVG export that matches what's on screen
Keep pages fully static-server-rendered with a client hydration layer on top

What the first version did (and where it strained)

The MVP rendered a static grid with straight-line connectors. It was:

Exportable for free - SVG is the document, serialize and you're done
Zero dependencies - one pure function, schema in → SVG string out
Easy to reason about - four TypeScript types underpin the whole app

The first pain was foreign-key routing. A clean diagram won't draw a line from table A to table B if it slices through three unrelated tables. My first pass was a four-way conditional that picked which edge to exit from based on relative position (above/below/left/right). It worked for small schemas and got fiddly as schemas grew. I already knew I'd revisit it.

The real push, though, was interactivity and maintainability. To get hover-to-trace, drag, pan, zoom, and the relationship tracing, I was going to bolt a lot of custom logic onto raw SVG. React Flow already solves that nodes, edges, viewport, minimap, controls and it's MIT licensed.

Why dagre (and not the obvious alternative)

When you need a layout engine inside a diagram tool, the first name everyone mentions is ELK (via elkjs). I seriously considered it:

Great hierarchical layouts out of the box
Nice output

But there's one hard blocker for dbdiagramr: it's MIT-only. ELK is licensed under EPL-2.0 (and GPL-3.0 in places). Mixing that into an MIT product means taking on a license I don't want to reason about for a small open-source tool.

So: dagre. It's:

MIT - same license as the project
Synchronous - runs in static-generation with zero async plumbing (all four schema pages are built at build time, so dagre's sync API keeps things simple)
Ships its own TypeScript types - no @types/dagre needed

That combination was worth far more than a slightly better layout. The constraint turned an easy pick into the right pick.

import dagre from "@dagrejs/dagre";

export function layoutSchema(schema: Schema): Record<string, Rect> {
  const g = new dagre.graphlib.Graph();
  g.setGraph({ nodesep: 60, ranksep: 90, marginx: 40, marginy: 40, rankdir: "LR" });

  // add each table node, sized from its columns
  for (const table of schema.tables) {
    const { width, height } = tableSize(table);
    g.setNode(table.name, { width, height });
  }

  // foreign keys → edges
  for (const table of schema.tables) {
    for (const fk of table.foreignKeys) {
      g.setEdge(table.name, fk.referencesTable);
    }
  }

  dagre.layout(g);

  const layout: Record<string, Rect> = {};
  for (const table of schema.tables) {
    const node = g.node(table.name);
    layout[table.name] = { x: node.x, y: node.y, w: node.width, h: node.height };
  }
  return layout;
}

One renderer, two outputs

The key architectural move was keeping a single layout source of truth and letting two layers read from it:

renderDiagramSVG(schema, layout) - produces the static SVG that SSG pages and the PNG export use
<SchemaDiagram schema={...} /> - a React Flow canvas that consumes the same dagre layout, so the interactive diagram matches the static one pixel-for-pixel

That one function is what guarantees the homepage, the schema library thumbnails, and the detail-page interactive canvas all agree. No drift between "what you see" and "what you export".

The interactive layer

On top of dagre's layout, the React Flow layer gives:

Hover-to-trace - on hover, unrelated tables drop to 15% opacity (related stay at 100%); edges animate so you can follow the foreign key through the diagram
Custom nodes - a TableNode with row-anchored handles: FK columns get a source handle on the right, referenced columns a target handle on the left, with PK/FK badges
Cardinality on edges - 1 and * badges rendered via an edge label layer
Viewport extras - background zoom, minimap, and a download panel exporting SVG or PNG (PNG is rasterized at 2× for crisp export)

All of it sits on dagre's layout rankdir: LR, 60px node spacing, 90px rank separation so related tables end up grouped left-to-right instead of scattered.

What a real schema looks like when you do it

The site ships a free schema library rendered this way real public schemas introspected into the exact Schema type:

Supabase auth - 7 tables, 3 foreign keys
NextAuth.js / Auth.js - 4 tables, 2 relationships
Laravel 11 default - 7 tables
Django auth - 9 tables, 9 relationships

The big one, Django (9 tables, 9 relationships), is nearly a star topology most tables reference the auth user table. dagre handles it fine; the lesson is to let a real layout engine deal with that instead of my hand-rolled routing conditional.

Honestly, what did it cost?

A static model is simpler. The pure-SVG version truly was dependency-free. React Flow pulls in more code for edge routing, viewports, and type plumbing. That's a real trade, and I don't regret making it.
License is a design constraint. The MIT-only requirement is what made dagre the right call over ELK and it was worth reasoning at the outset rather than mid-refactor.

But what it bought:

Interactive relationship tracing the pure-SVG version never had the kind of thing I'd have spent weeks hand-building on raw SVG
One layout, two outputs an identical static renderer and canvas that never drift
Export that always matches the screen SVG or 2× PNG, straight from the live view

Honest limitations (still)

PostgreSQL only - no MySQL, SQLite, or MongoDB yet
Public schema only - custom schemas aren't supported yet
Real-time sync is still not a thing - you generate, you export, you're done
dagre handles the schema sizes here fine; at hundreds of tables I'd look at force layouts (and re-graph sync)

The takeaway

If you're drawing relationships, don't hand-roll the canvas/network code when a purpose-built, MIT-licensed library exists. Let the library own the viewport and interaction; you keep the part that matters a small, typed data model and a single renderer that powers both static and interactive output. My first instinct was "I can just draw this myself." It took a week of wiring to realize the library was doing me a favor the payoff is interactivity I'd have hand-built for far longer.

Tech Stack

Next.js 14 (App Router)
TypeScript
Tailwind CSS
pg for PostgreSQL
@xyflow/react (React Flow v12) for the canvas
@dagrejs/dagre for layout (MIT)
MIT licensed, fully self-hostable

I Built a PostgreSQL Schema Visualizer With Pure TypeScript SVG - No Diagramming Library

Varun Krishnan — Sat, 01 Aug 2026 18:04:13 +0000

The Problem

I manage a few side projects with PostgreSQL databases. Every time I add a table, change a column, or refactor a relationship, I have to update my ER diagram.

I was using draw.io. It works. But it's manual. And it's tedious.

Open the file. Drag a new box. Connect the lines. Repeat for every schema change. It takes 30 minutes to an hour, it gets stale the moment someone commits a migration, and then you're back to answering "wait, what does the schema actually look like?"

A coworker asks you that question. You open pgAdmin. You click through tables. You mentally assemble the picture. It's slow and it's only in your head.

There had to be a better way.

The Solution

dbdiagramr.

Paste your PostgreSQL connection string. Get an interactive ER diagram in under 10 seconds. Pan, zoom, hover over tables to trace relationships, drag tables around. Export as SVG or PNG.

How It Works

The whole flow is four steps:

You paste your connection string
A server API introspects information_schema for tables, columns, keys
A pure TypeScript function generates an SVG diagram
You pan, zoom, and explore

No Canvas. No heavy libraries. Just SVG.

The data model is deliberately small - four types:

type Column = {
  name: string;
  type: string;
  nullable: string;
  default: string | null;
  isPrimaryKey: boolean;
};

type ForeignKey = {
  column: string;
  referencesTable: string;
  referencesColumn: string;
};

type Table = {
  name: string;
  columns: Column[];
  foreignKeys: ForeignKey[];
};

type Schema = {
  tables: Table[];
};

Every diagram is just a Schema object. Everything else is rendering.

The Introspection

The server connects to your database and reads only the structure — never your data. For each table it runs three queries in parallel against information_schema:

-- Columns
SELECT column_name, data_type, is_nullable, column_default
FROM information_schema.columns
WHERE table_schema = 'public' AND table_name = $1
ORDER BY ordinal_position;

-- Primary keys
SELECT kcu.column_name
FROM information_schema.table_constraints tc
JOIN information_schema.key_column_usage kcu
  ON tc.constraint_name = kcu.constraint_name
WHERE tc.constraint_type = 'PRIMARY KEY'
  AND tc.table_schema = 'public'
  AND tc.table_name = $1;

-- Foreign keys
SELECT kcu.column_name,
       ccu.table_name AS foreign_table_name,
       ccu.column_name AS foreign_column_name
FROM information_schema.table_constraints tc
JOIN information_schema.key_column_usage kcu
  ON tc.constraint_name = kcu.constraint_name
JOIN information_schema.constraint_column_usage ccu
  ON ccu.constraint_name = tc.constraint_name
WHERE tc.constraint_type = 'FOREIGN KEY'
  AND tc.table_schema = 'public'
  AND tc.table_name = $1;

These run server-side in a single API route, get assembled into a typed Schema object, and get sent back as JSON. The client never touches the database directly.

Why SVG (and not Canvas)

I chose pure SVG for three reasons:

Accessible by default - text is text, colors are colors. No rasterization needed.
Exportable for free - SVG is the document. Serialize it and you're done.
No dependencies - the diagram generator is a pure function: schema in, SVG string out.

function generateDiagramSVG(schema: Schema): string {
  // grid layout
  // table cards → <g> elements
  // foreign keys → <line> with arrow markers
  return parts.join("\n");
}

That single function produces the whole diagram server-side or client-side. The interactive React component sits on top and layers on pan, zoom, drag, and hover highlighting roughly 400 lines.

For PNG export, I serialize the current SVG (with tight viewBox and inlined styles), draw it to a canvas, and let the browser encode it:

const svgString = serializeSvg(svgElement, positions);
const blob = new Blob([svgString], { type: "image/svg+xml;charset=utf-8" });
const img = new Image();
img.src = URL.createObjectURL(blob);
// draw to canvas, canvas.toBlob → PNG download

The Hard Part: Foreign Key Routing

The most interesting problem wasn't drawing the boxes - it was deciding where the connection lines exit each table.

A foreign key connects column A in table 1 to column B in table 2. But which edge of table 1 should the line leave from? If table 1 is above table 2, the line exits the bottom. If they're side by side, it exits the right side. If one is much taller, it gets complicated.

The naive version produced lines that crossed through unrelated tables and made the diagram unreadable.

The fix was a four-way conditional that decides based on relative position:

if (bottom <= tgt.y) {
  // source sits above target → line exits bottom, enters top
  x1 = cx; y1 = bottom;
  x2 = tCx; y2 = tTop;
} else if (pos.y >= tgt.y + tgt.h) {
  // source sits below target → line exits top, enters bottom
  x1 = cx; y1 = pos.y;
  x2 = tCx; y2 = tgt.y + tgt.h;
} else if (pos.x + pos.w <= tgt.x) {
  // source sits left of target → line exits right edge
  x1 = right; y1 = cy;
  x2 = tLeft; y2 = tCy;
} else if (pos.x >= tgt.x + tgt.w) {
  // source sits right of target → line exits left edge
  x1 = pos.x; y1 = cy;
  x2 = tRight; y2 = tCy;
}

Simple on paper. It still took a while to get right because the cases interact - and the fallback (overlapping boxes) matters more than you'd think.

Lessons Learned

A tiny data model wins. Four types. The whole app is built on them, and it keeps the mental overhead near zero.
The grid layout breaks at - 50 tables. A static grid is fine for most schemas but gets cluttered on big ones. Next step would be a force-directed layout or at least smarter clustering.
Shipping beats perfecting. I could have kept polishing the routing algorithm forever. Shipping it and getting real feedback taught me more than any extra week of tweaking.

Honest Limitations

I'll say the same thing I'd tell a friend:

PostgreSQL only. No MySQL, SQLite, or MongoDB yet.
Public schema only - custom schemas aren't supported yet.
No real-time sync. You generate, you export, you're done.
Static grid layout struggles past ~50 tables.

Tech Stack

Next.js 14 (App Router)
TypeScript
Tailwind CSS
pg for PostgreSQL
Pure SVG for diagrams
MIT licensed, fully self-hostable

The contract clause that almost cost me my entire codebase

Varun Krishnan — Sat, 06 Jun 2026 02:30:00 +0000

I almost signed it.

The project looked good. The client seemed reasonable. The money was fair. I'd been freelancing long enough to know the drill get the contract, skim it, sign it, start working.

This time, for no particular reason, I actually read it.
Buried in section 4 or maybe section 6, I don't remember exactly was a line that stopped me cold. Something about "pre-existing materials." Standard boilerplate, right? Except it wasn't.
The clause said that anything I brought into the project including tools, libraries, and code I'd written before the engagement would become the exclusive property of the client upon completion.

Let that sink in.

Every utility function I'd spent years refining. Every internal library I reused across client projects. Every tool I'd built for my own workflow. All of it. Theirs. The moment I delivered the project.

What "pre-existing materials" actually means

Most freelance contracts have an IP assignment clause. That's normal the client pays you to build something, they own what you built. Fair enough.

But "pre-existing materials" is different. It's the stuff you owned before you ever heard of this client. Your code. Your tools. Your background IP.

A well-written contract carves this out explicitly. Something like: "Contractor retains ownership of all pre-existing materials. Client receives a license to use them as incorporated into the deliverables."

A badly written or deliberately predatory contract does the opposite. It lumps everything together under one broad assignment clause and hopes you don't notice.
I noticed.

What I did

I pushed back. Told the client the clause needed to be amended before I could sign.

The response surprised me. They got defensive. Not "oh that's just boilerplate, of course we'll fix it" defensive. Like I'd caught them doing something they knew was wrong.

That told me everything I needed to know. I walked away from the project.

What to look for in any freelance contract

If you take nothing else from this, scan every contract you sign for these:

1. Pre-existing materials / background IP

Any clause that assigns ownership of things you brought to the project, not just what you built for it. Red flag if there's no
explicit carve-out retaining your ownership.

2. Perpetual non-competes

"During and after the term of this agreement" with no time limit. This means forever. A reasonable non-compete has a duration — 6 or 12 months. No duration means no end.

3. Unlimited liability

If something goes wrong — a bug, a security issue, anything — are you personally on the hook with no cap? Some contracts make you liable for damages that could exceed what you were even paid.

4. Payment at sole discretion

"Client may withhold payment for deliverables deemed unsatisfactory at Client's sole discretion." Translation: they can refuse to pay for any reason and you have no recourse.

5. Work for hire with no exceptions

Everything you create during the engagement becomes theirs. Fine for the deliverables. Not fine if it includes general tools, open source contributions, or personal projects you worked on simultaneously.

What a safe version looks like

Here's the rewrite I proposed for the pre-existing materials clause:

"Contractor retains all ownership of pre-existing materials, tools, and background technology used in the project. Client receives a perpetual, non-exclusive, royalty-free license to use such materials solely as incorporated into the deliverables. All intellectual property developed specifically for this project shall be owned by Client upon receipt of full payment."

That's it. Both parties are protected. Client gets what they paid for. You keep what you built before they ever hired you.
Most reasonable clients will accept this without argument. The ones who don't are telling you something important about how the rest of the engagement will go.

Why I built Clause

After this happened I started paying more attention to contracts. Talked to other freelancers. Turns out this isn't rare it's common.

Clients use broad boilerplate and count on developers being too busy, too eager, or too intimidated to read it carefully.

So I built a tool that does the reading for you.
Paste any contract into Clause and it flags the dangerous clauses explains what each one means in plain English, why it's risky, and suggests a fairer rewrite you can send back to the client.
It's free to use and doesn't require an account to try.

Clauseapp.space

If you've ever been burned by a contract clause or nearly missed on I'd genuinely like to hear about it in the comments.

How to Create Product GIFs for Your Landing Page (No Video Editing Required)

Varun Krishnan — Fri, 02 Jan 2026 18:24:08 +0000

The Brochure vs. The Demo

Imagine walking into an electronics store.
You see a sleek new laptop.
Do you just stare at the turned-off screen? No. You touch the trackpad. You open a window. You want to see it work.

Your landing page is that store.
But most SaaS landing pages are just... brochures.

They have beautiful, high-res, completely static screenshots. They force the user to read about the features instead of seeing the features.

And reading is hard work.

The 3-Second Rule
You have roughly 3 seconds to convince a visitor to stay on your site.

Static Image: The brain has to process the text, look at the UI, map the text to the UI, and simulate the interaction mentally. Cognitive load: High.
GIF/Video: The brain sees movement. It instantly understands "Clicking X does Y." Cognitive load: Low.
Motion is a cheat code for attention.

Why Not Just Use Video?
"Okay," you say. "I'll just embed a YouTube video."

You could. But videos are heavy. They require a click to play. They have sound (risky). They take over the experience.

GIFs are the sweet spot.

Autoplay: No click needed.
Silent: Safe for work.
Looping: Reinforces the core value proposition.
Lightweight: Loads faster than a 4K video embed.

The Problem with GIF Creation
Creating a polished product GIF used to be painful.

Record screen (OBS/Loom).
Import to Premiere/After Effects.
Add a device frame overlay.
Mask the video to fit the screen.
Add a background.
Export and pray the file size isn't 50MB.
Most developers (and even designers) don't have time for this. So they settle for static screenshots.

The Shotframe Solution: GIFs in the Browser
We added GIF support to Shotframe to solve exactly this problem. We wanted the polish of After Effects with the speed of a screenshot tool.

How it works:

Record Your Screen: Use any tool to grab a short clip of your key feature. (Keep it under 5 seconds for best results).
Drop into Shotframe: Upload your video file just like an image.

Frame It: Choose a premium device frame (iPhone, MacBook, Browser). Shotframe handles the masking automatically.

Style It: Add a custom gradient background (use BlendIt to match your brand colors!).
Export: Download a highly optimized GIF ready for your landing page.

Best Practices for Product GIFs
If you're going to use GIFs, do it right:

Keep it Short: 3-5 seconds max. Focus on ONE interaction.
Start with Action: Don't have 2 seconds of a stillness at the start. Movement should happen immediately.
High Contrast: Make sure the cursor and the button clicks are visible.
Optimization: Don't upload a 20MB GIF to your hero section. Use Shotframe’s export settings to balance quality and size.
Conclusion
Your product is dynamic. Your marketing should be too.
Stop letting your hard work sit still. Make it move.

[Try the Shotframe GIF Maker →]

How to Make Product Mockups That Don't Look Like Templates

Varun Krishnan — Thu, 01 Jan 2026 15:59:59 +0000

Stop using generic mockup backgrounds. Learn how to create custom, brand-aligned mockups (and GIFs) directly from your browser. No Figma required.

The Problem With Modern Mockups
Scroll through Dribbble, Product Hunt, or any SaaS landing page. You’ll see the same thing:

A generic MacBook or iPhone frame.
A "mesh gradient" background (usually purple or blue).
A shadow that looks slightly fake.
It’s the "Startup Starter Pack." And because everyone uses the same templates, no one stands out.

If you’ve spent weeks building a unique product, wrapping it in a generic mockup kills the vibe instantly.

Your product deserves better.

Why Context Matters (And Why Templates Fail)
A mockup's job isn't just to frame your screenshot. Its job is to extend your brand.

When you use a random gradient template, you are clashing with your product's actual design.

The Pro Move: Your background colors should be extracted from the product screenshot itself.
The Result: Perfect color harmony. The background feels like an extension of the UI, not a wrapper.

Method 1: The "Figma Workflow" (The Hard Way)
You can do this manually, of course.

Take a screenshot.
Open Figma.
Import screenshot.
Use the Eyedropper tool to pick 3-4 dominant colors.
Create a rectangle layer behind the image.
Apply a linear or radial gradient using those colors.
Add a device frame (search community files for a mockup).
Add drop shadows manually.
Export.
Time: ~15-20 minutes per image.
Result: Good, but slow.

Method 2: The Shotframe Workflow (The Fast Way)
We built Shotframe to automate the "Pro Move."

Step 1: Upload Your Screenshot
Drop your image into the browser. No login needed.

Step 2: Auto-Match the Background
Instead of picking a random color, use a tool like BlendIt to generate a gradient directly from your screenshot. Upload that gradient as your background in Shotframe.

Now your background matches your UI perfectly.

Step 3: Choose Your Device
Select from premium device frames (Safari Dark, iPhone 15, Chrome Light). It wraps your screenshot automatically with perfect shadows.

Step 4: Go Beyond Static (New Feature)
Static images are fine. Motion is better.

Shotframe now lets you export as GIF.

Show a scrolling capture.
Show a UI interaction.
Show a workflow.
This turns a "picture of an app" into a "demo of an app."

Why GIFs Convert Better Than Images
On a landing page, you have about 3 seconds to explain what your tool does.

Screenshot: The user has to read the UI to understand it.
GIF: The user sees the UI working.
It builds trust. It proves the software is real. It catches the eye.

Creating Your First Custom Mockup
Go to Shotframe.xyz.
Drop your image.
Tweak the background (or upload your custom BlendIt gradient).
Hit Export.
Stop letting generic mockups lower your product's value. Make it look as premium as the code behind it.

[Create a Free Mockup Now →]

DEV Community: Varun Krishnan

Django Auth Tables and Permissions Explained

The core tables

auth_user

auth_group

auth_permission

django_content_type

auth_user_groups

auth_group_permissions

How permissions work

What to change

What to leave alone

FAQ

Does Django create all these tables automatically?

Can I use Django without the permission system?

What's the difference between is_superuser and is_staff?

How do I see my Django auth tables?

NextAuth / Auth.js Database Schema Explained

The short version

The 4 tables

users

accounts

sessions

verification_tokens

How they connect

What to change

What to leave alone

FAQ

Does NextAuth store passwords?

How do I see what's in my NextAuth tables?

Can I add custom fields to the users table?

What happens when a user deletes their account?

Is Auth.js the same as NextAuth?

Laravel Default Database Tables Explained

The core tables

users

password_resets

failed_jobs

personal_access_tokens

Optional tables

sessions

cache

jobs

batches

What to change

What to leave alone

FAQ

Does Laravel create all these tables automatically?

Can I use Redis instead of the database tables?

What's the difference between password_resets and password_reset_tokens?

How do I visualize my Laravel schema?

What Is an ER Diagram and How to Read One

The short version

What each part means

Entities (tables)

Attributes (columns)

Relationships (lines)

Cardinality (symbols)

Reading a real example

Why ER diagrams matter

Common mistakes

Try it yourself

FAQ

What does PK mean in an ER diagram?

What does FK mean?

How do you show a many-to-many relationship?

What's the difference between an ER diagram and a schema diagram?

Do I need to draw an ER diagram by hand?

Supabase Auth Schema Explained: Users, Identities, Sessions

The short version

Why an auth schema at all

The four tables that matter

How they relate (the joins you'll actually write)

What's usually NOT your business

Practical tips

FAQ

Try It

PostgreSQL Connection String: Supabase, Neon, Railway

The short version

Anatomy of a connection string

What's the difference between `is_superuser` and `is_staff`?

What's the difference between `password_resets` and `password_reset_tokens`?

Why an `auth` schema at all