Better SQLALchemy connection string examples, closes #11

README.md

@@ -26,7 +26,17 @@ For PostgreSQL, use this:
 
       Load data from any database into SQLite.
 
-      https://github.com/simonw/db-to-sqlite
+      PATH is a path to the SQLite file to create, e.c. /tmp/my_database.db
+
+      CONNECTION is a SQLAlchemy connection string, for example:
+
+          postgresql://localhost/my_database
+          postgresql://username:passwd@localhost/my_database
+
+          mysql://root@localhost/my_database
+          mysql://username:passwd@localhost/my_database
+
+      More: https://docs.sqlalchemy.org/en/13/core/engines.html#database-urls
 
     Options:
       --version                     Show the version and exit.
@@ -40,7 +50,6 @@ For PostgreSQL, use this:
       -p, --progress                Show progress bar
       --help                        Show this message and exit.
 
-
 For example, to save the content of the `blog_entry` table from a PostgreSQL database to a local file called `blog.db` you could do this:
 
     db-to-sqlite "postgresql://localhost/myblog" blog.db \

db_to_sqlite/cli.py

@@ -30,8 +30,18 @@
 def cli(connection, path, all, table, skip, redact, sql, pk, index_fks, progress):
     """
     Load data from any database into SQLite.
-    
-    https://github.com/simonw/db-to-sqlite
+
+    PATH is a path to the SQLite file to create, e.c. /tmp/my_database.db
+
+    CONNECTION is a SQLAlchemy connection string, for example:
+
+        postgresql://localhost/my_database
+        postgresql://username:passwd@localhost/my_database
+
+        mysql://root@localhost/my_database
+        mysql://username:passwd@localhost/my_database
+
+    More: https://docs.sqlalchemy.org/en/13/core/engines.html#database-urls
     """
     if not all and not table:
         raise click.ClickException("--all OR --table required")

tests/test_db_to_sqlite.py

@@ -41,9 +41,7 @@ def test_db_to_sqlite(connection, tmpdir):
 def test_index_fks(connection, tmpdir):
     db_path = str(tmpdir / "test_with_fks.db")
     # With --no-index-fks should create no indexes
-    CliRunner().invoke(
-        cli.cli, [connection, db_path, "--all", "--no-index-fks"]
-    )
+    CliRunner().invoke(cli.cli, [connection, db_path, "--all", "--no-index-fks"])
     db = sqlite_utils.Database(db_path)
     assert [] == db["products"].indexes
     # Without it (the default) it should create the indexes

tests/test_docs.py

@@ -1,3 +1,4 @@
+import difflib
 from pathlib import Path
 
 from click.testing import CliRunner
@@ -15,8 +16,24 @@ def test_readme_contains_latest_help():
     help_text_indented = "\n".join(
         [
             ("    {}".format(line) if line.strip() else "")
-            for line in help_text.split("\n")
+            for line in help_text.splitlines()
         ]
     ).replace("Usage: cli ", "Usage: db-to-sqlite ")
     readme = readme_path.read_text()
-    assert help_text_indented in readme
+    # Compare to just lines starting with 'Usage: db-to-sqlite' and ending --help
+    relevant_lines = []
+    collecting = False
+    for line in readme.splitlines():
+        if collecting:
+            relevant_lines.append(line)
+            if line.strip().startswith("--help"):
+                break
+        elif line.strip().startswith("Usage: db-to-sqlite"):
+            relevant_lines.append(line)
+            collecting = True
+    relevant_text = "\n".join(relevant_lines)
+    if help_text_indented != relevant_text:
+        print("\n".join(
+            difflib.ndiff(relevant_text.splitlines(), help_text_indented.splitlines())
+        ))
+        assert False