## 1. Project Overview & Quickstart (xo/D018-the-whole-package-is-idiomatic-go) # D018-the-whole-package-is-idiomatic-go Open-source repository xo/D018-the-whole-package-is-idiomatic-go ### Repository Details - **Repository:** [xo/D018-the-whole-package-is-idiomatic-go](https://github.com/xo/D018-the-whole-package-is-idiomatic-go) - **Primary Language:** Code *Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.* ## 2. Official Technical Reference & Guides (xo/docs) ## File: content/blog/say-hello-to-doks/index.md --- title: "Say hello to Doks 👋" lead: "Introducing Doks, a Hugo theme helping you build modern documentation websites that are secure, fast, and SEO-ready — by default." date: 2020-11-04T09:19:42+01:00 lastmod: 2020-11-04T09:19:42+01:00 draft: false weight: 50 images: ["say-hello-to-doks.png"] contributors: ["Henk Verlinde"] --- --- ## File: content/blog/_index.md --- title: "Blog" date: 2020-10-06T08:49:55+00:00 lastmod: 2020-10-06T08:49:55+00:00 draft: false images: [] --- --- ## File: content/contact/index.md --- title: "Contact" date: 2020-08-27T19:25:12+02:00 lastmod: 2020-08-27T19:25:12+02:00 draft: false images: [] --- {{< email user="hello" domain="getdoks.org" >}} --- ## File: content/contributors/hhhapz/_index.md --- title: "Hamza Ali" date: 2021-06-25 draft: false images: [] --- Contributor [@hhhapz](https://github.com/hhhapz) --- ## File: content/contributors/kenshaw/_index.md --- title: "Kenneth Shaw" date: 2021-06-25 draft: false images: [] --- Creator of `xo`. [@kenshaw](https://github.com/kenshaw) --- ## File: content/contributors/_index.md --- title: "Contributors" date: 2020-10-06T08:50:29+00:00 lastmod: 2020-10-06T08:50:29+00:00 draft: false images: [] --- The Doks contributors. --- ## File: content/docs/getting_started/_index.md --- title : "Getting Started" lead: "" date: 2020-10-06T08:48:45+00:00 lastmod: 2020-10-06T08:48:45+00:00 draft: false images: [] --- --- ## File: content/docs/getting_started/connection_string.md --- title: "Connection Strings" lead: "Connecting to your database with xo" date: 2021-06-25T11:23:25Z lastmod: 2021-06-25T11:23:25Z draft: false images: [] menu: docs: parent: "getting started" weight: 40 toc: true --- ## Connection Strings Creating a connection string to your database can become confusing, especially with all of the different formats that databases use. To help reduce complexity, `xo` uses [dburl →](https://github.com/xo/dburl). `dburl` provides a standard, URL style mechanism for parsing and opening SQL database connection strings. ### How it works Database connection URLs supported by `xo` are all in the same form: ```url protocol+transport://user:pass@host/dbname?opt1=a&opt2=b protocol:/path/to/file ``` Where: | Component | Description | |:------------------:|:-----------------------------------------------------| | protocol | driver name or alias (see below) | | transport | "tcp", "udp", "unix" or driver name (odbc/oleodbc) | | user | username | | pass | password | | host | host | | dbname1 | database, instance, or service name/ID to connect to | | ?opt1=[value] | additional database driver options | {{< alert icon="💡" text=`1 For Microsoft SQL Server, `/dbname`, can be `/instance/dbname`, where `/instance` is optional. For Oracle Database, `/dbname` is of the form `/service/dbname` where `/service` is the service name or SID, and `/dbname` is optional.` />}} To connect to your database with `xo`, here are the allowed protocols and driver names: | Database (scheme/driver) | Protocol Aliases | |----------------------------------|----------------------| | PostgreSQL (postgres) | pg, postgresql, pgsql| | MySQL (mysql) | my, maria | | SQLite3 (sqlite3) | sq, sqlite, file | | Oracle Database (oracle) | or, ora, oracle | | Microsoft SQL Server (sqlserver) | ms, mssql | ### Examples {{% code name="Connection Urls" lang="url" postgres=`postgres://user:pass@localhost/dbname pg://user:pass@localhost/dbname?sslmode=disable` mysql=`mysql://user:pass@localhost/dbname mysql:/var/run/mysqld/mysqld.sock` sqlite=`sqlite:/path/to/file.db file:myfile.sqlite3?loc=auto` sqlserver=`mssql://user:pass@remote-host.com/instance/dbname ms://user:pass@remote-host.com:port/instance/dbname?keepAlive=10` oracle=`oracle://user:pass@somehost.com/sid or://user:pass@localhost/db1` %}} To learn more about `dburl`, or to use it in your own project, check out its [GitHub →](https://github.com/xo/dburl). --- ## File: content/docs/getting_started/first_schema.md --- title: "Generating your first Schema" date: 2021-06-25T11:23:33Z lastmod: 2021-06-25T11:23:33Z draft: false images: [] menu: docs: parent: "getting started" weight: 50 toc: true --- first schema --- ## File: content/docs/getting_started/installation.md --- title: "Installation" lead: "Installing xo on your system" date: 2021-06-25T11:27:23Z lastmod: 2021-06-25T11:27:23Z draft: false images: [] menu: docs: parent: "getting started" weight: 20 toc: true --- ## Installation `xo` is written in Go and uses Go templates with the 1.16 `embed` package. To compile `xo`, you will need to use at least Go 1.16. ### 1. Install Go For Linux users, you can use your favorite package installer to install Go: ```shell $ aptitude install go $ pacman -S go $ yum install golang ``` Mac users can use Homebrew to install Go, or download it from the [Go website →](https://golang.org/dl) ```shell $ brew install go ``` For Windows, Go can be installed through [Chocolatey →](https://chocolatey.org/install) or from the [Go website →](https://golang.org/dl) ### 2. Install `xo` Install `xo` in the usual Go way: ```shell $ go get -u github.com/xo/xo ``` ## Notes: Go users ### 2.1 Install goimports `xo` uses goimports to format generated Go code. To install it: ```shell $ go get -u golang.org/x/tools/cmd/goimports ``` Go code generated by `xo` is compatible with Go versions as old as Go 1.3. {{< alert icon="💡" text=`To se `xo` in older versions of Go, set 'go-context-mode=disable'.` />}} --- ## File: content/docs/getting_started/overview.md --- title: "Overview" date: 2020-10-06T08:48:57+00:00 lastmod: 2020-10-06T08:48:57+00:00 draft: false images: [] menu: docs: parent: "getting started" weight: 10 toc: true --- ## Overview `xo` is a command-line tool to generate _idiomatic_ code for different languages code based on a database schema or a custom query. ### Supported languages At the moment, `xo` supports generating code just for [Go](https://golang.org). `xo` can also generate a JSON Schema file from your DB, and [GraphViz](http://graphviz.org/) diagrams. ### Features - Type-safe and idiomatic Go code. - Logging all DB operations - Working with transactions - Generated types/objects for tables and views - Type-safe CRUD operations - Type-safe functions/methods for primary keys, indexes, and foreign keys - Fully customisable templates - Automatic primary keys support - Type-safe code generation from your custom queries **Go-specific:** - \*sql.DB integration - Supply custom Go types for SQL data types - Generate code with and without context ### Databases `xo` can generate types for tables, enums, stored procedures, and custom SQL queries for the following languages: - [PostgreSQL →]({{< relref "databases#postgresql" >}}) - [MySQL →]({{< relref "databases#mysql" >}}) - [Oracle →]({{< relref "databases#oracle" >}}) - [Microsoft SQL Server →]({{< relref "databases#miscroft-sql-server" >}}) - [SQLite3 →]({{< relref "databases#sqlite3" >}}) For more info about supported databases, visit the [databases page →]({{< relref "databases" >}}) _xo/xo — hugs and kisses from your database_. --- ## File: content/docs/reference/databases.md --- title: "Databases" date: 2021-06-25T11:23:19Z lastmod: 2021-06-25T11:23:19Z draft: false images: [] menu: docs: parent: "reference" weight: 10 toc: true --- ## Databases At the moment, `xo` supports 5 major relational databases: | | PostgreSQL | MySQL | SQLite | SQL Server | Oracle | | ------------------------ | :--------: | :---: | :----: | :--------: | :----: | | | [Reference]({{% relref "postgres" %}}) | [Reference]({{% relref "mysql" %}}) | [Reference]({{% relref "sqlite3" %}}) | [Reference]({{% relref "sqlserver" %}}) | [Reference]({{% relref "oracle" %}}) | | Custom Queries | ✅ | ✅ | ✅ | ✅ | ✅ | | Tables | ✅ | ✅ | ✅ | ✅ | ✅ | | Views | ✅ | ✅ | ✅ | ✅ | ✅ | | Primary Keys | ✅ | ✅ | ✅ | ✅ | ✅ | | Sequences | ✅ | ✅ | ✅ | ✅ | ✅ | | Foreign Key | ✅ | ✅ | ✅ | ✅ | ✅ | | Indexes | ✅ | ✅ | ✅ | ✅ | ✅ | | Stored Procs1 | ✅ | ✅ | ✅ | ✅ | ✅ | | Stored Funcs1 | ✅ | ✅ | ✅ | ✅ | ✅ | | ENUM types | ✅ | ✅ | | | | | Custom types | ✅ | | | | | {{< alert icon="💡" text=`1 Currently, functions and procedures only support non-cursor IN and OUT parameters. For MySQL, procedures that have out parameters are not supported` />}} ## Drivers `xo` is designed to work with most drivers, and to be compatible with `database/sql` when targeting Go. Here are the drivers that `xo` uses to generate output, and the libraries that are tested and confirmed to work with `xo`. | Database (driver) | Package | |------------------------------|------------------------------------------------------------------------------| | PostgreSQL (postgres) | [github.com/lib/pq](https://github.com/lib/pq) | | SQLite3 (sqlite3) | [github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3) | | MySQL (mysql) | [github.com/go-sql-driver/mysql](https://github.com/go-sql-driver/mysql) | | Microsoft SQL Server (mssql) | [github.com/denisenkom/go-mssqldb](https://github.com/denisenkom/go-mssqldb) | | Oracle (go-ora) | [github.com/sijms/go-ora](https://github.com/sijms/go-ora) | | Oracle (godror) (tested) | [github.com/godror/godror](https://github.com/godror/godror) |