docs: clarify remote SQLite connection entry points

R/dbConnect_SQLiteDriver.R

@@ -12,6 +12,11 @@
 #'     will be deleted when the connection is closed.
 #'   \item `":memory:"` or `"file::memory:"` will create a temporary
 #'     in-memory database.
+#'   \item If the optional HTTP VFS is available, remote read-only SQLite
+#'     databases can be opened with [sqliteRemote()] or with a SQLite URI
+#'     filename such as
+#'     `"file:https://example.org/db.sqlite?vfs=http&immutable=1"` and
+#'     `flags = SQLITE_RO`.
 #'   }
 #' @param cache_size Advanced option. A positive integer to change the maximum
 #'   number of disk pages that SQLite holds in memory (SQLite's default is

README.Rmd

@@ -43,6 +43,30 @@ when the package is built with libcurl support, enabling read-only access to rem
 SQLite databases. See the help pages for `initExtension()`, `sqliteHttpConfig()`,
 `sqliteRemote()`, and `sqliteHasHttpVFS()`.
 
+If HTTP VFS support is available, `sqliteRemote()` is the easiest way to open a
+remote database:
+
+```r
+if (sqliteHasHttpVFS()) {
+  con <- sqliteRemote("https://example.org/db.sqlite")
+  dbDisconnect(con)
+}
+```
+
+For cases where you need the explicit SQLite URI filename, use
+`dbConnect()` with `flags = SQLITE_RO`:
+
+```r
+if (sqliteHasHttpVFS()) {
+  con <- dbConnect(
+    RSQLite::SQLite(),
+    "file:https://example.org/db.sqlite?vfs=http&immutable=1",
+    flags = SQLITE_RO
+  )
+  dbDisconnect(con)
+}
+```
+
 Discussions associated with DBI and related database packages take place on [R-SIG-DB](https://stat.ethz.ch/mailman/listinfo/r-sig-db).
 The website [Databases using R](https://db.rstudio.com/) describes the tools and best practices in this ecosystem.
 

README.md

@@ -44,6 +44,30 @@ read-only access to remote SQLite databases. See the help pages for
 `initExtension()`, `sqliteHttpConfig()`, `sqliteRemote()`, and
 `sqliteHasHttpVFS()`.
 
+If HTTP VFS support is available, `sqliteRemote()` is the easiest way to
+open a remote database:
+
+``` r
+if (sqliteHasHttpVFS()) {
+  con <- sqliteRemote("https://example.org/db.sqlite")
+  dbDisconnect(con)
+}
+```
+
+For cases where you need the explicit SQLite URI filename, use
+`dbConnect()` with `flags = SQLITE_RO`:
+
+``` r
+if (sqliteHasHttpVFS()) {
+  con <- dbConnect(
+    RSQLite::SQLite(),
+    "file:https://example.org/db.sqlite?vfs=http&immutable=1",
+    flags = SQLITE_RO
+  )
+  dbDisconnect(con)
+}
+```
+
 Discussions associated with DBI and related database packages take place
 on [R-SIG-DB](https://stat.ethz.ch/mailman/listinfo/r-sig-db). The
 website [Databases using R](https://db.rstudio.com/) describes the tools