How do I get my PostgreSQL connection string?

In your database provider's dashboard, click Connect to retrieve your connection string. It typically looks like: postgresql://user:password@host:5432/dbname.

Which connection method should I use?

Select the Transaction pooler option. This ensures compatibility with stateless applications and allows dbdiagramr to detect connections properly.

What if I forgot my database password?

Regenerate your password in the Shared pooler section of your database provider's dashboard and copy-paste the new credentials into your connection string.

What is how to document your database schema for a team?

A practical guide to documenting your database schema so your team actually reads it -- naming conventions, inline comments, and the one-page cheat sheet.

How to Document Your Database Schema for a Team

The short version

Document your schema in three layers: (1) name things well so they're self-documenting, (2) add inline column comments for the non-obvious stuff, (3) generate a one-page visual diagram that shows the relationships. Skip the 40-page Confluence page -- nobody reads it.

Layer 1: Name things well

Tables: plural nouns, snake_case -- order_items, not OrderItems.
Foreign keys: {table}_id -- user_id, not userId.
Booleans: prefix with is_ or has_ -- is_active, has_paid.
Timestamps: created_at and updated_at.

Layer 2: Inline comments

PostgreSQL supports column-level comments. Use them for anything that isn't obvious from the name:

COMMENT ON COLUMN orders.status IS
  'pending | confirmed | shipped | delivered | cancelled. Never delete orders -- set status to cancelled instead.';

What to comment: enum values, format requirements, business rules, deletion policies. What NOT to comment: id, created_at, obvious foreign keys.

Layer 3: Visual diagram

A one-page ER diagram replaces 40 pages of documentation. Use dbdiagramr -- paste your connection string, get a visual schema in seconds. Show table names, primary keys, foreign key relationships, and non-obvious column types.

The one-page cheat sheet

Create a SCHEMA.md in your repo with table names, key columns, relationships, and a link to your visual diagram. Update it in the same PR that changes the schema.

FAQ

Should I document every table?
No. Document the tables new engineers will touch, the ones with complex business logic, and the ones with non-obvious schemas.

How often should I update the docs?
When you add or change a column. Put the update in your PR template as a checklist item.

What's the best tool for auto-generating schema docs?
dbdiagramr for visual diagrams. dbt's docs generate if you're on dbt.