Updating README.md

kenshaw · kenshaw · commit b44385f7b62a · 2025-05-08T04:46:08.000+07:00
diff --git a/README.md b/README.md
@@ -1,7 +1,12 @@
 # dbtpl
 
-`dbtpl` is a command-line tool to generate _idiomatic_ code for different
-languages code based on a database schema or a custom query.
+`dbtpl` is a command-line tool to inspect and generate templated code based on
+a database schema or a custom database query.
+
+In addition to being able to generate standardized "model" code for a database,
+`dbtpl` is also capable of creating schema creation scripts for a database,
+generating JSON/YAML definitions, and [Graphviz](https://graphviz.org) diagrams
+for schemas.
 
 <p align="center">
   <a href="#installing" title="Installing">Installing</a> |
@@ -20,27 +25,27 @@ languages code based on a database schema or a custom query.
 
 #### Supported languages
 
-At the moment, `dbtpl` only supports [Go](https://golang.org). Support for other
-languages will come soon.
+At the moment, `dbtpl` only supports [Go](https://golang.org). Support for
+other languages is possible, but not currently planned.
 
 #### How it works
 
 In schema mode, `dbtpl` connects to your database and generates code using Go
-templates. `dbtpl` works by using database metadata and SQL introspection queries to
-discover the types and relationships contained within a schema, and applying a
-standard set of base (or customized) Go [templates](templates) against the
-discovered relationships.
+templates. `dbtpl` works by using database metadata and SQL introspection
+queries to discover the types and relationships contained within a schema, and
+applying a standard set of base (or customized) Go [templates](templates)
+against the discovered relationships.
 
 Currently, `dbtpl` can generate types for tables, enums, stored procedures, and
 custom SQL queries for PostgreSQL, MySQL, Oracle, Microsoft SQL Server, and
 SQLite3 databases.
 
-> **Note:** While the code generated by dbtpl is production quality, it is not the
-> goal, nor the intention for dbtpl to be a "silver bullet," nor to completely
-> eliminate the manual authoring of SQL / Go code.
+> **Note:** While the code generated by dbtpl is production quality, it is not
+> the goal, nor the intention for dbtpl to be a "silver bullet," nor to
+> completely eliminate the manual authoring of SQL / Go code.
 
-In query mode, `dbtpl` parses your query to generate code from Go templates.
-It finds related tables in your database to ensure type safety.
+In query mode, `dbtpl` parses your query to generate code from Go templates. It
+finds related tables in your database to ensure type safety.
 
 ## Database Feature Support
 
@@ -77,7 +82,7 @@ Scoop][] or [via Go][]:
 
 ### Installing via Homebrew (macOS and Linux)
 
-Install `dbtpl` from the [`xo/dbtpl` tap][xo-tap] in the usual way with the [`brew`
+Install `dbtpl` from the [`xo/xo` tap][xo-tap] in the usual way with the [`brew`
 command][homebrew]:
 
 ```sh
@@ -387,26 +392,15 @@ templates can be found in [templates/types.go](templates/types.go)
 Each language, has its own set of templates for `$TYPE` and are
 available in the [templates/](templates).
 
-|         Template File          | [Type](templates/types.go) | Description                                                                            |
-| :----------------------------: | :------------------------: | -------------------------------------------------------------------------------------- |
-|        hdr.dbtpl.\*.tpl        |                            | Base template. Executed with content for a template.                                   |
-|        db.dbtpl.\*.tpl         |                            | Package level template with base types and interface data. Generated once per package. |
-|    schema/enum.dbtpl.\*.tpl    |            Enum            | Template for schema enum type definitions. Generates types and related methods.        |
-| schema/foreignkey.dbtpl.\*.tpl |         ForeignKey         | Template for foreign key relationships. Generates related method.                      |
-|   schema/index.dbtpl.\*.tpl    |           Index            | Template for schema indexes. Generates related method.                                 |
-|    schema/proc.dbtpl.\*.tpl    |            Proc            | Template to generate functions to call defined stored procedures in the db.            |
-|  schema/typedef.dbtpl.\*.tpl   |            Type            | Template for schema table/views.                                                       |
-|   query/custom.dbtpl.\*.tpl    |           Query            | Template for custom query execution.                                                   |
-|   query/typedef.dbtpl.\*.tpl   |            Type            | Template for custom query's generated type.                                            |
-
-For example, Go has [`templates/gotpl/schema/foreignkey.dbtpl.go.tpl`](templates/gotpl/schema/foreignkey.dbtpl.go.tpl)
-which defines the template used by `dbtpl` for generating a function to get the
-foreign key type in Go. The templates are designed to be Database agnostic, so
-they are used for both PostgreSQL and Microsoft SQL the same, and all other
-supported database types. The template is passed a different instance of
-`templates.ForeignKey` instance (for each foreign key in a table). To get the
-`Name` field in from `ForeignKey`, the template can use ` {{ .Data.Name }}`, or
-any other field similarly.
+| Template File        | Description                                                                            |
+| -------------------- | -------------------------------------------------------------------------------------- |
+| `*.go`               | Template logic                                                                         |
+| `hdr.dbtpl.*.tpl`    | File header template. Executed with content for each generated file.                   |
+| `db.dbtpl.*.tpl`     | Package level template with base types and interface data. Generated once per package. |
+| `query.dbtpl.*.tpl`  | Template for custom query execution.                                                   |
+| `schema.dbtpl.*.tpl` | Template for custom query's generated type.                                            |
+
+_\*_ - is the template type, for example `go`, `json`, `yaml`, etc.
 
 ## Examples
 
@@ -458,9 +452,9 @@ application logic but by `dbtpl` by passing the `--exclude` or `-e` flag:
 
 ```sh
 # Ignore special fields
-$ xo schema postgres://user:pass@host/db -e users.created_at -e users.modified_at
+$ dbtpl schema postgres://user:pass@host/db -e users.created_at -e users.modified_at
 # or, To ignore these fields in all tables
-$ xo schema postgres://user:pass@host/db -e *.created_at -e *.modified_at
+$ dbtpl schema postgres://user:pass@host/db -e *.created_at -e *.modified_at
 ```
 
 ### Example: Custom Template -- adding a `GetMostRecent` lookup for all tables (Go)
@@ -480,7 +474,7 @@ First, we dump the base `dbtpl` Go template:
 ```sh
 $ mkdir -p my-tpl
 
-$ xo dump my-tpl
+$ dbtpl dump my-tpl
 ```
 
 We can now modify the templates to suit our specific schema, adding lookups,
@@ -532,7 +526,7 @@ We can then use the templates in conjunction with `dbtpl` to generate our "model
 code:
 
 ```sh
-$ xo schema postgres://user:pass@localhost/dbname --src templates/
+$ dbtpl schema postgres://user:pass@localhost/dbname --src templates/
 ```
 
 There will now be a `GetMostRecentUsers` func defined in `models/user.dbtpl.go`,
@@ -575,7 +569,7 @@ escaped using any of the `--escape-*` options, you must pass the `sql_mode=ansi`
 option to the MySQL driver:
 
 ```sh
-$ xo --escape-all 'mysql://user:pass@host/?parseTime=true&sql_mode=ansi' -o models
+$ dbtpl --escape-all 'mysql://user:pass@host/?parseTime=true&sql_mode=ansi' -o models
 ```
 
 And when opening a database connection:
@@ -588,7 +582,7 @@ Additionally, when working with date/time column types in MySQL, one should
 pass the `parseTime=true` option to the MySQL driver:
 
 ```sh
-$ xo schema 'mysql://user:pass@host/dbname?parseTime=true' -o models
+$ dbtpl schema 'mysql://user:pass@host/dbname?parseTime=true' -o models
 ```
 
 And when opening a database connection:
@@ -603,7 +597,7 @@ While not required, one should specify the `loc=auto` option when using `dbtpl`
 with a SQLite3 database:
 
 ```sh
-$ xo schema 'file:mydatabase.sqlite3?loc=auto' -o models
+$ dbtpl schema 'file:mydatabase.sqlite3?loc=auto' -o models
 ```
 
 And when opening a database connection:
@@ -667,13 +661,13 @@ table:
 
 `ALWAYS GENERATED` types will be parsed as Auto PK types for Oracle.
 
-## About xo: Design, Origin, Philosophy, and History
+## About dbtpl: Design, Origin, Philosophy, and History
 
 `dbtpl` can likely get you 99% "of the way there" on medium or large database
 schemas and 100% of the way there for small or trivial database schemas. In
-short, xo is a great launching point for developing standardized packages for
-standard database abstractions/relationships, and `dbtpl`'s most common use-case is
-indeed in a code generation pipeline, ala `stringer`.
+short, `dbtpl` is a great launching point for developing standardized packages
+for standard database abstractions/relationships, and `dbtpl`'s most common
+use-case is indeed in a code generation pipeline, ala `stringer`.
 
 ### Design
 
@@ -714,19 +708,24 @@ generate Go code. Additionally, at this time, but tangential to the story, the
 API definitions were ported from JSON to Protobuf to make use of its code
 generation abilities as well.
 
-`dbtpl` is the open source version of that code generation tool, and is the fruits
-of those development efforts. It is hoped that others will be able to use and
-expand `dbtpl` to support other databases -- SQL or otherwise -- and that `dbtpl` can
-become a common tool in any Go developer's toolbox.
+`dbtpl` is the open source version of that code generation tool, and is the
+fruits of those development efforts. It is hoped that others will be able to
+use and expand `dbtpl` to support other databases -- SQL or otherwise -- and
+that `dbtpl` can become a common tool in any Go developer's toolbox.
+
+In May of 2025, the project was renamed from `xo` to `dbtpl` to more readily
+convey the tool's purpose.
 
 ### Goals
 
-Part of `dbtpl`'s goals is to avoid writing an ORM, or an ORM-like in Go, and to
-instead generate static, type-safe, fast, and idiomatic Go code across
-languages and databases. Additionally, the `dbtpl` developers are of the opinion
-that relational databases should have proper, well-designed relationships and
-all the related definitions should reside within the database schema itself:
-ie, a "self-documenting" schema. `dbtpl` is an end to that pursuit.
+Part of `dbtpl`'s goals is to avoid writing an ORM, or an ORM-like in Go, and
+to instead generate static, type-safe, fast, and idiomatic Go code across
+languages and databases.
+
+Additionally, the `dbtpl` developers are of the opinion that relational
+databases should have proper, well-designed relationships and all the related
+definitions should reside within the database schema itself: ie, a
+"self-documenting" schema. `dbtpl` is an end to that pursuit.
 
 ## Related Projects
 
@@ -737,7 +736,7 @@ ie, a "self-documenting" schema. `dbtpl` is an end to that pursuit.
 
 ### Other Projects
 
-The following projects work with similar concepts as xo:
+The following projects work with similar concepts as `dbtpl`:
 
 #### Go Generators
 
