{"id":17925015,"url":"https://github.com/mwpastore/ember-cli-deploy-sql","last_synced_at":"2025-03-24T03:30:59.366Z","repository":{"id":57223226,"uuid":"88136770","full_name":"mwpastore/ember-cli-deploy-sql","owner":"mwpastore","description":"Deploy your Ember.js index to a database table","archived":false,"fork":false,"pushed_at":"2018-06-12T21:16:17.000Z","size":148,"stargazers_count":8,"open_issues_count":3,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-03-23T20:03:38.605Z","etag":null,"topics":["ember-addon","ember-cli-deploy-plugin","knexjs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/mwpastore.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-04-13T07:20:50.000Z","updated_at":"2019-05-02T17:07:43.000Z","dependencies_parsed_at":"2022-08-24T16:20:54.679Z","dependency_job_id":null,"html_url":"https://github.com/mwpastore/ember-cli-deploy-sql","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mwpastore%2Fember-cli-deploy-sql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mwpastore%2Fember-cli-deploy-sql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mwpastore%2Fember-cli-deploy-sql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mwpastore%2Fember-cli-deploy-sql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mwpastore","download_url":"https://codeload.github.com/mwpastore/ember-cli-deploy-sql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245204462,"owners_count":20577354,"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":["ember-addon","ember-cli-deploy-plugin","knexjs"],"created_at":"2024-10-28T20:51:58.955Z","updated_at":"2025-03-24T03:30:58.949Z","avatar_url":"https://github.com/mwpastore.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ember-cli-deploy-sql\n\n[![npm version](https://badge.fury.io/js/ember-cli-deploy-sql.svg)](https://badge.fury.io/js/ember-cli-deploy-sql)\n[![ember-cli-deploy](https://ember-cli-deploy.github.io/ember-cli-deploy-version-badges/plugins/ember-cli-deploy-sql.svg)](http://ember-cli-deploy.github.io/ember-cli-deploy-version-badges/)\n[![build status](https://travis-ci.org/mwpastore/ember-cli-deploy-sql.svg?branch=master)](https://travis-ci.org/mwpastore/ember-cli-deploy-sql)\n[![code coverage](https://coveralls.io/repos/mwpastore/ember-cli-deploy-sql/badge.svg?branch=master)](https://coveralls.io/r/mwpastore/ember-cli-deploy-sql?branch=master)\n\nThis plugin, lovingly cribbed from [ember-cli-deploy-redis][8], uploads the\ncontents of a file, presumably index.html, to a specified database table.\nPostgreSQL, MySQL/MariaDB, Oracle, and other relational database management\nsystems (RDBMS) are supported (courtesy of [Knex.js][3]).\n\nMore often than not this plugin will be used in conjunction with the [lightning\nmethod of deployment][1] where the Ember.js application assets will be served\nfrom S3 and the index.html file will be served alongside your API from a\nkey-value store of some kind; in this case, a database table. However, it can\nbe used to upload the contents of any file.\n\nThis plugin is a candidate to replace both [ember-cli-deploy-mysql][9] and\n[ember-cli-deploy-postgres][10].\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n\n- [What is an Ember CLI Deploy plugin?](#what-is-an-ember-cli-deploy-plugin)\n- [Why would I use this instead of ember-cli-deploy-redis?](#why-would-i-use-this-instead-of-ember-cli-deploy-redis)\n- [Quick Start](#quick-start)\n- [Pipeline Hooks Implemented](#pipeline-hooks-implemented)\n- [Configuration Options](#configuration-options)\n- [Configuration Prerequisites](#configuration-prerequisites)\n- [Activation](#activation)\n- [What if my MySQL server isn't publicly accessible?](#what-if-my-mysql-server-isnt-publicly-accessible)\n- [Migrating from ember-cli-deploy-mysql](#migrating-from-ember-cli-deploy-mysql)\n- [Migrating from ember-cli-deploy-postgres](#migrating-from-ember-cli-deploy-postgres)\n- [Tests](#tests)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## What is an Ember CLI Deploy plugin?\n\nA plugin is an addon that can be executed as a part of the Ember CLI Deploy\npipeline. A plugin will implement one or more of the Ember CLI Deploy's\npipeline hooks.\n\nFor more information on what plugins are and how they work, please refer to the\n[Plugin Documentation][2].\n\n## Why would I use this instead of ember-cli-deploy-redis?\n\nThat's a great question. Redis is a more natural fit for this kind of problem\nand you can do neat things like serve directly from NGINX. Databases, on the\nother hand, aren't traditionally set up well for key-value storage and\nretrieval, and it ends up being a somewhat clumsy solution.\n\nIn our case, we were only using Redis for this particular function, so it\nseemed overkill to be running the service (and maintaining a connection pool to\nit in our Ruby application). Also, our API responses (including the Ember.js\nindex) are already being cached (thanks to a reverse proxy), so talk about\nredundant layers!  It makes more sense for us, for now, to serve the index from\na database table and let our reverse proxy cache it. Perhaps your situation is\nsimilar?\n\n## Quick Start\n\nTo get up and running quickly, do the following:\n\n* Ensure [ember-cli-deploy-build][4] is installed and configured.\n\n* Install this plugin:\n\n    ```sh\n    $ ember install ember-cli-deploy-sql\n    ```\n\n* Install the [appropriate driver](http://knexjs.org/#Installation-node):\n\n    ```sh\n    $ yarn add --dev \u003cyour-database-type\u003e\n    ```\n\n    Or if you're still using npm:\n\n    ```sh\n    $ npm install --save-dev \u003cyour-database-type\u003e\n    ```\n\n* Place the following configuration into `config/deploy.js`:\n\n    ```javascript\n    ENV.sql = {\n      client: '\u003cyour-database-type\u003e',\n      connection: '\u003cyour-connection-string\u003e'\n    }\n    ```\n\n* Run the pipeline:\n\n    ```sh\n    $ ember deploy \u003cenvironment\u003e\n    ```\n\n## Pipeline Hooks Implemented\n\nFor detailed information on what plugin hooks are and how they work, please\nrefer to the [Plugin Documentation][2].\n\n* `activate`\n* `didDeploy`\n* `fetchInitialRevisions`\n* `fetchRevisions`\n* `setup`\n* `upload`\n* `willActivate`\n\n## Configuration Options\n\nFor detailed information on how configuration of plugins works, please refer to\nthe [Plugin Documentation][2].\n\n### client\n\n### connection\n\n### migrations\n\n*Default:* `{ tableName: 'ember_cli_deploy_migrations' }`\n\n### sqlOptions\n\nThese four options are assembled and passed to [Knex.js][3]. Knex is used as a\nquery builder and database abstraction layer (DAL). Please see [its\ndocumentation][11] for more information on these options. N.B.:\n\n* `connection` can be either a string or an object.\n* If a tunnel is present (see below), its port (and host `localhost` unless\n  otherwise specified) will be automatically added to the `connection` object.\n* `sqlOptions` is an optional object that may include any additional top-level\n  configurables to pass to Knex, such as `searchPath`, `debug`, `pool`, etc.\n\n### filePattern\n\nA file matching this pattern will be uploaded to the database table.\n\n*Default:* `'index.html'`\n\n### tableName\n\nThe name of the database table in which to store the revision keys and file\ncontents. By default this option will use the `project.name()` property from\nthe deployment context, snake-cased and suffixed with `_bootstrap`.\n\nThe table is created in your database automatically on the initial deploy, so\nyour database user will need `CREATE TABLE` privileges\u0026mdash;at least\ntemporarily!\n\nThe table looks something like this (e.g. in MySQL):\n\n| Field       | Type         | Null | Key | Default           | Extra          |\n| ----------- | ------------ | ---- | --- | ----------------- | -------------- |\n| id          | int(11)      | NO   | PRI | NULL              | auto_increment |\n| key         | varchar(255) | NO   | UNI | NULL              |                |\n| value       | text         | NO   |     | NULL              |                |\n| gitsha      | binary(20)   | YES  |     | NULL              |                |\n| deployer    | varchar(255) | YES  |     | NULL              |                |\n| description | varchar(255) | YES  |     | NULL              |                |\n| is_active   | tinyint(1)   | NO   |     | 0                 |                |\n| created_at  | timestamp    | NO   |     | CURRENT_TIMESTAMP |                |\n\n*Default:* `${projectName}_bootstrap`\n\nN.B.: `gitsha`, `deployer`, and `description` are reserved for future use.\n\n### allowOverwrite\n\nA flag to specify whether the revision should be overwritten if it already\nexists in the database table.\n\n*Default:* `false`\n\n### maxRecentUploads\n\nThe maximum number of recent revisions to keep in the MySQL table.\n\n*Default:* `10`\n\n## Configuration Prerequisites\n\nThe following properties are expected to be present on the deployment `context`\nobject:\n\n* `distDir` (unless a `distDir` is given in the config; provided by\n  [ember-cli-deploy-build][4])\n* `project.name()` (unless a `tableName` is given in the config; provided by\n  [ember-cli-deploy][5])\n* One of:\n  * `revisionData.revisionKey` (provided by [ember-cli-deploy-revision-data][6])\n  * `commandOptions.revisionKey` (provided by [ember-cli-deploy][5])\n* `deployEnvironment` (provided by [ember-cli-deploy][5])\n\nThe following properties are used if present on the deployment `context`\nobject:\n\n* `tunnel.srcPort` (provided by [ember-cli-deploy-ssh-tunnel][7])\n\n## Activation\n\nAs well as uploading a file to the database table, *ember-cli-deploy-sql* has\nthe ability to mark any revision of a deployed file as currently active.\n\nThe application could be configured to return any existing revision of the\n`index.html` file as requested by a query parameter. However, the revision\nmarked as the currently active revision would be returned if no query parameter\nis present. For more detailed information on this method of deployment please\nrefer to the [ember-cli-deploy-lightning-pack README][1].\n\n### How do I activate a revision?\n\nA user can activate a revision by either:\n\n* Passing an additional command line argument to the `deploy` command:\n\n    ```sh\n    $ ember deploy \u003cenvironment\u003e --activate\n    ```\n\n* Running the `deploy:activate` command:\n\n    ```sh\n    $ ember deploy:activate \u003cenvironment\u003e --revision=\u003crevision-key\u003e\n    ```\n\n* Setting the `activateOnDeploy` flag in `config/deploy.js`\n\n    ```javascript\n    ENV.pipeline = {\n      activateOnDeploy: true\n    }\n    ```\n\n  This has the same effect as passing `--activate` on every invocation of `ember\n  deploy`.\n\n### What does activation do?\n\nWhen *ember-cli-deploy-sql* uploads a file, it uploads it to the table defined\nby the `tableName` config property (which may be derived from the project name),\nwith a key defined by the `revisionKey` config property (which may be derived\nfrom the file contents). So if there have been three revisons deployed (but\nnot activated), the table might look something like this:\n\n```sh\n$ mysql -u root foo\n\nMariaDB [foo]\u003e select `key`, left(`value`, 10), `is_active` from bar_bootstrap;\n+----------------------------------+-------------------+-----------+\n| key                              | left(`value`, 10) | is_active |\n+----------------------------------+-------------------+-----------+\n| cc9d9af44ad70f4a6732c1c13deb246e | \u003c!DOCTYPE         | 0         |\n| 071be39412920947613c00d680b8e9c0 | \u003c!DOCTYPE         | 0         |\n| d56d56274aac91e229fa69f34f4cf81d | \u003c!DOCTYPE         | 0         |\n+----------------------------------+-------------------+-----------+\n```\n\nActivating a revison would update the corresponding entry in the database\ntable:\n\n```sh\n$ ember deploy:activate production --revision=cc9d9af44ad70f4a6732c1c13deb246e\n✔ Activated revision `cc9d9af44ad70f4a6732c1c13deb246e'\n$ mysql -u root foo\n\nMariaDB [foo]\u003e select `key`, left(`value`, 10), `is_active` from bar_bootstrap;\n+----------------------------------+-------------------+-----------+\n| key                              | left(`value`, 10) | is_active |\n+----------------------------------+-------------------+-----------+\n| cc9d9af44ad70f4a6732c1c13deb246e | \u003c!DOCTYPE         | 1         |\n| 071be39412920947613c00d680b8e9c0 | \u003c!DOCTYPE         | 0         |\n| d56d56274aac91e229fa69f34f4cf81d | \u003c!DOCTYPE         | 0         |\n+----------------------------------+-------------------+-----------+\n```\n\n### When does activation occur?\n\nActivation occurs during the `activate` hook of the pipeline. By default,\nactivation is turned off and must be explicitly enabled by one of the three\nmethods described above.\n\n## What if my MySQL server isn't publicly accessible?\n\nNot to worry!  Just install the handy-dandy [ember-cli-deploy-ssh-tunnel][7]\nplugin:\n\n```\nember install ember-cli-deploy-ssh-tunnel\n```\n\nAnd set up your `config/deploy.js` similar to the following:\n\n```js\nENV = {\n  sql: {\n    client: '\u003cyour-database-type\u003e',\n    connection: {\n      // everything except host and port!\n    }\n  },\n  'ssh-tunnel': {\n    username: 'your-ssh-username',\n    host: 'remote-mysql-host'\n  },\n  pipeline: {\n    runOrder: {\n      sql: {\n        after: 'ssh-tunnel'\n      }\n    }\n  }\n}\n```\n\n### What if my MySQL server is only accessible *from* my remote server?\n\nSometimes you need to SSH into a server (a \"bastion\" host) and then run `mysql`\nor what have you from there. This is really common if you're using RDS on AWS,\nfor instance. Ember CLI Deploy has got you covered there, too: just set your\nSSH tunnel host to the bastion server and tell the tunnel to use your database\nserver as the destination host, like so:\n\n```js\nENV = {\n  sql: ..,\n  'ssh-tunnel': {\n    username: 'your-ssh-username',\n    host: 'remote-mysql-client',\n    dstHost: 'remote-mysql-server'\n  },\n  pipeline: ..\n}\n```\n\n## Migrating from ember-cli-deploy-mysql\n\n1. Remove [ember-cli-deploy-mysql][9] from your project:\n\n    ```sh\n    $ yarn remove ember-cli-deploy-mysql\n    ```\n\n    Or if you're still using npm:\n\n    ```sh\n    $ npm uninstall --save-dev ember-cli-deploy-mysql\n    ```\n\n1. Add *ember-cli-deploy-sql* to your project:\n\n    ```sh\n    $ ember install ember-cli-deploy-sql\n    ```\n\n1. Add a MySQL/MariaDB driver to your project:\n\n    ```sh\n    $ yarn add --dev mysql\n    ```\n\n    Or if you're still using npm:\n\n    ```sh\n    $ npm install --save-dev mysql\n    ```\n\n1. Update `config/deploy.js` to use the `sql` key (instead of `mysql`), and\n   adapt your connection options to Knex syntax. For example:\n\n    Before:\n\n    ```javascript\n    mysql: {\n      user: 'jack',\n      password: process.env.MYSQL_PASSWORD,\n      database: 'momotaro'\n    }\n    ```\n\n    After:\n\n    ```javascript\n    sql: {\n      client: 'mysql',\n      connection: {\n        user: 'jack',\n        password: process.env.MYSQL_PASSWORD,\n        database: 'momotaro'\n      }\n    }\n    ```\n\n1. Update your backend to serve the revision `` WHERE `is_active` = 1 ``\n   (instead of the revision pointed to by the `'current'` revision).\n\n1. Run `ember deploy:list \u003cenvironment\u003e` to migrate the database and confirm\n   that the correct revision is (still) active.\n\n## Migrating from ember-cli-deploy-postgres\n\n1. Remove [ember-cli-deploy-postgres][10] from your project:\n\n    ```sh\n    $ yarn remove ember-cli-deploy-postgres\n    ```\n\n    Or if you're still using npm:\n\n    ```sh\n    $ npm uninstall --save-dev ember-cli-deploy-postgres\n    ```\n\n1. Add *ember-cli-deploy-sql* to your project:\n\n    ```sh\n    $ ember install ember-cli-deploy-sql\n    ```\n\n1. Add a PostgreSQL driver to your project:\n\n    ```sh\n    $ yarn add --dev pg\n    ```\n\n    Or if you're still using npm:\n\n    ```sh\n    $ npm install --save-dev pg\n    ```\n\n1. Update `config/deploy.js` to use the `sql` key (instead of `postgres`), and\n   adapt your connection options to Knex syntax. For example:\n\n    Before:\n\n    ```javascript\n    postgres: {\n      user: 'jack',\n      password: process.env.POSTGRESQL_PASSWORD,\n      database: 'momotaro'\n    }\n    ```\n\n    After:\n\n    ```javascript\n    sql: {\n      client: 'pg',\n      connection: {\n        user: 'jack',\n        password: process.env.POSTGRESQL_PASSWORD,\n        database: 'momotaro'\n      }\n    }\n    ```\n\n1. Update your backend to serve the revision `WHERE \"is_active\" = TRUE`\n   (instead of the revision pointed to by the `'current'` revision).\n\n1. Run `ember deploy:list \u003cenvironment\u003e` to migrate the database and confirm\n   that the correct revision is (still) active.\n\n## Tests\n\n* `yarn install \u0026\u0026 yarn test`\n\n### Why `ember test` doesn't work\n\nSince this is a node-only Ember CLI addon, we use mocha for testing and this\npackage does not include many files and devDependencies which are part of Ember\nCLI's typical `ember test` processes.\n\n[1]: https://github.com/lukemelia/ember-cli-deploy-lightning-pack\n[2]: http://ember-cli-deploy.com/plugins/\n[3]: http://knexjs.org\n[4]: https://github.com/ember-cli-deploy/ember-cli-deploy-build\n[5]: https://github.com/ember-cli/ember-cli-deploy\n[6]: https://github.com/ember-cli-deploy/ember-cli-deploy-revision-data\n[7]: https://github.com/ember-cli-deploy/ember-cli-deploy-ssh-tunnel\n[8]: https://github.com/ember-cli-deploy/ember-cli-deploy-redis\n[9]: https://github.com/mwpastore/ember-cli-deploy-mysql\n[10]: https://github.com/weskinner/ember-cli-deploy-postgres\n[11]: http://knexjs.org/#Installation-client\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmwpastore%2Fember-cli-deploy-sql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmwpastore%2Fember-cli-deploy-sql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmwpastore%2Fember-cli-deploy-sql/lists"}