{"id":13395240,"url":"https://github.com/infostreams/db","last_synced_at":"2025-05-16T14:07:29.391Z","repository":{"id":62422823,"uuid":"180148260","full_name":"infostreams/db","owner":"infostreams","description":"Version control for databases: save, restore, and archive snapshots of your database from the command line","archived":false,"fork":false,"pushed_at":"2021-09-24T09:27:16.000Z","size":106,"stargazers_count":1302,"open_issues_count":5,"forks_count":28,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-05-15T11:41:26.621Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","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/infostreams.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":"2019-04-08T12:51:30.000Z","updated_at":"2025-04-30T13:04:03.000Z","dependencies_parsed_at":"2022-11-01T17:32:56.302Z","dependency_job_id":null,"html_url":"https://github.com/infostreams/db","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infostreams%2Fdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infostreams%2Fdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infostreams%2Fdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infostreams%2Fdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/infostreams","download_url":"https://codeload.github.com/infostreams/db/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254544146,"owners_count":22088807,"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":[],"created_at":"2024-07-30T17:01:47.427Z","updated_at":"2025-05-16T14:07:29.373Z","avatar_url":"https://github.com/infostreams.png","language":"Shell","readme":"# Introduction \n\nWith DB you can very easily save, restore, and archive snapshots of your database from the command line. It \nsupports connecting to different database servers (for example a local development server and a staging or \nproduction server) and allows you to load a database dump from one environment into another environment. \n\n\u003e For now, this is for MySQL only, but it could be extended to be used with other database systems as well.\n\n## Table of Contents\n- [Introduction](#introduction)\n- [Examples](#examples)\n- [Installation](#installation)\n  * [Additional configuration / different port or socket](#additional-configuration--different-port-or-socket)\n- [Available commands](#available-commands)\n  * [db init](#db-init)\n  * [db save](#db-save)\n  * [db load](#db-load)\n  * [db remove](#db-remove)\n  * [db server](#db-server)\n    + [db server add](#db-server-add)\n    + [db server remove](#db-server-remove)\n    + [db server show](#db-server-show)\n    + [db server list](#db-server-list)\n  * [db export](#db-export)\n  * [db import](#db-import)\n  * [db nuke](#db-nuke)\n  * [db log](#db-log)\n  * [db show](#db-show)\n  * [db structure](#db-structure)\n  * [db change](#db-change)\n    + [db change charset](#db-change-charset)\n    + [db change wordpress](#db-change-wordpress)\n  * [db test](#db-test)\n\n## Examples \n\n```shell \n$ db save localhost \"snapshot before running migrations\" \n\n\u003e [localhost] \n\u003e Successfully made snapshot of database - hash f4f0c1d3fac74166c12a3708cdaa5d804dcd4b970c6e2789ccb23303 \n``` \n\nThis will save a copy of your database to the repository. \n\n\u003e By default, this repository lives in the ```.db``` folder in your project root. In this repository are gzipped database \n\u003e dumps. Whether or not you want to commit the contents of that folder to ```git``` or another VCS is up to you. If you\n\u003e do, make sure to exclude your database credentials by adding something like ```.db/*/config/credentials.cnf``` \n\u003e (untested!) to your ```.gitignore```.\n\nImagine the following scenario: after creating the local snapshot, you run a database migration. However, the migration\nbreaks your database and deletes some stuff that you didn't want to delete. Usually, if you run a migration, there is \nalso a way to undo that migration - but alas, that won't return your deleted data. No problem. To restore your database \nto the state it was in before you started the migration, simply run: \n\n```shell \n$ db load localhost f4f0c1d3fac74166c12a3708cdaa5d804dcd4b970c6e2789ccb23303 \n\n\u003e [localhost] Loaded snapshot f4f0c1d3fac74166c12a3708cdaa5d804dcd4b970c6e2789ccb23303 \n``` \n\nThis will load the snapshot you made before you ran the migration. It's like the migration never happened. \n\nThere are many other things ```db``` can do, for example pulling down a database from the staging environment to \nyour localhost: \n\n```shell \n$ db save staging \"Snapshot intended for development\" \n\n\u003e [staging] \n\u003e Successfully made snapshot of database - hash 1577b2173c672eb824d5b43e989f15448f2bfca43b5b1144e6977479 \n\n$ db load localhost 1577b2173c672eb824d5b43e989f15448f2bfca43b5b1144e6977479 \n\n\u003e [localhost] Loaded snapshot 1577b2173c672eb824d5b43e989f15448f2bfca43b5b1144e6977479 \n\n``` \n\nHere you first make a snapshot of the database on the **staging** server, which you then load into your **localhost** \ndatabase. This works most reliably if your staging and your development server are on the same database version.\n\nSee the full [list of available commands](#available-commands) to get a complete overview of ```db```'s capabilities. \n\n## Installation \n\n### MacOS\nOn MacOS, you can install ```db``` with the [HomeBrew package manager](https://brew.sh/):\n\n```shell\n$ brew install db-vcs\n```\n\n### Linux / others\nOn other operating systems, you can install ```db``` by cloning the repository:\n\n```shell\n$ git clone https://www.github.com/infostreams/db\n```\n\nand then creating a symlink to the main ```db``` script from a directory that is in your path, e.g.:\n\n```shell\n$ cd db/ # change to the directory you cloned the github repository in\n$ ln -s db /usr/local/bin/ # create the symlink\n```\n\nYou can see if it works by running\n\n```shell\n$ db\n```\n\nIf all is well you should see the following friendly error message:\n\n```shell\nfatal: Not a db repository (or any of the parent directories). Please run 'db init'.\n```\n\nSo, to really get started, go to a directory where you have a project that uses a database, and type \n[```db init```](#db-init). This will start the process of setting up your database connection details, after which \nthe following commands will be available to you.\n\n### Additional configuration / different port or socket\n\nYou can provide additional configuration for the MySQL connection by providing them in \n[the options file](https://dev.mysql.com/doc/refman/5.7/en/option-files.html) that can be found at \n```.db/\u003calias\u003e/config/credentials.cnf```. Here you can provide a different port number or you can specify a socket\nto connect through, for example\n\n```ini\n[client]\nuser = root\npassword =\nhost = 127.0.0.1\nport = 3307\n```\n\nto connect to a MySQL database on a port 3307 instead of the standard 3306, or\n\n```ini\n[client]\nuser = root\npassword =\nsocket = /var/run/mysqld/mysql.sock\n```\n\nto connect to MySQL through a socket file located at ```/var/run/mysqld/mysql.sock```.\n\n## Available commands \n\n```db``` has commands to import external SQL files into your database ([```db import```](#db-import)), to export a \ndump from the repository to a file ([```db export```](#db-export)), to make minor changes to your database (such as \nchanging the encoding, with [```db change```](#db-change)), to clean out your database entirely ([```db nuke```](#db-nuke)), \nor to show the table structure of a particular dump ([```db structure```](#db-structure)). Very high on the wish \nlist is a way to display a \"diff\" between two dumps, but that's not so easy and hasn't been implemented yet. \n\n### Full list \n\nThe full list of available commands is as follows \n\n* [init](#db-init) \n* [save](#db-save) \n* [load](#db-load) \n* [remove](#db-remove) \n* [server](#db-server) \n* [export](#db-export) \n* [import](#db-import) \n* [log](#db-log) \n* [nuke](#db-nuke) \n* [show](#db-show) \n* [structure](#db-structure) \n* [change](#db-change) \n* [test](#db-test) \n\n### db init \n\nCreates a new DB repository in the current directory. Starts an interactive session that allows you to specify the \nconnection details. \n\n#### Syntax \n```shell \n$ db init \u003cdatabase-type\u003e \n``` \n\nIf no database-type is provided, you will be asked to specify it in the interactive session. At the moment, only mysql \nis supported. The extension points for other database systems are already in place and could (theoretically) be added\nrelatively easily. \n\nBelow you see an example of the questions you might be asked. \n\n```shell \n$ db init \n\n\n\u003e Please provide the database type for this repository \n\u003e Supported types: mysql \n\u003e \n\u003e Database type [mysql]: \n\u003e \n\u003e Please provide the connection details for the database \n\u003e Server alias []: \n\u003e Connection type, e.g. direct, or ssh []: \n\u003e SSH login, e.g. user@hostname.com []: \n\u003e Please provide the database host. For connection types SSH and direct, this is probably 127.0.0.1. \n\u003e Database host [127.0.0.1]: \n\u003e Username [root]: \n\u003e Password []: \n\u003e Database []: \n\u003e \n\u003e Successfully connected to database. Writing config. \n``` \n\nThe password for your connection will be stored in plain text, in a file that only the current user has read-access to \n(file mode 0600). Make sure to not commit this file (```.db/\u003cserver alias\u003e/config/credentials.cnf```) to source control!\n\nIf you want to add a remote server, you need to have ssh access to it. It is best if you have setup passwordless access,\notherwise it will ask you for your password every time you interact with the remote server. \n\n### db save \n\nSaves a snapshot of the database to the repository. \n\n#### Syntax \n\n```shell \n$ db save [server alias] [commit message] \n``` \n\nIf you omit the **server alias** it will default to using the oldest server alias, in my case almost always **localhost**. \n\nExample \n\n```shell \n$ db save localhost \"Hello database\" \n\n\u003e [localhost] \n\u003e Successfully made snapshot of database - hash e82a736789b421e7efd0ee2071bff33945a5fab6be08be6821a3f576 \n``` \n\nIf you try to make a snapshot of a database that didn't change, it will not save a new snapshot. \n\n\n### db load \n\nLoads a snapshot from the repository into the database. \n\nCAVEAT: Any tables that are **not** in the snapshot you are restoring are left untouched. *It only replaces the tables \nthat are in the snapshot.* If you want to completely empty your database first, have a look at [db nuke](#db-nuke). \n\n#### Syntax \n\n```shell \n$ db load [server alias] [snapshot] [--match MATCH] \u003ctable_1\u003e \u003ctable_2\u003e \u003c...\u003e \u003ctable_n\u003e\n```\n \nIf you omit the **server alias** it will default to using the oldest server alias, in my case almost always **localhost**.\n\nFor ```[snapshot]``` you can either provide the full hash (e.g. ```e82a736789b421e7efd0ee2071bff33945a5fab6be08be6821a3f576```)\nor you can provide just enough characters to uniquely identify a given dump (e.g. ```e82a736789b4```) \n\nYou can choose to only load one or more specific tables from this snapshot. For example, the following command will only \nrestore the ```wp_users``` table to localhost:\n\n```shell\n$ db load localhost e82a736789b421e7efd0ee2071bff33945a5fab6be08be6821a3f576 wp_users\n```\n\nYou can provide more than one table to restore. If you don't provide any tables, it will load all the tables that\nare defined in the snapshot.\n\nYou can also provide a regular expression to match the table name to restore. For example, to only restore tables\nwhose name matches the regular expression ```wp_13_.*```, you can run the following command:\n\n```shell\n$ db load localhost e82a736789b421e7efd0ee2071bff33945a5fab6be08be6821a3f576 --match \"wp_13_.*\"\n```\n\n### db remove\n\nRemoves a snapshot from the repository\n\n#### Syntax\n\n```shell\n$ db remove [server alias] [snapshot] \n```\n\n#### Alternative syntax\n\nInstead of typing out ```db remove```, you can also use an abbreviated version, ```db rm```:\n\n```shell\n$ db rm [server alias] [snapshot] \n```\n\n### db server\n\n\n#### db server add\n\nAdds a new database server\n\n##### Syntax\n\n\n```shell \n$ db server add \n```\n\nExample \n\n```shell \n$ db server add \n\n\n\u003e Please provide the connection details for the database \n\u003e \n\u003e Server alias []: production \n\u003e Connection type, e.g. direct, or ssh []: ssh \n\u003e SSH login, e.g. user@hostname.com []: account@server.com\n\u003e Please provide the database host. For connection types SSH and direct, this is probably 127.0.0.1. \n\u003e Database host [127.0.0.1]: 127.0.0.1 \n\u003e Username [root]: user \n\u003e Password []: password\n\u003e Database []: database\n\u003e \n\u003e Successfully connected to database. Writing config. \n``` \n\nThis would have added a new server with the alias **production**, which you can then use to save and load snapshots. \n\nIf you want to add a remote server, you need to have ssh access to it. It is best if you have setup passwordless access,\notherwise it will ask you for your password every time you interact with the remote server. \n\n\n#### db server remove\n\nRemoves a database server alias and all the snapshots. Does not do affect the actual database server itself.\n\n##### Syntax\n\n```\n$ db server remove [server alias]\n```\n\n#### db server show\n\nShows the connection details for a database server alias.\n\n##### Syntax\n\n```\n$ db server show [server alias]\n```\n\n#### db server list\n\nShows a list of which servers are available\n\n##### Syntax\n\n```shell \n$ db server list \n\n\u003e localhost \n\u003e staging \n``` \n\n### db export\n\nCopies a database snapshot from the repository to a local file\n\n#### Syntax\n\n```shell\n$ db export [server alias] [snapshot] \u003cpath to output .sql file\u003e\n```\n\nExample\n\n```shell\n$ db export project a604f1d9063e9100fef408119287d8b604542434ea79214713088bc3  ~/Desktop/latest-dump.sql\n```\n\n### db import\n\nTries to load an external database dump into the database. Will not empty out the database first (!) - if you want that,\nmake sure to run [```db nuke```](#db-nuke) first.\n\nYou can import gzip compressed database dumps, as long as the file extension is **.gz**.\n\n#### Syntax\n\n```shell\n$ db import [server alias] [\u003cpath to .sql or .sql.gz file\u003e | \u003chash\u003e]\n```\n\nExample\n\n```shell\n$ db import localhost ~/Desktop/some-dump-from-a-colleague-or-customer.sql\n```\n\n### db nuke \n\n*Deletes all tables in your database* (!!)\n\n#### Syntax \n\n```shell \n$ db nuke [server alias]\n```\n \nThis will delete all the tables in your database. If you omit the **server alias** it will default to using the oldest \nserver alias, in my case almost always **localhost**.\n\nUse with care (obviously).\n\n### db log\n\nShow a list of snapshots in the repository. By default, it will list all snapshots for all servers.\n\n\n#### Syntax\n\n```shell\n$ db log [server alias | all]\n```\n\nExample\n\n```shell\n$ db log\n```\n\nThis will list all snapshots in the repository.\n\n```shell\n$ db log localhost\n```\n\nThis will only list the snapshots for the _localhost_ database.\n\n### db show\n\nDisplays the contents of a snapshot. Basically echos the contents of the database dump to STDOUT.\n\n#### Syntax\n\n```shell\n$ db show [snapshot]\n```\n\nYou don't need to provide the server alias here, since snapshots have unique names.\n\nExample\n\n```shell\n$ db show e9d5240e077b0f180d594d59aac468b4fc844d984eaf6e76363e1c14 | less\n```\n\nDisplays the contents of the given database dump, and pipes it through ```less``` so you can inspect it.\n\n\n### db structure\n\nDisplays the table structure of a given snapshot: shows all the **CREATE TABLE** statements in the snapshot.\nUseful for debugging or inspecting the database.\n\n#### Syntax\n\n```shell\n$ db structure [snapshot]\n```\n\nYou don't need to provide the server alias here, since snapshots have unique names.\n\nExample\n\n```shell\n$ db structure c6d7451de16a8ddd0ec240a6d8f7cc376544583433f74bcf9960c6ab | less\n```\n\nDisplays the table definitions in the provided snapshot, and pipes it through ```less``` for inspection.\n\n### db change\n\nAllows you to make changes to a database. Does not operate on a snapshot but on the actual database itself.\n\n#### db change charset\n\nChanges the character set and collation of the database and its tables.\n\n##### Syntax\n\n```shell\n$ db change charset [server alias] [new characterset] [new collation]\n```\n\nExample\n\n```shell\n$ db change charset localhost utf8mb4 utf8mb4_unicode_ci\n```\n\n#### db change wordpress\n\nRuns a naive search and replace on the database to make changes to allow WordPress to run on a different domain name.\nOnly use this if you cannot use [WP-CLI](https://wp-cli.org/) for some reason.\n\n##### Syntax\n\n```shell\n$ db change wordpress [server alias] [new url]\n```\n\nExample\n\n```shell\n$ db change wordpress localhost \"http://www.my-new-domain.com/\"\n```\n\n### db test\n\nTries to connect to a given database server. Known to sometimes give false positives.\n\n### Syntax\n\n```shell\n$ db test [server alias]\n```\n\nExample\n\n```shell\n$ db test staging \n```\n\nTries to connect to the **staging** server.\n","funding_links":[],"categories":["Shell","Version Control for Databases (AKA Schema Migration)"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfostreams%2Fdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finfostreams%2Fdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfostreams%2Fdb/lists"}