Documentation Source Text

Check-in [809f9fa181]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Add documentation for shell tool SQLAR archive support.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 809f9fa181f0e31a9bf87d81b0b8611b981a0d8c083c49a57c85af5b8d6e26b6
User & Date: dan 2017-12-09 15:44:16.609
Context
2017-12-12
01:16
Changes to walformat.html document. (check-in: c0a1fede37 user: drh tags: trunk)
2017-12-09
15:44
Add documentation for shell tool SQLAR archive support. (check-in: 809f9fa181 user: dan tags: trunk)
2017-11-25
15:22
Update the fts5 documentation to make it clear that the xDestroy function is not invoked if either xCreateFunction or xCreateTokenizer fails. (check-in: 820de7c995 user: dan tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/cli.in.
757
758
759
760
761
762
763



































































































764
765
766
767
768
769
770
does not already exists, then appends entries that check the SHA3
hash of the content of all tables.  Subsequent runs of ".selftest"
will verify that the database has not been changed in any way.  To
generates tests to verify that a subset of the tables are unchanged,
simply run ".selftest --init" then [DELETE] the selftest rows that
refer to tables that are not constant.  




































































































<tcl>hd_fragment dotother</tcl>
<h1>Other Dot Commands</h1>

<p>There are many other dot-commands available in the command-line
shell.  See the ".help" command for a complete list for any particular
version and build of SQLite.








>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
does not already exists, then appends entries that check the SHA3
hash of the content of all tables.  Subsequent runs of ".selftest"
will verify that the database has not been changed in any way.  To
generates tests to verify that a subset of the tables are unchanged,
simply run ".selftest --init" then [DELETE] the selftest rows that
refer to tables that are not constant.  

<tcl>hd_fragment sqlar</tcl>
<h1>SQLAR Archive Support</h1>

<p>The shell tool ".ar" dot-command provides built-in support for the 
[https://sqlite.org/sqlar|SQLite ARchive format]. The interface is similar to
that of the "tar" command on unix systems. Each invocation of the ".ar"
command must specify a single command option. The following commands
are available:

<table striped=1>
  <tr><th style="width:15ex">Option<th style="width:17ex">Long&nbsp;Option<th>Purpose
  <tr><td>-c<td>--create<td>Create a new archive containing specified files.
  <tr><td>-x<td>--extract<td>Extract specified files from archive.
  <tr><td>-t<td>--list<td>List the files in the archive.
  <tr><td>-u<td>--update<td>Add files to existing archive.
</table>

<p>As well as the command option, each invocation of ".ar" may specify
one or more modifier options. Some modifier options require an argument,
some do not. The following modifier options are available:

<table striped=1>
  <tr><th style="width:15ex">Option<th style="width:17ex">Long&nbsp;Option<th>Purpose
  <tr><td>-v<td>--verbose<td>List each file as it is processed.
  <tr><td>-f FILE<td>--file FILE<td>If specified, use file FILE as the
  archive. Otherwise, assume that the current "main" database is the 
  archive to be operated on.
  <tr><td>-C DIR<td>--directory DIR<td>If specified, interpret all relative
  paths as relative to DIR, instead of the current working directory.
  <tr><td>--<td>--<td>All subsequent command line words are command arguments,
  not options.
</table>

<p>
Long and short style options may be mixed. For example, the following are
equivalent:

<codeblock>
  <i>-- Two ways to create a new archive named "new_archive.db" containing</i>
  <i>-- files "file1", "file2" and "file3".</i>
  .ar -c --file new_archive.db file1 file2 file3
  .ar -f new_archive.db --create file1 file2 file3
</codeblock>

<p>Alternatively, the first argument following to ".ar" may be the concatenation
of the short form of all required options (without the "-" characters). In 
this case arguments for options requiring them are read from the command line
next, and any remaining words are considered command arguments. For example:

<codeblock>
  <i>-- Create a new archive "new_archive.db" containing files "file1" and</i>
  <i>-- "file2" from directory "dir1".</i>
  .ar cCf dir1 new_archive.db file1 file2 file3
</codeblock>

<h2> SQLAR Create Command </h2>

<p>Create a new archive, clobbering any existing archive (either in the current
"main" db or in the file specified by a --file option). Each argument following
the options is a file to add to the archive. Directories are imported
recursively. See above for examples.

<h2> SQLAR Extract Command </h2>

<p>Extract files from the archive (either to the current working directory or
to the directory specified by a --directory option). If there are no arguments
following the options all files are extracted from the archive. Or, if there
are arguments, they are the names of files to extract from the archive. Any
specified directories are extracted recursively. It is an error if any
specified files are not part of the archive.

<codeblock>
  <i>-- Extract all files from the archive in the current "main" db to the</i>
  <i>-- current working directory. List files as they are extracted. </i>
  .ar --extract --verbose

  <i>-- Extract file "file1" from archive "ar.db" to directory "dir1".</i>
  .ar fCx ar.db dir1 file1
</codeblock>

<h2> SQLAR List Command </h2>

<p>List the contents of the archive. If no arguments are specified, then all
files are listed. Otherwise, only those specified as arguments are. Currently,
the --verbose option does not change the behaviour of this command. That may
change in the future.

<codeblock>
  <i>-- List contents of archive in current "main" db.</i>.
  .ar --list
</codeblock>

<h2> SQLAR Update Command </h2>

<p> This command works the same way as the --create command, except that 
it does not delete the current archive before commencing. New versions of
files silently replace existing files with the same names, but otherwise
the initial contents of the archive (if any) remain intact.

<tcl>hd_fragment dotother</tcl>
<h1>Other Dot Commands</h1>

<p>There are many other dot-commands available in the command-line
shell.  See the ".help" command for a complete list for any particular
version and build of SQLite.