{"id":29311357,"url":"https://github.com/usvc/go-db","last_synced_at":"2026-05-08T04:04:55.471Z","repository":{"id":49977624,"uuid":"242312580","full_name":"usvc/go-db","owner":"usvc","description":"A Go package to handle database connections.","archived":false,"fork":false,"pushed_at":"2021-06-07T07:22:56.000Z","size":88,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-06-21T06:17:27.278Z","etag":null,"topics":["database","db","go","golang","golang-library","golang-package","mysql"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/usvc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-02-22T09:15:32.000Z","updated_at":"2024-06-21T06:17:27.279Z","dependencies_parsed_at":"2022-08-30T03:11:15.577Z","dependency_job_id":null,"html_url":"https://github.com/usvc/go-db","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/usvc/go-db","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usvc%2Fgo-db","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usvc%2Fgo-db/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usvc%2Fgo-db/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usvc%2Fgo-db/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/usvc","download_url":"https://codeload.github.com/usvc/go-db/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usvc%2Fgo-db/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264040961,"owners_count":23548076,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","db","go","golang","golang-library","golang-package","mysql"],"created_at":"2025-07-07T08:13:45.971Z","updated_at":"2026-05-08T04:04:55.422Z","avatar_url":"https://github.com/usvc.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DB\n\n[![latest release](https://badge.fury.io/gh/usvc%2Fgo-db.svg)](https://github.com/usvc/go-db/releases)\n[![release status](https://travis-ci.org/usvc/go-db.svg?branch=master)](https://travis-ci.org/usvc/go-db)\n[![pipeline status](https://gitlab.com/usvc/modules/go/db/badges/master/pipeline.svg)](https://gitlab.com/usvc/modules/go/db/-/commits/master)\n[![test coverage](https://api.codeclimate.com/v1/badges/90b27fd4714b0ce75111/test_coverage)](https://codeclimate.com/github/usvc/go-db/test_coverage)\n[![maintainability](https://api.codeclimate.com/v1/badges/90b27fd4714b0ce75111/maintainability)](https://codeclimate.com/github/usvc/go-db/maintainability)\n\nA Go package to handle database connections.\n\nThis package is a convenience wrapper around other libraries and currently supports databases utilising the following protocols:\n\n1. MySQL ([`github.com/go-sql-driver/mysql`](https://github.com/go-sql-driver/mysql))\n2. PostgreSQL ([`github.com/lib/pq`](https://github.com/lib/pq))\n3. MSSQL ([`github.com/denisenkom/go-mssqldb`](https://github.com/denisenkom/go-mssqldb))\n\n- **Github**: [https://github.com/usvc/go-db](https://github.com/usvc/go-db)\n- **Gitlab**: [https://gitlab.com/usvc/modules/go/db](https://gitlab.com/usvc/modules/go/db)\n\n\u003e The main database tool by `usvc` can be found at [`github.com/usvc/db`](https://github.com/usvc/db) if that's what you were looking for\n\n- [DB](#db)\n- [Usage](#usage)\n  - [Importing](#importing)\n  - [Creating a new database connection](#creating-a-new-database-connection)\n  - [Creating a new, named database connection](#creating-a-new-named-database-connection)\n  - [Importing an existing connection](#importing-an-existing-connection)\n  - [Verifying a connection works](#verifying-a-connection-works)\n  - [Retrieving a database connection](#retrieving-a-database-connection)\n  - [Closing a database connection](#closing-a-database-connection)\n  - [Closing all connections](#closing-all-connections)\n- [Configuration](#configuration)\n  - [`db.Options`](#dboptions)\n- [Development Runbook](#development-runbook)\n  - [Getting Started](#getting-started)\n  - [Continuous Integration (CI) Pipeline](#continuous-integration-ci-pipeline)\n    - [On Github](#on-github)\n      - [Releasing](#releasing)\n    - [On Gitlab](#on-gitlab)\n      - [Version Bumping](#version-bumping)\n      - [DockerHub Publishing](#dockerhub-publishing)\n- [Licensing](#licensing)\n\n- - -\n\n# Usage\n\n## Importing\n\n```go\nimport \"github.com/usvc/go-db\"\n```\n\n## Creating a new database connection\n\nThe following registers a new connection instance (but does not estabish a connection):\n\n```go\nif err := db.Init(Options{\n  Username: \"user\",\n  Password: \"password\",\n  Database: \"schema\",\n  Hostname: \"localhost\",\n  Port:     3306,\n}); err != nil {\n  log.Printf(\"an error occurred while creating the connection: %s\", err)\n}\n```\n\n## Creating a new, named database connection\n\nThe following registers a new connection instance (but does not estabish a connection) named `\"my-connection\"`:\n\n```go\nif err := db.Init(Options{\n  ConnectionName: \"my-connection\",\n  Username: \"user\",\n  Password: \"password\",\n  Database: \"schema\",\n  Hostname: \"localhost\",\n  Port:     3306,\n}); err != nil {\n  log.Printf(\"an error occurred while creating the connection: %s\", err)\n}\n```\n\n## Importing an existing connection\n\nThe following imports an existing `*sql.DB` connection and names it `\"connection-name\"`\n\n```go\nvar existingConnection *sql.DB\n// ... initialise `existingConnection` by other means ...\nif err := db.Import(existingConnection, \"connection-name\"); err != nil {\n  log.Printf(\"connection 'connection-name' seems to already exist: %s\\n\", err)\n}\n```\n\n## Verifying a connection works\n\nThe following checks if the connection instance named `\"existing-connection\"` can establish a connection to the database server:\n\n```go\nvar existingConnection *sql.DB\n// ... initialise `existingConnection` by other means ...\nif err := db.Check(\"existing-connection\"); err != nil {\n  log.Printf(\"connection 'existing-connection' could not connect: %s\\n\", err)\n}\n```\n\n## Retrieving a database connection\n\nThe following retrieves the default `*sql.DB` connection instance:\n\n```go\n// retrieve the 'default' connection\nconnection := db.Get()\nif connection == nil {\n  log.Println(\"connection 'default' does not exist\")\n}\n```\n\nThe following retrieves the `*sql.DB` connection instance named `\"my-connection\"`:\n\n```go\n// retrieve the connection with name 'my-connection'\nconnection := db.Get(\"my-connection\")\nif connection == nil {\n  log.Println(\"connection 'my-connection' does not exist\")\n}\n```\n\n## Closing a database connection\n\nThe following closes the default database connection:\n\n```go\n// ... run db.Init ...\nif err := db.Close(); err != nil {\n  log.Println(\"the default connection could not be closed\")\n}\n```\n\nThe following closes the database connection named `\"my-connection\"`:\n\n```go\n// ... run db.Init for a connection named 'my-connection'...\nif err := db.Close(\"my-connection\"); err != nil {\n  log.Println(\"the connection named 'my-connection' could not be closed\")\n}\n```\n\n## Closing all connections\n\nThe following closes all database connections:\n\n```go\n// ... run db.Init for a connection named 'my-connection'...\nif err := db.Close(\"my-connection\"); err != nil {\n  for i := 0; i \u003c len(err); i++ {\n    log.Println(err[i])\n  }\n}\n```\n\n- - -\n\n# Configuration\n\n## `db.Options`\n\n- **`ConnectionName`** `string`: Defines a local name of the connection. Defaults to `\"default\"`\n- **`Hostname`** `string`: Defines the hostname where the database service can be reached. Defaults to `\"127.0.0.1\"`\n- **`Port`** `string`: Defines the port which the database service is listening on. Defaults to `uint16(3306)`\n- **`Username`** `string`: Defines the username of the user used to login to the database server. Defaults to `\"user\"`\n- **`Password`** `string`: Defines the password of the user represented in the Username property. Defaults to `\"password\"`\n- **`Database`** `string`: Defines the name of the database schema to use. Defaults to `\"database\"`\n- **`Driver`** `string`: Defines the database driver to use. One of `db.DriverMySQL`, `db.DriverPostgreSQL`, or `db.DriverMSSQL`. Defaults to `db.DriverMySQL`\n- **`Params`** `map[string]string`: Defines connection parameters to use in the data source name (DSN).\n\n- - -\n\n# Development Runbook\n\n## Getting Started\n\n1. Clone this repository\n2. Run `make deps` to pull in external dependencies\n3. Write some awesome stuff\n4. Run `make test` to ensure unit tests are passing\n5. Push\n\n## Continuous Integration (CI) Pipeline\n\n### On Github\n\nGithub is used to deploy binaries/libraries because of it's ease of access by other developers.\n\n#### Releasing\n\nReleasing of the binaries can be done via Travis CI.\n\n1. On Github, navigate to the [tokens settings page](https://github.com/settings/tokens) (by clicking on your profile picture, selecting **Settings**, selecting **Developer settings** on the left navigation menu, then **Personal Access Tokens** again on the left navigation menu)\n2. Click on **Generate new token**, give the token an appropriate name and check the checkbox on **`public_repo`** within the **repo** header\n3. Copy the generated token\n4. Navigate to [travis-ci.org](https://travis-ci.org) and access the cooresponding repository there. Click on the **More options** button on the top right of the repository page and select **Settings**\n5. Scroll down to the section on **Environment Variables** and enter in a new **NAME** with `RELEASE_TOKEN` and the **VALUE** field cooresponding to the generated personal access token, and hit **Add**\n\n### On Gitlab\n\nGitlab is used to run tests and ensure that builds run correctly.\n\n#### Version Bumping\n\n1. Run `make .ssh`\n2. Copy the contents of the file generated at `./.ssh/id_rsa.base64` into an environment variable named **`DEPLOY_KEY`** in **Settings \u003e CI/CD \u003e Variables**\n3. Navigate to the **Deploy Keys** section of the **Settings \u003e Repository \u003e Deploy Keys** and paste in the contents of the file generated at `./.ssh/id_rsa.pub` with the **Write access allowed** checkbox enabled\n\n- **`DEPLOY_KEY`**: generate this by running `make .ssh` and copying the contents of the file generated at `./.ssh/id_rsa.base64`\n\n#### DockerHub Publishing\n\n1. Login to [https://hub.docker.com](https://hub.docker.com), or if you're using your own private one, log into yours\n2. Navigate to [your security settings at the `/settings/security` endpoint](https://hub.docker.com/settings/security)\n3. Click on **Create Access Token**, type in a name for the new token, and click on **Create**\n4. Copy the generated token that will be displayed on the screen\n5. Enter the following varialbes into the CI/CD Variables page at **Settings \u003e CI/CD \u003e Variables** in your Gitlab repository:\n\n- **`DOCKER_REGISTRY_URL`**: The hostname of the Docker registry (defaults to `docker.io` if not specified)\n- **`DOCKER_REGISTRY_USERNAME`**: The username you used to login to the Docker registry\n- **`DOCKER_REGISTRY_PASSWORD`**: The generated access token\n\n- - -\n\n# Licensing\n\nCode in this package is licensed under the [MIT license (click to see full text))](./LICENSE)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusvc%2Fgo-db","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fusvc%2Fgo-db","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusvc%2Fgo-db/lists"}