dbmate 2.30.0 → 2.31.0

package/README.md

@@ -111,18 +111,19 @@ docker run --rm -it --network=host -v "$(pwd)/db:/db" ghcr.io/amacneil/dbmate ne
 ## Commands
 
 ```sh
-dbmate --help    # print usage help
-dbmate new       # generate a new migration file
-dbmate up        # create the database (if it does not already exist) and run any pending migrations
-dbmate create    # create the database
-dbmate drop      # drop the database
-dbmate migrate   # run any pending migrations
-dbmate rollback  # roll back the most recent migration
-dbmate down      # alias for rollback
-dbmate status    # show the status of all migrations (supports --exit-code and --quiet)
-dbmate dump      # write the database schema.sql file
-dbmate load      # load schema.sql file to the database
-dbmate wait      # wait for the database server to become available
+dbmate --help         # print usage help
+dbmate new            # generate a new migration file
+dbmate up             # create the database (if it does not already exist) and run any pending migrations
+dbmate create         # create the database
+dbmate drop           # drop the database
+dbmate migrate        # run any pending migrations
+dbmate rollback       # roll back the most recent migration
+dbmate down           # alias for rollback
+dbmate status         # show the status of all migrations (supports --exit-code and --quiet)
+dbmate dump           # write the database schema.sql file
+dbmate dump -- [...]  # optionally pass additional arguments directly to mysqldump or pg_dump
+dbmate load           # load schema.sql file to the database
+dbmate wait           # wait for the database server to become available
 ```
 
 ### Command Line Options
@@ -130,6 +131,7 @@ dbmate wait      # wait for the database server to become available
 The following options are available with all commands. You must use command line arguments in the order `dbmate [global options] command [command options]`. Most options can also be configured via environment variables (and loaded from your `.env` file, which is helpful to share configuration between team members).
 
 - `--url, -u "protocol://host:port/dbname"` - specify the database url directly. _(env: `DATABASE_URL`)_
+- `--driver "driver_name"` - specify the driver to use (if empty, the driver is derived from database URL scheme). _(env: `DBMATE_DRIVER`)_
 - `--env, -e "DATABASE_URL"` - specify an environment variable to read the database connection URL from.
 - `--env-file ".env"` - specify an alternate environment variables file(s) to load.
 - `--migrations-dir, -d "./db/migrations"` - where to keep the migration files. _(env: `DBMATE_MIGRATIONS_DIR`)_
@@ -207,6 +209,18 @@ A `socket` or `host` parameter can be specified to connect through a unix socket
 DATABASE_URL="postgres://username:password@/database_name?socket=/var/run/postgresql"
 ```
 
+For passwordless authentication such as PostgreSQL [peer auth](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html), the password can be omitted (note the `@` is still required):
+
+```sh
+DATABASE_URL="postgres://username@/database_name?socket=/var/run/postgresql"
+```
+
+If the username is also omitted, it defaults to the `PGUSER` environment variable if set, otherwise the OS username (via `lib/pq`, matching `libpq` behavior):
+
+```sh
+DATABASE_URL="postgres:///database_name?socket=/var/run/postgresql"
+```
+
 A `search_path` parameter can be used to specify the [current schema](https://www.postgresql.org/docs/13/ddl-schemas.html#DDL-SCHEMAS-PATH) while applying migrations, as well as for dbmate's `schema_migrations` table.
 If the schema does not exist, it will be created automatically. If multiple comma-separated schemas are passed, the first will be used for the `schema_migrations` table.
 
@@ -255,10 +269,42 @@ Otherwise the migration will fail with "Error: cannot change into wal mode from
 
 #### ClickHouse
 
+Dbmate supports connecting to ClickHouse using native TCP (default) or HTTP/HTTPS.
+
+##### Native (TCP)
+
+By default, the `clickhouse://` scheme uses the native protocol on port `9000`.
+
 ```sh
 DATABASE_URL="clickhouse://username:password@127.0.0.1:9000/database_name"
 ```
 
+##### HTTP / HTTPS
+
+You can use `clickhouse+http://` (deafult port 8123) or `clickhouse+https://` (default port 8443).
+
+```sh
+# HTTP (Defaults to port 8123)
+DATABASE_URL="clickhouse+http://username:password@127.0.0.1:8123/database_name"
+
+# HTTPS (Defaults to port 8443)
+DATABASE_URL="clickhouse+https://username:password@127.0.0.1:8443/database_name"
+```
+
+##### Using the --driver flag
+
+You can use the ClickHouse driver with a standard http/https/tcp URL by providing the --driver flag
+
+```sh
+# Connect via HTTP using generic URL syntax
+dbmate --driver clickhouse --url "http://username:password@127.0.0.1:8123/database_name" status
+
+dbmate --driver clickhouse --url "https://username:password@127.0.0.1:8443/database_name" status
+
+# Better to rely on the standard clickhouse:// scheme, but this is supported
+dbmate --driver clickhouse --url "tcp://username:password@127.0.0.1:9000/database_name" status
+```
+
 To work with ClickHouse cluster, there are 4 connection query parameters that can be supplied:
 
 - `on_cluster` - Indicataion to use cluster statements and replicated migration table. (default: `false`) If this parameter is not supplied, other cluster related query parameters are ignored.
@@ -482,14 +528,26 @@ When you run the `up`, `migrate`, or `rollback` commands, dbmate will automatica
 It is recommended to check this file into source control, so that you can easily review changes to the schema in commits or pull requests. It's also possible to use this file when you want to quickly load a database schema, without running each migration sequentially (for example in your test harness). However, if you do not wish to save this file, you could add it to your `.gitignore`, or pass the `--no-dump-schema` command line option.
 
 To dump the `schema.sql` file without performing any other actions, run `dbmate dump`. Unlike other dbmate actions, this command relies on the respective `pg_dump`, `mysqldump`, or `sqlite3` commands being available in your PATH. If these tools are not available, dbmate will silently skip the schema dump step during `up`, `migrate`, or `rollback` actions. You can diagnose the issue by running `dbmate dump` and looking at the output:
-
 ```sh
 $ dbmate dump
 exec: "pg_dump": executable file not found in $PATH
 ```
-
 On Ubuntu or Debian systems, you can fix this by installing `postgresql-client`, `mysql-client`, or `sqlite3` respectively. Ensure that the package version you install is greater than or equal to the version running on your database server.
 
+It is possible to pass additional arguments directly to mysqldump or pg_dump:
+```sh
+$ dbmate dump -- --flag1 --flag2
+$ dbmate --url="..." dump -- --restrict-key=restrict_key
+```
+for mysqldump:
+```sh
+mysqldump [default_options] [your_arguments_go_here] dbname
+```
+for pg_dump:
+```sh
+pg_dump [default_options] [your_arguments_go_here] dbname
+``` 
+
 > Note: The `schema.sql` file will contain a complete schema for your database, even if some tables or columns were created outside of dbmate migrations.
 
 ## Library

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dbmate",
-  "version": "2.30.0",
+  "version": "2.31.0",
   "description": "A lightweight, framework-agnostic database migration tool",
   "repository": {
     "type": "git",
@@ -30,12 +30,12 @@
     "build": "tsc --build"
   },
   "optionalDependencies": {
-    "@dbmate/linux-ia32": "2.30.0",
-    "@dbmate/linux-x64": "2.30.0",
-    "@dbmate/linux-arm": "2.30.0",
-    "@dbmate/linux-arm64": "2.30.0",
-    "@dbmate/darwin-x64": "2.30.0",
-    "@dbmate/darwin-arm64": "2.30.0",
-    "@dbmate/win32-x64": "2.30.0"
+    "@dbmate/linux-ia32": "2.31.0",
+    "@dbmate/linux-x64": "2.31.0",
+    "@dbmate/linux-arm": "2.31.0",
+    "@dbmate/linux-arm64": "2.31.0",
+    "@dbmate/darwin-x64": "2.31.0",
+    "@dbmate/darwin-arm64": "2.31.0",
+    "@dbmate/win32-x64": "2.31.0"
   }
 }