1 | ## How to contribute to Knex.js
|
2 |
|
3 | - Make changes in the `/lib` directory.
|
4 |
|
5 | - Before sending a pull request for a feature or bug fix, be sure to have
|
6 | [tests](https://github.com/knex/knex/tree/master/test). Every pull request that changes the queries should have
|
7 | also **integration tests which are ran against real database** (in addition to unit tests which checks which kind of queries
|
8 | are being created).
|
9 |
|
10 | - Use the same coding style as the rest of the
|
11 | [codebase](https://github.com/knex/knex/blob/master/knex.js).
|
12 |
|
13 | - All pull requests should be made to the `master` branch.
|
14 |
|
15 | - Pull request description should have link to corresponding PR of documentation branch.
|
16 |
|
17 | - All pull requests that modify the public API should be updated in [types/index.d.ts](https://github.com/knex/knex/blob/master/types/index.d.ts)
|
18 |
|
19 | ## Documentation
|
20 |
|
21 | Documentation is no longer maintained in knex master repository. All the documentation pull requests should be sent to https://github.com/knex/documentation
|
22 |
|
23 | Documentation pull requests should not be merged before knex version which has the new documented feature is released.
|
24 |
|
25 | ## I would like to add support for new dialect to knex, is it possible?
|
26 |
|
27 | Currently there are already way too many dialects supported in `knex` and instead of adding new dialect to central codebase, all the dialects should be moved to separate npm packages out from `knex` core library with their respective maintainers and test suites.
|
28 |
|
29 | So if you like to write your own dialect, you can just inherit own dialect from knex base classes and use it by passing dialect to knex in knex configuration (https://runkit.com/embed/90b3cpyr4jh2):
|
30 |
|
31 | ```js
|
32 | // simple dialect overriding sqlite3 dialect to use sqlite3-offline driver
|
33 | require('sqlite3-offline');
|
34 | const Knex = require('knex');
|
35 |
|
36 | const Dialect = require(`knex/lib/dialects/sqlite3/index.js`);
|
37 | Dialect.prototype._driver = () => require('sqlite3-offline');
|
38 |
|
39 | const knex = Knex({
|
40 | client: Dialect,
|
41 | connection: ':memory:',
|
42 | });
|
43 |
|
44 | console.log(knex.select(knex.raw(1)).toSQL());
|
45 |
|
46 | await knex.schema.createTable('fooobar', (t) => {
|
47 | t.bigincrements('id');
|
48 | t.string('data');
|
49 | });
|
50 | await knex('fooobar').insert({ data: 'nomnom' });
|
51 |
|
52 | console.log('Gimme all the data:', await knex('fooobar'));
|
53 | ```
|
54 |
|
55 | ## What is minimal code to reproduce bug and why I have to provide that when I can just tell whats the problem is
|
56 |
|
57 | Writing minimal reproduction code for the problem is time-consuming and sometimes it is also really hard, for
|
58 | example when the original code where the bug happens is written using express or mocha. So why is it necessary
|
59 | for me to commit so much time to it when the problem is in `knex`? Contributors should be grateful that I reported
|
60 | the bug I found.
|
61 |
|
62 | The point of runnable code to reproduce the problem is to easily verify that there really is a problem and that the one
|
63 | who did the report did nothing wrong (surprisingly often problem is in the user code). So instead of just description
|
64 | what to do the complete code encourages devs to actually test out that problem exists and start solving it and it
|
65 | saves lots of time.
|
66 |
|
67 | tl;dr list:
|
68 |
|
69 | 1. Actually in most of the cases developer already figures out what was the problem when writing the minimal test case
|
70 | or if there was problem how stuff was initialized or how async code was written it is easy to point out the problem.
|
71 |
|
72 | 2. It motivates developer to actually try out if the bug really exist by not having to figure out from incomplete example
|
73 | environment in which and how bug actually manifests.
|
74 |
|
75 | 3. There are currently very few people fixing knex issues and if one has to put easily 15-30 minutes time to issue just
|
76 | to see that I cannot reproduce this issue it just wastes development hours that were available for improving knex.
|
77 |
|
78 | Test case should initialize needed tables, insert needed data and fail...
|
79 |
|
80 | ```
|
81 | const knex = require('knex')({
|
82 | client: 'pg',
|
83 | connection: 'postgres:///knex_test'
|
84 | });
|
85 |
|
86 | async function main() {
|
87 | await knex.schema.createTable(...);
|
88 | await knex('table').insert({foo: 'bar}');
|
89 | await knex.destroy();
|
90 | }
|
91 |
|
92 | main();
|
93 | ```
|
94 |
|
95 | Usually issues without reproduction code available are just closed and if the same issue is reported multiple
|
96 | times maybe someone looks into it.
|
97 |
|
98 | One easy way to setup database for your reproduction is to use database from knex's docker-compose setup (npm run db:start) and by checking the connection settings from tests' `test/knexfile.js`.
|
99 |
|
100 | ## Integration Tests
|
101 |
|
102 | ### The Easy Way
|
103 |
|
104 | By default, Knex runs tests against sqlite3, postgresql, mysql, mysql2, mssql and oracledb drivers. All databases can be initialized and ran with docker.
|
105 |
|
106 | Docker databases can be started and initialized and started with:
|
107 |
|
108 | ```bash
|
109 | npm run db:start
|
110 | ```
|
111 |
|
112 | and stopped with:
|
113 |
|
114 | ```bash
|
115 | npm run db:stop
|
116 | ```
|
117 |
|
118 | In case you don't need all of the databases, you can use simplified dev Docker configuration that only runs PostgreSQL, by running `npm run db:start:postgres` and `npm run db:stop:postgres` accordingly.
|
119 |
|
120 | ### Installing support for oracledb
|
121 |
|
122 | Oracle has started providing precompiled driver libs for all the platforms, which makes it viable to run oracle tests also locally against oracledb running in docker.
|
123 |
|
124 | Check message when running
|
125 |
|
126 | ```bash
|
127 | npm install oracledb
|
128 | ```
|
129 |
|
130 | and download driver library binary packages and unzip it to ~/lib directory.
|
131 |
|
132 | ### Specifying Databases
|
133 |
|
134 | You can optionally specify which dialects to test using the `DB` environment variable. Values should be space separated and can include:
|
135 |
|
136 | - mysql
|
137 | - mysql2
|
138 | - postgres
|
139 | - sqlite3
|
140 | - oracledb
|
141 | - mssql
|
142 |
|
143 | ```bash
|
144 | $ DB='postgres mysql' npm test
|
145 | ```
|
146 |
|
147 | ### Custom Configuration
|
148 |
|
149 | If you'd like to override the database configuration (to use a different host, for example), you can override the path to the [default test configuration](https://github.com/knex/knex/blob/master/test/knexfile.js) using the `KNEX_TEST` environment variable.
|
150 |
|
151 | ```bash
|
152 | $ KNEX_TEST='./path/to/my/config.js' npm test
|
153 | ```
|
154 |
|
155 | ### Creating Postgres User
|
156 |
|
157 | If you are running tests against own local database one might need to setup test user and database for knex to connect.
|
158 |
|
159 | To create a new user, login to Postgres and use the following queries to add the user. This assumes you've already created the `knex_test` database.
|
160 |
|
161 | ```
|
162 | CREATE ROLE postgres WITH LOGIN PASSWORD '';
|
163 | GRANT ALL PRIVILEGES ON DATABASE "knex_test" TO postgres;
|
164 | ```
|
165 |
|
166 | Once this is done, check it works by attempting to login:
|
167 |
|
168 | ```
|
169 | psql -h localhost -U postgres -d knex_test
|
170 | ```
|
171 |
|
172 | ## Want to be Collaborator?
|
173 |
|
174 | There is always room for more collaborators. Be active on resolving github issues / sending pull requests / reviewing code and we will ask you to join.
|
175 |
|
176 | ### Etiquette (/ˈɛtᵻkɛt/ or /ˈɛtᵻkɪt/, French: [e.ti.kɛt])
|
177 |
|
178 | Make pull requests for your changes, do not commit directly to master (release stuff like fixing changelog are ok though).
|
179 |
|
180 | All the pull requests must be peer reviewed by other collaborator, so don't merge your request before that. If there is no response ping others.
|
181 |
|
182 | If you are going to add new feature to knex (not just a bugfix) it should be discussed first with others to agree on details.
|
183 |
|
184 | Join Gitter chat if you feel to chat outside of github issues.
|