• Stars
    star
    1,805
  • Rank 25,735 (Top 0.6 %)
  • Language
    Haskell
  • License
    The Unlicense
  • Created about 11 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Translates a plain text description of a relational database schema to a graphical entity-relationship diagram.

Build Status Hackage

This utility takes a plain text description of entities, their attributes and the relationships between entities and produces a visual diagram modeling the description. The visualization is produced by using Dot with GraphViz. There are limited options for specifying color and font information. Also, erd can output graphs in a variety of formats, including but not limited to: pdf, svg, eps, png, jpg, plain text and dot.

Here's an example of the output produced by erd (click on it for a larger PNG version):

ER diagram for nfldb

The corresponding er file is in the examples directory.

Installation

erd requires GraphViz, and one of:

All of these are available for Windows, Mac and Linux.

MacPorts

erd is available in MacPorts as a one-shot install (GraphViz will be set up correctly for you):

port install erd

Docker

docker run -i ghcr.io/burntsushi/erd:latest < examples/nfldb.er >| out.pdf

All available tags.

Local Docker build

An example command to use erd in a docker container, once this repository is successfully cloned.

erdtag="0.2.1.0"; cd erd && docker build -t erd:$erdtag . && docker run -it erd:$erdtag "--help"

Where:

  • you shall specify your erdtag, that will help identifying the docker image to be created;
  • instead of using --help invoke erd the way you need to i.e.:
    docker run -i erd:$erdtag "--dot-entity" < examples/nfldb.er > out.pdf
    

Stack

Install the Stack build tool, and build from source:

git clone git://github.com/BurntSushi/erd
cd erd
stack install

stack install will put the binary into Stack's standard binary installation path. Unless you've overridden it, that's ~/.local/bin on Unix and OS X, %APPDATA%\local\bin on Windows.

Haskell Platform

NB OSX users: for text formatting of keys (bold and italics) you may need to reinstall graphviz with pango support:

# OSX only
brew install graphviz

The issue 1636 explains what needs to be performed in details to find out whether pango support is enabled and how to make it happen in case it wasn't.

erd is on hackage, so you can install it with cabal (which is included with the Haskell platform):

cabal new-install erd

Alternatively, you can clone this repository and build from source:

git clone git://github.com/BurntSushi/erd
cd erd
cabal new-configure
cabal new-build
# binary is now under ./dist-newstyle/build/

Usage information is available with erd --help.

Building statically linked executable

In case one wishes to have a statically linked erd as a result, this is possible to have by executing build-static_by-nix.sh: which requires the nix package manager to be installed on the building machine. NixOS itself is not a requirement.

Quick example

Before describing the ER file, let's try making an ER diagram from a small example:

$ curl 'https://raw.githubusercontent.com/BurntSushi/erd/master/examples/simple.er' > simple.er
$ cat simple.er
# Entities are declared in '[' ... ']'. All attributes after the entity header
# up until the end of the file (or the next entity declaration) correspond
# to this entity.
[Person]
*name
height
weight
`birth date`
+birth_place_id

[`Birth Place`]
*id
`birth city`
'birth state'
"birth country"

# Each relationship must be between exactly two entities, which need not
# be distinct. Each entity in the relationship has exactly one of four
# possible cardinalities:
#
# Cardinality    Syntax
# 0 or 1         ?
# exactly 1      1
# 0 or more      *
# 1 or more      +
Person *--1 `Birth Place`
$ erd -i simple.er -o simple.pdf

The PDF should now contain a graph that looks like this:

Simple erd example graph

Available command-line options

Short Long Description
-c[FILE] --config[=FILE] Configuration file.
-i FILE --input=FILE When set, input will be read from the given file. Otherwise, stdin will be used.
-o FILE --output=FILE When set, output will be written to the given file. Otherwise, stdout will be used. If given and if --fmt is omitted, then the format will be guessed from the file extension.
-f FMT --fmt=FMT Force the output format to one of: bmp, dot, eps, gif, jpg, pdf, plain, png, ps, ps2, svg, tiff.
-e EDGE --edge=EDGE Select one type of edge: compound, noedge, ortho, poly, spline.
-d --dot-entity When set, output will consist of regular dot tables instead of HTML tables. Formatting will be disabled.
-p PATTERN --edge-pattern=PATTERN Select one of the edge patterns: dashed, dotted, solid.
-n NOTATION --notation=NOTATION Select a notation style for cardinalities of relations: ie, uml.
-h --help Show this usage message.

Formatting defined in configuration file

erd may be invoked using the -c or --config argument

  • without a provided configuration file it will try to read the file ~/.erd.yaml which is the path of the configuration file to store formatting settings of any resulted graph. In case the file ~/.erd.yaml does not exists erd will print the default content of this file to stdout which you can inspect and/or redirect appropriately, e.g.: erd -c -i ./examples/nfldb.er -o ./nfldb.pdf 1 > ~/.erd.yaml .

  • with a provided configuration file erd will use that instead of ~/.erd.yaml. For instance: erd -c./myconfig.yaml -i ./examples/nfldb.er -o ./nfldb.pdf .

The configuration file in commented sections do contain the supported formatting options, so you can use one of the listed ones.

The default content of the configuration file would be only shown when ~/.erd.yaml does not exist.

The er file format

The er format allows one to describe a relational schema in terms of its entities (tables), attributes (columns) and relationships between entities (0 or 1, exactly 1, 0 or more and 1 or more).

Entities are declared inside [ and ]. For example, this declares the entity Person with no attributes:

[Person]

Attributes for an entity are then listed after its corresponding entity's declaration. Each attribute should be on its own line. The following adds the name and height attributes to the Person entity:

[Person]
name
height

Entity names and attributes may contain spaces and mostly any character, except ASCII control characters like carriage return and line feed, if quoted with backticks, simple quotes or double quotes:

[`Birth Place`]
*id
`birth city`
'birth state'
"birth country"

Any number of attributes may be declared as a primary key for its entity by prefixing the attribute with a *. Similarly, an attribute may be declared as a foreign key by prefixing the attribute with a +:

[Person]
*name
+birth_place_id

An attribute may be both a primary key and a foreign key by prefixing the name with a * and a + in any order. Note that primary keys are underlined while foreign keys are italicized.

Relationships can also be declared anywhere in an ER file. Every relationship includes exactly two entities (the two entities may be the same, for self-relationships). Each entity in a relationship must have exactly one of four cardinalities:

Cardinality    Syntax
0 or 1         ?
exactly 1      1
0 or more      *
1 or more      +

So for example, the following defines a relationship between Person and Birth Place that reads "every person has exactly one birth place":

Person *--1 `Birth Place`

And here's another example that can be read as, "every platinum album has one or more artists, but not every artist has a platinum album":

Artist +--? PlatinumAlbums

Fonts, colors, labels, ...

The er format also has limited support for customizing the appearance of your ER diagram. For example, the following will show the entity with a background color of #ececfc and a font size of 20:

[Person] {bgcolor: "#ececfc", size: "20"}
name
height
weight

Which looks like:

example of changing background color

Alternatively, you can specify the background color of every entity with a special directive at the top of the file:

entity {bgcolor: "#ececfc", size: "20"}

[Person]
name
height
weight

[`Birth Place`]
place

There are three other directives: title, header and relationship. The title directive allows one to specify a title for the graph and provide options for formatting it. The header directive allows one to customize the formatting of every entity header. And similarly for relationship. Note that global options are overwritten by local options.

Note that directives must come before anything else in an ER file.

Here's an example depicting the first schema shown at the top of this README (note that this is auto-generated by nfldb-write-erd):

title {label: "nfldb Entity-Relationship diagram (condensed)", size: "20"}

# Entities

[player] {bgcolor: "#d0e0d0"}
  *player_id {label: "varchar, not null"}
  full_name {label: "varchar, null"}
  team {label: "varchar, not null"}
  position {label: "player_pos, not null"}
  status {label: "player_status, not null"}

[team] {bgcolor: "#d0e0d0"}
  *team_id {label: "varchar, not null"}
  city {label: "varchar, not null"}
  name {label: "varchar, not null"}

[game] {bgcolor: "#ececfc"}
  *gsis_id {label: "gameid, not null"}
  start_time {label: "utctime, not null"}
  week {label: "usmallint, not null"}
  season_year {label: "usmallint, not null"}
  season_type {label: "season_phase, not null"}
  finished {label: "boolean, not null"}
  home_team {label: "varchar, not null"}
  home_score {label: "usmallint, not null"}
  away_team {label: "varchar, not null"}
  away_score {label: "usmallint, not null"}

[drive] {bgcolor: "#ececfc"}
  *+gsis_id {label: "gameid, not null"}
  *drive_id {label: "usmallint, not null"}
  start_field {label: "field_pos, null"}
  start_time {label: "game_time, not null"}
  end_field {label: "field_pos, null"}
  end_time {label: "game_time, not null"}
  pos_team {label: "varchar, not null"}
  pos_time {label: "pos_period, null"}

[play] {bgcolor: "#ececfc"}
  *+gsis_id {label: "gameid, not null"}
  *+drive_id {label: "usmallint, not null"}
  *play_id {label: "usmallint, not null"}
  time {label: "game_time, not null"}
  pos_team {label: "varchar, not null"}
  yardline {label: "field_pos, null"}
  down {label: "smallint, null"}
  yards_to_go {label: "smallint, null"}

[play_player] {bgcolor: "#ececfc"}
  *+gsis_id {label: "gameid, not null"}
  *+drive_id {label: "usmallint, not null"}
  *+play_id {label: "usmallint, not null"}
  *+player_id {label: "varchar, not null"}
  team {label: "varchar, not null"}

[meta] {bgcolor: "#fcecec"}
  version {label: "smallint, null"}
  season_type {label: "season_phase, null"}
  season_year {label: "usmallint, null"}
  week {label: "usmallint, null"}

# Relationships

player      *--1 team
game        *--1 team {label: "home"}
game        *--1 team {label: "away"}
drive       *--1 team
play        *--1 team
play_player *--1 team

game        1--* drive
game        1--* play
game        1--* play_player

drive       1--* play
drive       1--* play_player

play        1--* play_player

player      1--* play_player

All formatting options

erd only exposes a subset of formatting options made available by GraphViz. I'm not entirely opposed to expanding this list if there's a compelling reason to do so, but I'd prefer to keep it small and simple.

Note that not all options are applicable on all items. For example, a title cannot have a background color (it will just be ignored by GraphViz).

Colors can be specified in hexadecimal notation prefixed with a #, e.g., #3366ff or they may be written as their English names.

  • label A plain text string used to label the item. For entity names and attributes, a label is shown next to the name in square brackets. For relationships, a label is drawn near the center of the edge. For the special title directive, the label corresponds to the graph title.
  • color Specifies the font color. Valid everywhere.
  • bgcolor Specifies the background color. Only valid for entities and attributes.
  • size Specifies the font size. Valid everywhere.
  • font Specifies the font. Valid everywhere. See this for information about fonts in GraphViz. TL;DR: Stick with one of the following: Times-Roman, Helvetica or Courier.
  • border-color Border color. Only works for entities or attributes.
  • border Border size in pixels. Only works for entities and attributes.

Formatting options are always specified as key-value pairs in curly braces, where the opening curly brace starts on the same line as the entity/attribute/relationship/directive. The option name precedes a colon and the option value comes after the colon in double quotes (even for integer values). The value is then proceded by either a comma or an ending curly brace. Also note that trailing commas are allowed and that options may be specified over more than one line. For example, the following is a valid er file:

[Person]
  name {
    label: "string",
    color: "#3366ff", # i like bright blue
  }
  weight {
    label: "int",}

Philosophy

I don't intend for erd to have a large feature set with a lot of options for customizing the appearance of ER diagrams. erd should produce diagrams that are "good enough" from simple plain text descriptions without a lot of complexity. erd will implicitly trust GraphViz to "do the right thing" without a lot of fiddling with its options.

If you have more exotic needs, then I suggest that either erd is not the right tool, or you could use erd to output an er file as a dot file. You can then customize it further manually or using some other tool.

You can output a dot file using the --fmt option or by simply using it as a file extension:

erd -i something.er -o something.dot

Similar software

The format of the er file is inspired by the file format used by the project erwiz (which looks abandoned). The er format is a bit more lightweight, but its general structure is similar.

Similar software that translates a plain text description of a relational schema to a graphical visualization (the list may be incomplete and some of the listed projects are no longer maintained):

Text editor support

More Repositories

1

ripgrep

ripgrep recursively searches directories for a regex pattern while respecting your gitignore
Rust
48,517
star
2

xsv

A fast CSV command line toolkit written in Rust.
Rust
10,377
star
3

toml

TOML parser for Golang with reflection.
Go
4,464
star
4

quickcheck

Automated property based testing for Rust (with shrinking).
Rust
2,408
star
5

fst

Represent large sets and maps compactly with finite state transducers.
Rust
1,771
star
6

jiff

A date-time library for Rust that encourages you to jump into the pit of success.
Rust
1,736
star
7

rust-csv

A CSV parser for Rust, with Serde support.
Rust
1,710
star
8

walkdir

Rust library for walking directories recursively.
Rust
1,283
star
9

nflgame

An API to retrieve and read NFL Game Center JSON data. It can work with real-time data, which can be used for fantasy football.
Python
1,257
star
10

nfldb

A library to manage and update NFL data in a relational database.
Python
1,079
star
11

aho-corasick

A fast implementation of Aho-Corasick in Rust.
Rust
1,028
star
12

byteorder

Rust library for reading/writing numbers in big-endian and little-endian.
Rust
980
star
13

wingo

A fully-featured window manager written in Go.
Go
958
star
14

memchr

Optimized string search routines for Rust.
Rust
888
star
15

bstr

A string type for Rust that is not required to be valid UTF-8.
Rust
795
star
16

advent-of-code

Rust solutions to AoC 2018
Rust
479
star
17

xgb

The X Go Binding is a low-level API to communicate with the X server. It is modeled on XCB and supports many X extensions.
Go
472
star
18

termcolor

Cross platform terminal colors for Rust.
Rust
462
star
19

rust-snappy

Snappy compression implemented in Rust (including the Snappy frame format).
Rust
449
star
20

go-sumtype

A simple utility for running exhaustiveness checks on Go "sum types."
Go
421
star
21

chan

Multi-producer, multi-consumer concurrent channel for Rust.
Rust
392
star
22

regex-automata

A low level regular expression library that uses deterministic finite automata.
Rust
352
star
23

cargo-benchcmp

A small utility to compare Rust micro-benchmarks.
Rust
342
star
24

suffix

Fast suffix arrays for Rust (with Unicode support).
Rust
262
star
25

rure-go

Go bindings to Rust's regex engine.
Go
250
star
26

tabwriter

Elastic tabstops for Rust.
Rust
247
star
27

rebar

A biased barometer for gauging the relative speed of some regex engines on a curated set of tasks.
Python
227
star
28

imdb-rename

A command line tool to rename media files based on titles from IMDb.
Rust
226
star
29

critcmp

A command line tool for comparing benchmarks run by Criterion.
Rust
216
star
30

ty

Easy parametric polymorphism at run time using completely unidiomatic Go.
Go
198
star
31

xgbutil

A utility library to make use of the X Go Binding easier. (Implements EWMH and ICCCM specs, key binding support, etc.)
Go
191
star
32

pytyle3

An updated (and much faster) version of pytyle that uses xpybutil and is compatible with Openbox Multihead.
Python
181
star
33

dotfiles

My configuration files and personal collection of scripts.
Vim Script
154
star
34

rsc-regexp

Translations of a simple C program to Rust.
Rust
138
star
35

rust-cbor

CBOR (binary JSON) for Rust with automatic type based decoding and encoding.
Rust
129
star
36

chan-signal

Respond to OS signals with channels.
Rust
125
star
37

goim

Goim is a robust command line utility to maintain and query the Internet Movie Database (IMDb).
Go
117
star
38

same-file

Cross platform Rust library for checking whether two file paths are the same file.
Rust
101
star
39

clibs

A smattering of miscellaneous C libraries. Includes sane argument parsing, a thread-safe multi-producer/multi-consumer queue, and implementation of common data structures (hashmaps, vectors and linked lists).
C
98
star
40

ucd-generate

A command line tool to generate Unicode tables as source code.
Rust
95
star
41

nflvid

An experimental library to map play meta data to footage of that play.
Python
91
star
42

rust-stats

Basic statistical functions on streams for Rust.
Rust
87
star
43

migration

Package migration for Golang automatically handles versioning of a database schema by applying a series of migrations supplied by the client.
Go
81
star
44

winapi-util

Safe wrappers for various Windows specific APIs.
Rust
64
star
45

xpybutil

An incomplete xcb-util port plus some extras
Python
62
star
46

graphics-go

Automatically exported from code.google.com/p/graphics-go
Go
60
star
47

rust-pcre2

High level Rust bindings to PCRE2.
C
56
star
48

blog

My blog.
Rust
52
star
49

rust-sorts

Implementations of common sorting algorithms in Rust with comprehensive tests and benchmarks.
Rust
51
star
50

openbox-multihead

Openbox with patches for enhanced multihead support.
C
46
star
51

nakala

A low level embedded information retrieval system.
Rust
45
star
52

nflfan

View your fantasy teams with nfldb using a web interface.
JavaScript
43
star
53

globset

A globbing library for Rust.
Rust
42
star
54

utf8-ranges

Convert contiguous ranges of Unicode codepoints to UTF-8 byte ranges.
Rust
42
star
55

rtmpdump-ksv

rtmpdump with ksv's patch. Intended to track upstream git://git.ffmpeg.org/rtmpdump as well.
C
40
star
56

regexp

A regular expression library implemented in Rust.
Rust
37
star
57

xdg

A Go package for reading config and data files according to the XDG Base Directory specification.
Go
35
star
58

locker

A simple Golang package for conveniently using named read/write locks. Useful for synchronizing access to session based storage in web applications.
Go
34
star
59

nflcmd

A collection of command line utilities for viewing NFL statistics and rankings with nfldb.
Python
32
star
60

notes

A collection of small notes that aren't appropriate for my blog.
31
star
61

mempool

A fast thread safe memory pool for reusing allocations.
Rust
29
star
62

gribble

A command oriented language whose environment is defined through Go struct types by reflection.
Go
28
star
63

vcr

A simple wrapper tool around ffmpeg to capture video from a VCR.
Rust
27
star
64

encoding_rs_io

Streaming I/O adapters for the encoding_rs crate.
Rust
25
star
65

rust-cmail

A simple command line utility for periodically sending email containing the output of long-running commands.
Rust
21
star
66

cluster

A simple API for managing a network cluster with smart peer discovery.
Go
19
star
67

pager-multihead

A pager that supports per-monitor desktops (compatible with Openbox Multihead and Wingo)
Python
15
star
68

cablastp

Performs BLAST on compressed proteomic data.
Go
15
star
69

rust-error-handling-case-study

Code for the case study in my blog post: http://blog.burntsushi.net/rust-error-handling
Rust
15
star
70

rg-cratesio-typosquat

The source code of the 'rg' crate. It is an intentional typo-squat that redirects folks to 'ripgrep'.
Rust
15
star
71

imgv

An image viewer for Linux written in Go.
Go
14
star
72

cmd

A convenience library for executing commands in Go, including executing commands in parallel with a pool.
Go
14
star
73

fanfoot

View your fantasy football leagues and get text alerts when one of your players scores.
Python
12
star
74

cmail

cmail runs a command and sends the output to your email address at certain intervals.
Go
12
star
75

gohead

An xrandr wrapper script to manage multi-monitor configurations. With hooks.
Go
12
star
76

burntsushi-blog

A small Go application for my old blog.
CSS
12
star
77

intern

A simple package for interning strings, with a focus on efficiently representing dense pairwise data.
Go
11
star
78

crev-proofs

My crev reviews.
10
star
79

pytyle1

A lightweight X11 tool for simulating tiling in a stacking window manager.
Python
9
star
80

cif

A golang package for reading and writing data in the Crystallographic Information File (CIF) format. It mostly conforms to the CIF 1.1 specification.
Go
9
star
81

rucd

WIP
Rust
8
star
82

qcsv

An API to read and analyze CSV files by inferring types for each column of data.
Python
8
star
83

pyndow

A window manager written in Python
Python
8
star
84

csql

Package csql provides convenience functions for use with the types and functions defined in the standard library `database/sql` package.
Go
6
star
85

freetype-go

A fork of freetype-go with bounding box calculations.
Go
6
star
86

sqlsess

Simple database backed session management. Integrates with Gorilla's sessions package.
Go
6
star
87

go-wayland-simple-shm

C
5
star
88

sqlauth

A simple Golang package that provides database backed user authentication with bcrypt.
Vim Script
4
star
89

lcmweb

A Go web application for coding documents with the Linguistic Category Model.
JavaScript
4
star
90

bcbgo

Computational biology tools for the BCB group at Tufts University.
Go
4
star
91

fex

A framework for specifying and executing experiments.
Haskell
3
star
92

present

My presentations.
HTML
3
star
93

memchr-2.6-mov-regression

Rust
3
star
94

genecentric

A tool to generate between-pathway modules and perform GO enrichment on them.
Python
3
star
95

rust-docs

A silly repo for managing my Rust crate documentation.
Python
3
star
96

pcre2-mirror

A git mirror for PCRE2's SVN repository at svn://vcs.exim.org/pcre2/code
2
star
97

xpyb

A clone of xorg-xpyb.
C
2
star
98

burntsushi-homepage

A small PHP web application for my old homepage.
PHP
2
star
99

window-marker

Use vim-like marks on windows.
Python
2
star
100

sudoku

An attempt at a sudoku solver in Haskell.
Haskell
1
star