Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Extending Documentation With Added Install Options #2

Merged
merged 3 commits into from
Apr 10, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,11 @@ Currently there is no distributable, so you will need to:

Which will install the application in your GOBIN directory, which is assumed to be on your path for further instructions.

Alternatives:
- Use the `go build` command to build the binary, and then run it directly from the `cmd/` directory.
- Use the `go run` command to run the application directly from the `cmd/` directory.
- Use any of the build artefacts in the Github Actions pipeline, which are available in the `Actions` tab of the repo.

The binary makes use of several environment variables to function, including for connection credentials. This is currently the only method supported, but please see the roadmap for future plans in this space.

An example of all the possible environment variables which you can use, along with possible options, can be found in `connection_vars.sh` in the root of the repo. At this stage, only the DB connection variables are required for the program to function, all the others have workable defaults.
Expand All @@ -26,27 +31,30 @@ You will then want to run `db_to_d2` which will output the d2 of the database yo

It is recommended to use the -l "tala" option, which renders ERD diagrams the best, but this assumes that you also have `tala` installed, and that you either have a license, or aren't disturbed by the 'UNLICENSED' watermark.


## Features

### Basic ERD diagram

If you use the application with its defaults, and point at a MySQL database, you will get a basic ERD diagram of the database. This will include all tables, and all foreign keys which are recorded in the database information schema.

### Grouped Tables

As part of diagramming a large database, you may want to introduce some manual groupings of tables. This is supported by the application, and can be done by adding the groups into a .json file and pointing the application at it's path using the variable `TABLE_GROUPS_PATH`. An example of this can be found in `example_table_groups.json` in the `cmd/` directory.

This can be of special use when refactoring a database, as you can group tables together which are related, and the diagram will then illustrate the way that your logical groups remain interconnected.

You will need to enable the grouped tables behaviour by setting `TABLE_GROUPS` to 'true' in your environment variables.

### Virtual Links

Sometimes you may want to show a relationship between two tables which is not recorded in the database schema. This is supported by the application, and can be done by adding the virtual links into a .json file and pointing the application at it's path using the variable `VIRTUAL_LINKS_PATH`. An example of this can be found in `example_virtual_links.json` in the `cmd/` directory.

This feature can be of use when you have either a not very well formed database, where the logical links aren't captured in the structure (for one reason or another, many legitimate). It can also be of use when you have a database which is in the process of being refactored to support some microservices, and you still have multiple services writing to the same database.

You will need to enable the virtual links behaviour by setting `VIRTUAL_LINKS` to 'true' in your environment variables.

### Minimalist restrictions

When diagramming a large database, you may find yourself hitting the limitations of your chosen layout engine. This is especially common when you are working with a database where the tables have lots of columns. This is reasonably common if you have a database with a low level of normalisation, intentional or otherwise.

You can simplify this by restricting the application to only display the columns which are used in the foreign keys of the tables. This will reduce the number of columns displayed, and will allow you to cleanly render diagrams of larger databases.
Expand Down