root/1.8.3/branches/gc/README.SQL

Revision 1299, 7.3 KB (checked in by shawnw, 3 months ago)

GC: Update to p7
Line 
1
2                            Use SQL with PennMUSH
3                             Revised: 24 May 2004
4
5
6As of version 1.7.7p32, PennMUSH includes functions and commands that
7can access SQL databases. Currently, the following databases are
8supported:
9
10  * MySQL
11  * PostgresQL (from 1.8.3p2)
12  * Sqlite v3  (from 1.8.3p2)
13
14This document explains how to use (or avoid) SQL with PennMUSH, and
15covers the following issues:
16
17   I. Compiling with or without SQL
18   II. Mush configuration overview
19   III. SQL setup tips
20
21I. Compiling with/without SQL
22
23In general, Configure attempts to detect all support sql client
24libraries on the host, and will link with all of them, permitting you
25to select which platform you want at runtime. You can selectively
26prevent linking with client libraries that are present on your system,
27by passing configure a --without-FOO option. --disable-sql turns off
28all checks for SQL servers.
29
30I.a. MySQL
31
32  The configure script distributed with PennMUSH automatically detects
33  the MySQL client library via the presence of the mysql_config
34  program, which will tell configure where needed headers and
35  libraries are.
36
37  If you want to avoid linking these libraries on systems where they
38  are present, pass the --without-mysql switch to configure.
39
40  If you installed Mysql from a binary package (e.g. rpm or apt), you
41  should be sure that your system also has the development package
42  (usuallyl mysql-dev or mysql-devel).
43
44  If you think you have mysql libraries and header files but configure
45  isn't finding them, they may be in an unusual location on your
46  system, with mysql_config not in your default path.  Find its
47  location ('where mysql_config' if the program works for you, 'find /
48  -name mysql_config' otherwise, and call configure with
49  --with-mysql=/path/to/mysql_config
50
51I.b. PostgresQL
52
53  The configure script distributed with PennMUSH automatically detects
54  the PostgresQL client library via the pg_conf program, which will
55  tell configure where needed headers and libraries are.
56
57  If you want to avoid linking these libraries on systems where they
58  are present, pass the --without-postgresql switch to configure.
59
60  If you installed PostgresQL from a binary package (e.g. rpm or apt),
61  you should be sure that your system also has the development package
62  (usually postgresql-dev, or libpq or similar)
63
64  If you think you have postgresql libraries and header files but
65  configure isn't finding them, they may be in an unusual location on
66  your system, with pg_config not in your default path.  Find its
67  location ('where pg_config' if the program works for you, 'find /
68  -name pg_config' otherwise, and call configure with
69  --with-postgresql=/path/to/pg_config
70
71I.c Sqlite
72
73  The configure script distrubted with PennMUSH looks for sqlite3
74  headers and libraries in /usr, /usr/local and /opt. If it's
75  somewhere else on your system, call configure with
76  --with-sqlite3=/path/to/sqlite3
77 
78  If you want to avoid linking with sqlite on systems where it is
79  present, pass the --without-sqlite3 switch to configure.
80
81  The path is the directory that contains the hdrs/ and lib/
82  directories that hold the sqlite3 headers and library respectively.
83
84II. Mush configuration overview
85
86  mush.cnf includes these directives that configure the SQL support:
87
88  sql_platform provides the name of the SQL database server software
89  that will be used for connections. It current takes one of four
90  values: "disabled" (no SQL), "mysql", "postgresql", or "sqlite3".
91  If not specified, it defaults to disabled.
92
93  sql_host gives the name of the host running the SQL server.  It
94  defaults to 127.0.0.1, which makes a TCP connection to the local
95  host. The keyword "localhost" instead makes a domain socket (Unix)
96  or named pipe (Windows) connection under MySQL.  You can also
97  specify an alternate port by setting sql_host to hostname:port
98  (e.g. 127.0.0.1:5444).
99
100  sql_database gives the name of the database that contains the MUSH's
101  tables. This must be specified and there is no default.
102 
103  sql_username provides a username to connect to the SQL server
104  with. If no specified, a null username will be used, which many SQL
105  servers treat as "the user running this (pennmush) process".
106
107  sql_password provides the password for the user. It defaults to no
108  password.
109 
110  For sqlite3, which uses a local file instead of connected to a
111  database server, sql_database gives the name of the database file,
112  sql_host must be localhost, and the username and password are
113  currently ignored.
114
115III. SQL setup tips
116
117  You will have to set up the appropriate database on the SQL server,
118  and username permitted to perform operations in that database, and a
119  password for that username. This is a platform-specific process.
120
121  A. MySQL platform
122
123    Easiest way is:
124
125    % mysql_setpermission --user root           REQUIRED
126          --host <mysql host> --port <mysql port>   OPTIONAL, OR:
127          --socket <unix domain socket>         OPTIONAL
128
129    ######################################################################
130    ## Welcome to the permission setter 1.2 for MySQL.
131    ## made by Luuk de Boer
132    ######################################################################
133    What would you like to do:
134      1. Set password for a user.
135      2. Add a database + user privilege for that database.
136         - user can do all except all admin functions
137      3. Add user privilege for an existing database.
138         - user can do all except all admin functions
139      4. Add user privilege for an existing database.
140         - user can do all except all admin functions + no create/drop
141      5. Add user privilege for an existing database.
142         - user can do only selects (no update/delete/insert etc.)
143      0. exit this program
144   
145    Make your choice [1,2,3,4,5,0]: 2                    <==========
146
147    Which database would you like to add: mush
148    The new database mush will be created
149   
150    What username is to be created: mush                 <==========
151    Username = mush
152    Would you like to set a password for  [y/n]: y       <==========
153    What password do you want to specify for :           <==========
154    Type the password again:                             <==========
155    We now need to know from what host(s) the user will connect.
156    Keep in mind that % means 'from any host' ...
157    The host please: localhost                           <==========
158    Would you like to add another host [yes/no]: no      <==========
159    Okay we keep it with this ...
160    The following host(s) will be used: localhost.
161    ######################################################################
162   
163    That was it ... here is an overview of what you gave to me:
164    The database name       : mush
165    The username            : mush
166    The host(s)             : localhost
167    ######################################################################
168   
169    Are you pretty sure you would like to implement this [yes/no]: yes
170
171  B. PostgresQL
172
173    As the postgres user:
174
175    % createuser -A -d -P mush
176    Enter password for new user:            <===========
177    CREATE USER
178
179    % createdb -U mush mush
180    Password:                   <===========
181    CREATE DATABASE
182
183  C. Sqlite3:
184   
185    As the same user account that runs the mush:
186       Edit mush.cnf so that sql_database is set to data/mush.db and
187       sql_platform is set to sqlite3.
188       % cd pennmush/game/data
189       % sqlite3 mush.db
190         > create table ....
Note: See TracBrowser for help on using the browser.