stabilize import db (#5293)

Merge when iterative/dvc#10510 gets released. Closes #5087.
iterative · Aug 9, 2024 · b3c60b6 · b3c60b6
1 parent 9a2d0fb
commit b3c60b6
Show file tree

Hide file tree

Showing 3 changed files with 12 additions and 8 deletions.
diff --git a/content/docs/command-reference/import-db.md b/content/docs/command-reference/import-db.md
@@ -1,11 +1,5 @@
 # import-db
 
-<admon type="warn" title="Experimental">
-
-This is an experimental command, and is subject to breaking changes.
-
-</admon>
-
 Snapshot a table or a SQL query results from a database into CSV/JSON format.
 
 ```usage

diff --git a/content/docs/command-reference/update.md b/content/docs/command-reference/update.md
@@ -20,8 +20,8 @@ positional arguments:
 
 ## Description
 
-After creating import stages (`.dvc` files) with `dvc import` or
-`dvc import-url`, the data source can change. Use `dvc update` to bring these
+After creating import stages (`.dvc` files) with `dvc import`, `dvc import-url`,
+or `dvc import-db`, the data source can change. Use `dvc update` to bring these
 imported files or directories up to date.
 
 To indicate which import stages to update, we can specify the corresponding

diff --git a/content/docs/user-guide/project-structure/dvc-files.md b/content/docs/user-guide/project-structure/dvc-files.md
@@ -74,6 +74,7 @@ The following subfields may be present under `deps` entries:
 | `size`                          | Size of the file or directory (sum of all files).                                                                                                                                                                                                |
 | `nfiles`                        | If this dependency is a directory, the number of files inside (recursive).                                                                                                                                                                       |
 | `repo`                          | Only in external dependencies created with `dvc import`: It can contain `url`, `rev`, `rev_lock`, `config` and `remote` (detailed below).                                                                                                        |
+| `db`                            | Only in db dependencies created with `dvc import-db`: It can contain `connection`, `file_format`, `query` and `table` (detailed below).                                                                                                          |
 
 ### Dependency `repo` subfields:
 
@@ -85,4 +86,13 @@ The following subfields may be present under `deps` entries:
 | `config`   | When `dvc import --config` is used: Path to a [config file](/doc/command-reference/config) that will be merged with the config in the target repository. When both `--remote` and `--remote-config` are used: config options that will be merged with the config in the target repository. See examples section in`dvc import`. |
 | `remote`   | Only when `dvc import --remote` or `--remote-config` is used: name of the `dvc remote` to set as a default or remote config options to merge with a default remote's config in the target repository. See examples section in `dvc import`.                                                                                     |
 
+### Dependency `db` subfields:
+
+| Field         | Description                                                                                                                                                              |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `connection`  | Name of the connection to use. The connection has to be set in the config before use. See [Database Connections](/doc/command-reference/import-db#database-connections). |
+| `query`       | SQL query to snapshot. It is only set if `--sql` option was used on `dvc import-db`. `dvc update` will use this field to re-import.                                      |
+| `table`       | Name of the database table to snapshot. It is only set if `--table` option was used on `dvc import-db`. `dvc update` will use this field to re-import.                   |
+| `file_format` | Export format to use. At the moment, it can be set to either `csv` or `json`.                                                                                            |
+
 [git revision]: https://git-scm.com/docs/revisions