{"id":13516691,"url":"https://github.com/Vincit/knex-db-manager","last_synced_at":"2025-03-31T06:31:39.684Z","repository":{"id":44884976,"uuid":"63145051","full_name":"Vincit/knex-db-manager","owner":"Vincit","description":"Utility  for create, drop, truncate etc. administrative database operations.","archived":false,"fork":false,"pushed_at":"2022-07-04T14:42:41.000Z","size":2596,"stargazers_count":142,"open_issues_count":12,"forks_count":28,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-29T11:07:31.590Z","etag":null,"topics":["copy-database","copydb","create-database","createdb","drop-database","dropdb","truncate-database","truncatedb"],"latest_commit_sha":null,"homepage":"https://vincit.github.io/knex-db-manager/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Vincit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-07-12T09:29:24.000Z","updated_at":"2024-01-13T23:55:33.000Z","dependencies_parsed_at":"2022-09-03T16:20:40.334Z","dependency_job_id":null,"html_url":"https://github.com/Vincit/knex-db-manager","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vincit%2Fknex-db-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vincit%2Fknex-db-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vincit%2Fknex-db-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vincit%2Fknex-db-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Vincit","download_url":"https://codeload.github.com/Vincit/knex-db-manager/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246174595,"owners_count":20735417,"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":["copy-database","copydb","create-database","createdb","drop-database","dropdb","truncate-database","truncatedb"],"created_at":"2024-08-01T05:01:24.939Z","updated_at":"2025-03-31T06:31:39.654Z","avatar_url":"https://github.com/Vincit.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/Vincit/knex-db-manager.svg?branch=master)](https://travis-ci.org/Vincit/knex-db-manager)\n[![Coverage Status](https://coveralls.io/repos/github/Vincit/knex-db-manager/badge.svg?branch=master)](https://coveralls.io/github/Vincit/knex-db-manager?branch=master)\n[![Greenkeeper badge](https://badges.greenkeeper.io/Vincit/knex-db-manager.svg)](https://greenkeeper.io/)\n\nPretty useful when writing scripts to initialize database for fresh install or\ndropping / creating new database when running tests and for truncating database\nbetween tests.\n\nLibrary uses knex connection for non administrative queries, but also creates\npriviliged connection directly with driver with superuser privileges for creating\nand dropping databases / roles.\n\n## Supported Databases\n\n- PostgreSQL\n- MySQL\n- SQLite3 (partial support even though most of the functions won't make sense with this)\n- ~~Oracle DB Express (TBD)~~\n- ~~MSSQL (TBD if we can get integration tests to run automatically)~~\n\n## Install\n\nYou need to install `knex`, database driver and `knex-db-manager`\n\n```\nnpm install knex-db-manager knex pg pg-escape\n```\n\n## API \u0026 Usage\n\nDatabase manager is initialized with normal `knex` configuration and with\nsuperuser account which should be able to create / drop roles and databases.\n\n\u003e Initialization:\n\n```js\nlet config = {\n  knex: {\n    // just the usual knex configuration\n    client: 'postgres',\n    connection: {\n      host: 'localhost',\n      database: 'appdb',\n      user: 'dbowneruser',\n      password: 'dbownerpassword',\n    },\n    pool: {\n      min: 0,\n      max: 10,\n    },\n    migrations: {\n      directory: __dirname + '/migrations',\n    },\n  },\n  dbManager: {\n    // db manager related configuration\n    collate: ['fi_FI.UTF-8', 'Finnish_Finland.1252'],\n    superUser: 'userwithrightstocreateusersanddatabases',\n    superPassword: 'privilegeduserpassword',\n    populatePathPattern: 'data/**/*.js', // glob format for searching seeds\n  },\n};\n\nlet dbManager = require('knex-db-manager').databaseManagerFactory(config);\n```\n\n### `createDbOwnerIfNotExist(): Promise\u003cvoid\u003e`\n\nCreates the user, which is described in `knex` configuration. This user is used as\nthe database owner when creating new databases.\n\n```js\nlet promise = dbManager.createDbOwnerIfNotExist();\n```\n\n### `createDb(dbName?: string): Promise\u003cvoid\u003e`\n\nCreates database described in `knex` configuration or by given name. Owner of the\ncreated database is set to be the `config.knex.connection.user`.\n\n`dbName` is the name of the database to be created, if not given the name is read\nfrom `config.knex.connection.database`.\n\n\u003e Read database from `config.knex.connection.database`:\n\n```js\nlet promise = dbManager.createDb();\n```\n\n\u003e By given name:\n\n```js\nlet promise = dbManager.createDb('brave-new-db');\n```\n\n### `dropDb(dbName?: string): Promise\u003cvoid\u003e`\n\nDrops database described in `knex` configuration or by given name. Note\nthat if there are any active connections to the database that is being\ndropped, the drop command might fail.\n\n`dbName` is the name of the database to be dropped, if not given the name\nis read from `config.knex.connection.database`.\n\n\u003e Drop database `config.knex.connection.database`:\n\n```js\nlet promise = dbManager.dropDb();\n```\n\n\u003e By specific name:\n\n```js\nlet promise = dbManager.dropDb('brave-new-db');\n```\n\n### `copyDb(fromDbName: string, toDbName: string): Promise\u003cvoid\u003e`\n\nClones database to another name remotely on db serverside (may be useful e.g.\nto make backup before running migrations).\n\nNew database `toDatabaseName` will be created containing a copy of `fromDbName`.\n\nNote: This method is not supported with MySQL (yet).\n\n\u003e Making copy of DB:\n\n```js\nlet promise = dbManager.copyDb('brave-new-db', 'brave-new-db-copy');\n```\n\n### `truncateDb(ignoreTables?: string[]): Promise\u003cvoid\u003e`\n\nTruncate tables of the database and reset corresponding id sequences.\n\n`ignoreTables` list of tables names which should not be truncated.\n\n\u003e Truncate database `config.knex.connection.database`:\n\n```js\nlet promise = dbManager.truncateDb();\n```\n\n\u003e ignore certain tables:\n\n```js\nlet promise = dbManager.truncateDb(['migrations']);\n```\n\n### `updateIdSequences(): Promise\u003cvoid\u003e`\n\nUpdates all primary key id sequences to be biggest id in table + 1.\nSo after running this next `INSERT` to table will get valid id for\nthe row from the sequence.\n\nThis was motivated by some people who liked to create test data with\nhard coded ids, so this helps them to make app to work normally after\nadding rows to tables, which has not used id sequence to get ids.\n\nThe function assumes that the primary key for each table is called `id`.\n\nNote: This method is not supported with MySQL (yet).\n\n\u003e Reset sequence of database `config.knex.connection.database`:\n\n```js\nlet promise = dbManager.updateIdSequences();\n```\n\n### `populateDb(glob: string): Promise\u003cvoid\u003e`\n\nFinds `knex` seed files by pattern and populate database with them.\n\n`glob` is a pattern to match files to be ran, if not given the name is\nread from `config.dbManager.populatePathPattern`.\n\n\u003e Get database from `config.knex.connection.database` and pattern\n\u003e from `config.dbManager.populatePathPattern`:\n\n```js\nlet promise = dbManager.populateDb();\n```\n\n\u003e with pattern:\n\n```js\nlet promise = dbManager.populateDb(path.join(__dirname, 'seeds', 'test-*'));\n```\n\n### `migrateDb(): Promise\u003cvoid\u003e`\n\nRuns `knex` migrations configured in knex config.\n\n\u003e Get database from `config.knex.connection.database`:\n\n```js\nlet promise = dbManager.migrateDb();\n```\n\n### `dbVersion(): Promise\u003cstring\u003e`\n\nChecks which migrations has been ran to database.\n\nExpects that migration name starts with timestamp.\n\nIf no migrations has been run, promise resolves to `'none'`. Otherwise\nresolves to first numbers of latest migration file ran e.g. for\n`20141024070315_test_schema.js` version will be `'20141024070315'`.\n\n\u003e Get database from `config.knex.connection.database`:\n\n```js\nlet promise = dbManager.dbVersion();\n```\n\n### `close(): Promise\u003cvoid\u003e`\n\nCloses the single privileged connection and all normal knex connections.\n\n\u003e Kill database connection:\n\n```js\nlet promise = dbManager.close();\n```\n\n### `closeKnex(): Promise\u003cvoid\u003e`\n\nCloses knex connection which is made to the database for unprivileged\nqueries. Sometimes this is needed e.g. for being able to drop database.\n\n\u003e Close knex connection\n\n```js\nlet promise = dbManager.closeKnex();\n```\n\n### `knexInstance(): QueryBuilder`\n\nReturns `knex` query builder bound to configured database.\n\n\u003e Get database from `config.knex.connection.database`:\n\n```js\nlet knex = dbManager.knexInstance();\nknex('table')\n  .where('id', 1)\n  .then((rows) =\u003e {\n    console.log('Query was ran with db owner privileges', rows);\n  });\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVincit%2Fknex-db-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FVincit%2Fknex-db-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVincit%2Fknex-db-manager/lists"}