壳

Shell为您提供了一种与SQLite交互、执行管理和提供SQL以供执行的便捷方式。它是仿照 shell that comes with SQLite 它需要单独编译和安装。

值得注意的改进包括：

  • 您可以通过编程方式调用该Shell，这对于开发和调试非常有用

  • 输出是彩色的

  • 可使用制表符完成功能

  • 更好的文本转储输出，包括USER_VERSION之类的元数据

  • 有用 autoimport 和 find 命令

备注

要中断Shell，请按Control-C。(在Windows上，如果按下Control-Break，程序将立即中止。)

对于Windows用户，除非您安装了 readline module 。您可以通过PIP安装 pyreadline3 以获得完整的功能。

对于Windows用户，使用内置控制台对颜色的支持。在当前版本的Windows中默认启用该功能，在较旧版本中启用注册表项 (details) 。

命令行用法

您可以直接从命令行使用Shell。

Usage: python3 -m apsw [OPTIONS] FILENAME [SQL|CMD] [SQL|CMD]...
FILENAME is the name of a SQLite database. A new database is
created if the file does not exist. If omitted or an empty
string then an in-memory database is created.
OPTIONS include:

   -init filename       read/process named file
   -echo                print commands before execution
   -[no]header          turn headers on or off
   -bail                stop after hitting the first error
   -interactive         force interactive I/O
   -batch               force batch I/O
   -column              set output mode to 'column'
   -csv                 set output mode to 'csv'
   -html                set output mode to 'html'
   -line                set output mode to 'line'
   -list                set output mode to 'list'
   -python              set output mode to 'python'
   -jsonl               set output mode to 'jsonl'
   -separator 'x'       set output field separator (|)
   -nullvalue 'text'    set text string for NULL values
   -version             show SQLite version
   -encoding 'name'     the encoding to use for files
                        opened via .import, .read & .output
   -nocolour            disables interactive colour output

程序性用法

您还可以通过编程方式使用Shell(甚至可以同时以交互方式和编程方式使用)。请参阅 example 用于使用该API。

要快速调用类似于Python调试器的Shell，请执行以下操作：

apsw.shell.Shell(db=database_of_interest).cmdloop()

您可以使用 .connection 在连接之间切换。在提示符下按Control-D(在Windows上按Control-Z)将退出Shell。

指令

除了执行SQL之外，还可以使用这些命令及其说明。命令与SQL的区别在于有一个前导 . (句号)-例如：：

.help
.mode qbox
.find winchester

自动导入文件名？表？

Imports filename creating a table and automatically working out separators and data types (alternative to .import command)

IMPORT命令要求您精确地预先设置表和模式，并设置数据分隔符(例如逗号或制表符)。此命令会自动计算出分隔符和CSV方言。必须至少有两列和两行。

如果未指定该表，则将使用文件的基本名称。

此外，还会推断出每列内容的类型--例如，如果它是数字或日期。空值将变为空值。日期被标准化为 YYYY -``MM`-``DD``格式和DateTime归一化为ISO8601格式，便于排序和搜索。必须使用4位数的年份来检测日期。如果至少有一个值可以解决模棱两可的问题，也会检测到美国(交换的日期和月份)与世界其他地区之间的差异。

注意确保看起来像数字的列只有在没有不必要的前导零或加号的情况下才被视为数字。这是为了避免将电话号码和类似于字符串的数字视为整数。

此命令在处理大文件时可能会花费相当长的时间，因为它们实际上被导入了两次。第一次是确定每列的格式和类型，而第二次是实际导入数据。

后备？数据库？档案

Backup DB (default "main") to FILE

将当前数据库的内容复制到 FILE 覆盖其中的任何内容 FILE 。如果您有附加的数据库，那么您可以指定它们的名称，而不是缺省的“main”。

备份是在页面级完成的--SQLite按原样复制页面。在SQL代码中不存在往返。

保释|取消保释

Stop after hitting an error (default OFF)

如果在处理命令或SQL时遇到错误，则退出。(请注意，这与SQLiteShell不同，后者只在SQL中出现错误时才会退出。)

光盘？目录？

Changes current directory

如果未提供目录，则切换到主目录

更改打开|关闭

Show changes from last SQL and total changes (default OFF)

执行进行更改的SQL后，将显示受影响的行数以及所有更改的运行计数。

关

Closes the current database

使用.Open打开数据库，或使用.Connection切换到另一个连接

配色方案

Selects a colour scheme from default, off

如果在交互模式下使用彩色终端，则输出会自动上色，以使其更具可读性。使用 off 关闭颜色，没有名字或 default 用于默认配色方案。

联系？电话号码？

List connections, or switch active connection

这涵盖了所有连接，而不仅仅是在该Shell中启动的连接。关闭的连接不会显示。

数据库

Lists names and files of attached databases

数据库配置？名称值？

Show all dbconfig, or set a specific one

不带参数时列出所有设置。提供要更改的名称和整数值。例如：：

.dbconfig enable_fkey 1

数据库信息？名字？

Shows summary and file information about the database

这包括表、索引等的数量，以及由返回的文件中的字段 apsw.ext.dbinfo() 。

NAME 默认为 main ，并且可以是数据库的附加名称。

丢弃？桌子？ [TABLE...]

Dumps all or specified tables in SQL text format

表名被视为LIKE模式，因此您可以使用 % 作为通配符。您可以使用DUMP对数据库进行基于文本的备份。它对于比较差异或使数据可供其他数据库使用也很有用。表(S)的索引和触发器也被转储。最后，与表模式名称匹配的视图被转储(不可能计算出哪些视图访问哪些表，而视图无论如何都可以访问多个表)。

请注意，如果您转储的是FTS5模块使用的虚拟表，那么它们可能会使用其他表来存储信息。例如，如果您创建一个名为 recipes 然后它还会创造出 recipes_content ， recipes_segdir 因此，要正确转储此示例，请使用：：

.dump recipes recipes_%

如果数据库为空或没有匹配的表/视图，则不会输出。

Echo ON|OFF

If ON then each SQL statement or command is printed before execution (default OFF)

将SQL语句或命令发送到错误输出，以便它不会与常规输出混合在一起。

编码编码

Set the encoding used for new files opened via .output and imports

SQLite和APSW在内部使用Unicode和字符。然而，文件是一个字节序列。编码描述了如何在字节和字符之间进行转换。默认编码是UTF8，当其他程序提供选择时，这通常是最好的选择。

您还可以指定错误处理程序。例如 cp437:replace 将使用代码页437，cp437中不存在的任何Unicode代码点都将被替换(通常使用问号之类的符号)。其他错误处理程序包括 ignore ， strict (默认)和 xmlcharrefreplace 。

对于启动时的默认输入/输出/错误流，Shell程序遵循Python的编码检测。例如，在Windows上，它询问正在使用的代码页，而在Unix上，它查看 LC_CTYPE 环境变量。您可以将 PYTHONIOENCODING 环境变量来覆盖此检测。

此命令会影响在设置编码和导入后打开的文件。

例外打开|关闭

If ON then detailed tracebacks are shown on exceptions (default OFF)

正常情况下，当发生异常时，只显示错误字符串。然而，有时获取完整的回溯是有用的。例如，当您正在开发虚拟表并使用Shell来执行它们时。除了显示每个堆栈帧之外，还会显示每个帧内的局部变量。

出口？密码？

Exit this program with optional exit code

找到价值？桌子？

Searches all columns of all tables for a value

Find命令可以帮助您在整个数据库中定位数据，例如查找字符串或对id的任何引用。

您可以指定LIKE模式以将搜索限制在表的子集内(例如指定 CUSTOMER% 对于所有以 CUSTOMER )。

如果可能，该值将被视为字符串和/或整数。如果值包含 % 或 _ 然后，它也被视为相似的模式。

执行此命令可能需要很长时间，需要扫描所有相关的表。

页眉(S)开|关

Display the column names in output (default OFF)

帮助？指挥部？

Shows list of commands and their usage

如果 COMMAND ，然后显示有关该属性的详细信息。 COMMAND 。 .help all 将显示有关所有命令的详细帮助。

导入文件表

Imports separated data from FILE into TABLE

使用当前分隔符和编码将数据从文件读取到命名表中。例如，如果分隔符当前为逗号，则文件应为CSV(逗号分隔值)。

所有读入的值都以字符串的形式提供给SQLite。如果希望SQLite将它们视为其他类型，则适当地声明您的列。例如，声明一列 REAL 将导致这些值以浮点形式存储(如果它们可以安全地转换)。

另一种方法是创建一个临时表，将值插入其中，然后使用强制转换。：：

CREATE TEMPORARY TABLE import(a,b,c);
.import filename import
CREATE TABLE final AS SELECT cast(a as BLOB), cast(b as INTEGER),
     cast(c as CHAR) from import;
DROP TABLE import;

您还可以使用SQL使其变得更加复杂 CASE 接线员。例如，这会将零长度字符串转换为NULL：：

SELECT CASE col WHEN '' THEN null ELSE col END FROM ...

索引表

Lists all indices on table TABLE

加载文件？条目？

Loads a SQLite extension library

注意：在您正在使用的SQLite库版本中可能未启用扩展加载。

默认情况下，在库中调用SQlite3_Expansion_init，但您可以指定一个替代入口点。

如果出现找不到扩展名的错误，则可能需要显式指定目录。例如，如果它在当前目录中，则使用：：

.load ./extension.so

登录|注销

Shows SQLite log messages (default off)

模式模式？选项？

Sets output mode to one of box column columns csv html insert json jsonl line lines list python qbox table tabs tcl

框：使用线条绘制和自动调整列大小的输出

列：在空格填充的列中左对齐的项目。如果它们不合适，它们就会被截断。如果没有为列指定宽度，则使用10，除非列名(标题)更长，在这种情况下使用该宽度。使用.Width命令更改列大小。

CSV：CSV格式的项目(逗号分隔)。对制表符分隔使用制表符模式。在切换模式后，您可以使用.parator命令来使用不同的命令。 A 逗号分隔符使用双引号进行引号，而其他分隔符不进行任何引号。用于此的PythonCSV库仅支持单字符分隔符。

超文本标记语言：超文本标记语言表格样式

INSERT：作为SQL INSERT语句的行。表名为“TABLE”，除非您将另一个表名指定为.mode命令的第二个参数。

JSON：输出JSON数组。BLOB以Base64编码字符串的形式输出。

Jsonl：输出为JSON对象，换行符分隔。BLOB以Base64编码字符串的形式输出。

行：‘Column=Value’形式的每行一个值，行之间有一个空行。

列表：所有项目都在一行上，用分隔符分隔

PYTHON：每一行的PYTHON源代码形式的元组

Qbox：使用线条绘制和自动调整列大小引用值的输出

表：使用ASCII线条绘制和经过高度清理的文本的输出

TCL：使用当前分隔符输出TCL/C样式字符串

空值字符串

Print STRING in place of null values

这会影响列和列表等文本输出模式，并设置SQL空值的显示方式。缺省值为零长度字符串。插入模式和转储不受此设置的影响。您可以使用双引号提供零长度字符串。例如：：

.nullvalue ""         # the default
.nullvalue <NULL>     # rather obvious
.nullvalue " \\t "     # A tab surrounded by spaces

打开？选项？？文件？

Opens a database connection

选项包括：

--wipe

关闭此过程中引用同一文件的所有现有连接，并在打开之前删除数据库文件、日记等

--vfs VFS

打开时使用哪个VFS

如果 FILE 则打开内存数据库

输出文件名

Send output to FILENAME (or stdout)

如果 FILENAME 是 stdout 然后，从启动Shell时开始，将输出发送到标准输出。使用当前编码打开文件(更改为 encoding 命令)。

参数CMD...

Maintain named bindings you can use in your queries.

指定子命令：：

list            -- shows current bindings
clear           -- deletes all bindings
unset NAME      -- deletes named binding
set NAME VALUE  -- sets binding to VALUE

该值必须是有效的SQL文本或表达式。例如 3 将是一个整数3，而 '3' 将是一个字符串。

示例：

.parameter set floor 10.99
.parameter set text 'Acme''s Glove'
SELECT * FROM sales WHERE price > $floor AND description != $text;

提示主？是否继续？

Changes the prompts for first line and continuation lines

默认情况下，在主提示符下打印‘sqlite>’，您可以在其中输入点命令或SQL语句。如果SQL语句不完整(例如，NOT；TERMINATED)，则会使用继续提示符来提示您输入更多语句，该提示符默认为‘..>’。示例：：

.prompt "command> " "more command> "

You can use backslash escapes such as \n and \t.

PY？ Python ？

Starts a python REPL or runs the Python statement provided

提供的命名空间包括 apsw 对于模块， shell 对于该Shell和 db 用于当前数据库。

使用.out命令不会影响此命令的输出。你可以写信给 shell.stdout 和 shell.stderr 。

读取文件名

Processes SQL and commands in FILENAME (or Python if FILENAME ends with .py)

将指定的文件视为输入(混合或SQL和/或点命令)。如果文件名以.py结尾，则会将其视为Python代码。

对于Python代码，符号 db 指当前数据库， shell 是指Shell的实例，并且 apsw 是apsw模块。

恢复？数据库？档案

Restore database from FILE into DB (default "main")

复制的内容 FILE 到当前数据库(默认为“Main”)。备份是在页面级完成的--SQLite按原样复制页面。在SQL代码中不存在往返。

模式？表？ [TABLE...]

Shows SQL for table

如果给出一个或多个表，则会列出它们的模式(包括索引)。如果您没有指定任何模式，则会列出所有模式。 TABLE 是一种LIKE模式，因此您可以 % 用于通配符。

分隔符字符串

Change separator for output mode and .import

您可以使用引号和反斜杠。例如，要将分隔符设置为空格制表符空间，可以使用：：

.separator " \\t "

当您切换到CSV或TAB输出模式时，该设置会自动更改。您还应该在执行导入之前设置它(即，对于CSV和\t对于TSV)。

壳牌CMD参数...

Run CMD ARGS in a system shell

请注意，输出将进入流程标准输出，而不是Shell.out命令配置的任何内容。

显示

Show the current values for various settings.

桌子？图案？

Lists names of tables matching LIKE pattern

这也会返回视图。

超时MS

Try opening locked tables for MS milliseconds

如果数据库被另一个进程锁定，SQLite将继续重试。这设置了它将继续尝试的千分之几秒。如果提供零或负数，则禁用所有忙碌的处理程序。

计时器开|关

Control printing of time and resource usage after each query

当显示为浮点或绝对计数时，显示的值以秒为单位。仅显示自开始查询以来更改过的项目。在非Windows平台上，可以显示更多信息。

版本

Displays SQLite, APSW, and Python version information

Vfsinfo

Shows detailed information about the VFS for the database

Vfslist

Shows detailed information about all the VFS available

Vfsname

VFS name used to open current database

宽度数字...

Set the column widths for "column" mode

在“列”输出模式中，每列都是固定的宽度，值被截断以适应需要。使用此命令指定新宽度。使用负数右对齐，使用零作为默认列宽。

Shell类

这是您希望将代码集成到您的Shell中的API。此处未显示的是实现各种命令的函数。它们是以命令命名的。例如，.exit由COMMAND_EXIT实现。您可以通过使子类具有相关函数来添加新命令。该函数的文档字符串由Help命令使用。输出模式的工作方式与此类似。例如，有一个outputhtml方法，同样，帮助函数使用了文档字符串，您只需实现一个适当命名的方法就可以添加更多内容。

请注意，除了扩展Shell外，还可以使用 .read 命令为文件名提供 .py 分机。然后你就可以 monkey patch 根据需要选择Shell。