Merge branch 'master' into fixing-whereILike-in-sqlite-issue-5604

.github/ISSUE_TEMPLATE.md

@@ -29,7 +29,11 @@ If issue is about TypeScript definitions, tag @ lorefnon.
 
 # Missing / erroneus documentation
 
-Send issue to documentation repo, or fix it and send PR https://github.com/knex/documentation
+1. What is the missing or erroneus part of the documentation
+
+2. What is the correct information
+
+3. If you have time, you can also make a pull request to fix the documentation
 
 # Questions about how to use knex
 

.github/workflows/docs-deploy.yml

@@ -0,0 +1,53 @@
+name: Knex / Documentation deployment
+
+on:
+  push:
+    branches:
+      - 'master'
+    paths:
+      - docs/**
+      - .github/workflows/**
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./docs
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 16.x
+
+      # cache node_modules
+      - name: Restore cached dependencies
+        uses: actions/cache@v3
+        id: npm-cache
+        with:
+          path: |
+            **/node_modules
+          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-npm-
+
+      # install dependencies if the cache did not hit
+      - name: Install dependencies
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npm ci
+
+      - name: Build documentation
+        run: npm run build
+
+      - name: Deploy to gh-pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/.vitepress/dist
+          cname: knexjs.org
+          force_orphan: true

.gitignore

@@ -1,5 +1,6 @@
 yarn.lock
 package-lock.json
+!docs/package-lock.json
 raw
 *.sw?
 .idea

CHANGELOG.md

@@ -1,5 +1,27 @@
 # Master (Unreleased)
 
+# 3.1.0 - 8 December, 2023
+
+### Bug fixes
+
+- andWhereNotJsonObject calling wrong function (#5683)
+- PostgreSQL: fix error when setting query_timeout (#5673)
+- MySQL: Missing comments on delete, update and insert (#5738)
+- MySQL: Fixed issue with bigincrements not working with composite primary key - #5341 (#5343)
+
+### Types
+
+- Add type definitions for orHavingNull and orHavingNotNull (#5669)
+- Import knex as type in TS migration template (#5741)
+- Fix conditional constraint error (#5747)
+- PostgreSQL: Fix typing to reflect pg typing change (#5647)
+
+### New features
+
+- Add transactor.parentTransaction (#5567)
+- MySQL: Added implementation for upsert (#5743)
+- Oracle: Support Object Names Greater than 30 Characters for Oracle DB Versions 12.2 and Greater (#5197)
+
 # 3.0.1 - 6 October, 2023
 
 - Build fix

CONTRIBUTING.md

@@ -18,9 +18,7 @@
 
 ## Documentation
 
-Documentation is no longer maintained in knex master repository. All the documentation pull requests should be sent to https://github.com/knex/documentation
-
-Documentation pull requests should not be merged before knex version which has the new documented feature is released.
+Documentation is maintained in the `/docs` folder. every pull request that changes the public API should also update the docs
 
 ## I would like to add support for new dialect to knex, is it possible?
 

docs/.gitignore

@@ -0,0 +1,2 @@
+node_modules
+.vitepress/dist

docs/.vitepress/config.ts

@@ -0,0 +1,105 @@
+import { defineConfig } from 'vitepress';
+import KnexDialectsPlugins from './knexDialects';
+
+export default defineConfig({
+  title: 'Knex.js',
+  description: 'Beta knex.js documentation.',
+  base: '/',
+  srcDir: 'src',
+  head: [['link', { rel: 'icon', type: 'image/png', href: '/knex-logo.png' }]],
+  themeConfig: {
+    logo: '/knex-logo.png',
+    repo: 'knex/knex',
+    docsRepo: 'knex/knex',
+    docsDir: 'docs/src',
+    docsBranch: 'master',
+    editLinks: true,
+    editLinkText: 'Edit this page on GitHub',
+    lastUpdated: 'Last Updated',
+    nav: [
+      { text: 'Guide', link: '/guide/', activeMatch: '^/guide/' },
+      {
+        text: 'F.A.Q.',
+        link: '/faq/',
+      },
+      {
+        text: 'Changelog',
+        link: '/changelog.html',
+      },
+    ],
+    sidebar: {
+      '/guide/': getGuideSidebar(),
+      '/faq/': getFaqSidebar(),
+    },
+    algolia: {
+      appId: 'V7E3EHUPD6',
+      apiKey: '44b5077836c1c8fba0f364383dde7fb4',
+      indexName: 'knex',
+      initialQuery: '',
+    },
+  },
+  vite: {
+    plugins: [KnexDialectsPlugins()],
+  },
+});
+
+function getGuideSidebar() {
+  return [
+    {
+      text: 'Installation',
+      link: '/guide/',
+    },
+    {
+      text: 'Query Builder',
+      link: '/guide/query-builder',
+    },
+    {
+      text: 'Transactions',
+      link: '/guide/transactions',
+    },
+    {
+      text: 'Schema Builder',
+      link: '/guide/schema-builder',
+    },
+    {
+      text: 'Raw',
+      link: '/guide/raw',
+    },
+    {
+      text: 'Ref',
+      link: '/guide/ref',
+    },
+    {
+      text: 'Utility',
+      link: '/guide/utility',
+    },
+    {
+      text: 'Interfaces',
+      link: '/guide/interfaces',
+    },
+    {
+      text: 'Migrations',
+      link: '/guide/migrations',
+    },
+    {
+      text: 'Extending',
+      link: '/guide/extending',
+    },
+  ];
+}
+function getFaqSidebar() {
+  return [
+    {
+      text: 'F.A.Q.',
+      link: '/faq/',
+    },
+    {
+      text: 'Recipes',
+      link: '/faq/recipes',
+    },
+    {
+      text: 'Support',
+      link: '/faq/support',
+    },
+  ];
+}

docs/.vitepress/knexDialects.ts

@@ -0,0 +1,46 @@
+import Knex from 'knex';
+import type { PluginOption } from 'vite';
+
+const dialects = {
+  'better-sqlite3': Knex({ client: 'better-sqlite3' }),
+  cockroachdb: Knex({ client: 'cockroachdb' }),
+  mssql: Knex({ client: 'mssql' }),
+  mysql: Knex({ client: 'mysql' }),
+  mysql2: Knex({ client: 'mysql2' }),
+  oracledb: Knex({ client: 'oracledb' }),
+  pgnative: Knex({ client: 'pgnative' }),
+  postgres: Knex({ client: 'postgres' }),
+  redshift: Knex({ client: 'redshift' }),
+  sqlite3: Knex({ client: 'sqlite3' }),
+};
+
+export default function knexDialects(): PluginOption {
+  const regex = /<SqlOutput[\s]*code="([^"]+)"[\s]*\/>/gi;
+
+  return {
+    name: 'transform-file',
+    enforce: 'pre',
+
+    transform(src, id) {
+      if (id.endsWith('.md')) {
+        const matches = src.matchAll(regex);
+        for (const match of matches) {
+          let markdown = '';
+          const getCode = Function('knex', `return knex.raw(${match[1]});`);
+
+          for (const dialect in dialects) {
+            const knex = dialects[dialect];
+            const { sql } = getCode(knex);
+            const output = sql.toString();
+
+            markdown += `<div data-dialect="${dialect}">\n\n\`\`\`sql\n${output}\n\`\`\`\n\n</div>\n`;
+          }
+
+          src = src.replace(match[0], markdown);
+        }
+      }
+
+      return src;
+    },
+  };
+}