e02ff6bac8b22f91d0efabdc651db85d668f470f
[php-sqllint.git] / README.rst
1 ***********
2 PHP-SQLlint
3 ***********
4
5 Command line tool to validate (syntax check) SQL files.
6 Primarily for MySQL ``.sql`` files.
7
8 Can be used in git pre-commit hooks to catch errors.
9 Use it from your shell, offline and without any SQL server.
10
11 You can also use it to format SQL queries.
12
13
14 =====
15 Usage
16 =====
17 Syntax check::
18
19     $ php-sqllint tests/files/create-missingcomma.sql 
20     Checking SQL syntax of tests/files/create-missingcomma.sql
21      Line 3, col 5 at "pid": A comma or a closing bracket was expected.
22      Line 3, col 13 at "11": Unexpected beginning of statement.
23      Line 3, col 17 at "DEFAULT": Unrecognized statement type.
24
25 Emacs mode::
26
27     $ php-sqllint -r emacs tests/files/create-noname.sql 
28     tests/files/create-noname.sql:1.12:Error: The name of the entity was expected.
29     tests/files/create-noname.sql:1.13:Error: A closing bracket was expected.
30     tests/files/create-noname.sql:1.13:Error: At least one column definition was expected.
31
32
33 Formatting::
34
35     $ php-sqllint --format tests/files/select-unformatted.sql
36     SELECT
37       id,
38       NAME,
39       url
40     FROM
41       users
42     WHERE
43       DATE > NOW() AND id != 0
44     ORDER BY NAME
45     LIMIT 10
46
47
48 Syntax highlighting
49 ===================
50 ANSI colors are applied automatically when not piping; you can use the
51 ``--highlight`` option to override the automatism.
52
53 ``--highlight`` option values:
54
55 ``none``
56   No highlighting. Use it to disable automatic highlighting
57 ``ansi``
58   ANSI escape codes for your shell
59 ``html``
60   HTML tags
61
62
63 ====
64 Bugs
65 ====
66 Does ``php-sqllint`` not detect a syntax error, or doesn't support a certain
67 SQL statement?
68 Then please report a bug at `udan11/sql-parser`__.
69
70 __ https://github.com/udan11/sql-parser
71
72
73 ============
74 Dependencies
75 ============
76 - PEAR's `Console_Commandline`__
77 - `udan11's SqlParser`__, which is used by `phpMyAdmin`__
78
79 __ http://pear.php.net/package/Console_CommandLine
80 __ https://github.com/udan11/sql-parser
81 __ https://www.phpmyadmin.net/
82
83
84 Dependency installation
85 =======================
86 ::
87
88     $ composer install
89
90 Now you can use ``./bin/php-sqllint`` without building the phar yourself.
91
92
93 ========
94 Building
95 ========
96
97 Preparation
98 ===========
99 - Adjust version number in ``src/phpsqllint/Cli.php``
100 - Adjust version number in ``build.xml``
101
102
103 Create the release
104 ==================
105 You'll need `phing`__, the PHP build tool::
106
107     $ phing
108
109 __ https://www.phing.info/
110
111 The result are ``.phar`` files in ``dist/`` directory that you can execute::
112
113     $ ./dist/php-sqllint-0.0.1.phar tests/files/create-noname.sql 
114     Checking SQL syntax of tests/files/create-noname.sql
115      Line 1, col 12 at "(": The name of the entity was expected.
116
117
118 =================
119 About PHP-SQLlint
120 =================
121
122 License
123 =======
124 ``php-sqllint`` is licensed under the `AGPL v3`__ or later.
125
126 __ http://www.gnu.org/licenses/agpl.html
127
128
129 Homepage
130 ========
131 Home page
132    http://cweiske.de/php-sqllint.htm
133 Source code
134    http://git.cweiske.de/php-sqllint.git
135
136    Mirror: https://github.com/cweiske/php-sqllint
137
138
139 Author
140 ======
141 Written by Christian Weiske, cweiske@cweiske.de