mirror of
https://github.com/darlinghq/fmdb.git
synced 2025-02-20 13:53:44 +00:00
Merge pull request #306 from nemesis/patch-1
Bump version in README.markdown
This commit is contained in:
commit
f6f96d44bf
@ -1,4 +1,4 @@
|
||||
# FMDB v2.3
|
||||
# FMDB v2.4
|
||||
This is an Objective-C wrapper around SQLite: http://sqlite.org/
|
||||
|
||||
## The FMDB Mailing List:
|
||||
@ -21,7 +21,10 @@ FMDB can be installed using [CocoaPods](http://cocoapods.org/).
|
||||
|
||||
```
|
||||
pod 'FMDB'
|
||||
# pod 'FMDB/SQLCipher' # If using FMDB with SQLCipher
|
||||
# pod 'FMDB/FTS' # FMDB with FTS
|
||||
# pod 'FMDB/standalone' # FMDB with latest SQLite amalgamation source
|
||||
# pod 'FMDB/standalone/FTS' # FMDB with latest SQLite amalgamation source and FTS
|
||||
# pod 'FMDB/SQLCipher' # FMDB with SQLCipher
|
||||
```
|
||||
|
||||
**If using FMDB with [SQLCipher](http://sqlcipher.net/) you must use the FMDB/SQLCipher subspec. The FMDB/SQLCipher subspec declares SQLCipher as a dependency, allowing FMDB to be compiled with the `-DSQLITE_HAS_CODEC` flag.**
|
||||
@ -49,7 +52,7 @@ An `FMDatabase` is created with a path to a SQLite database file. This path can
|
||||
(For more information on temporary and in-memory databases, read the sqlite documentation on the subject: http://www.sqlite.org/inmemorydb.html)
|
||||
|
||||
FMDatabase *db = [FMDatabase databaseWithPath:@"/tmp/tmp.db"];
|
||||
|
||||
|
||||
### Opening
|
||||
|
||||
Before you can interact with the database, it must be opened. Opening fails if there are insufficient resources or permissions to open and/or create the database.
|
||||
@ -58,7 +61,7 @@ Before you can interact with the database, it must be opened. Opening fails if
|
||||
[db release];
|
||||
return;
|
||||
}
|
||||
|
||||
|
||||
### Executing Updates
|
||||
|
||||
Any sort of SQL statement which is not a `SELECT` statement qualifies as an update. This includes `CREATE`, `UPDATE`, `INSERT`, `ALTER`, `COMMIT`, `BEGIN`, `DETACH`, `DELETE`, `DROP`, `END`, `EXPLAIN`, `VACUUM`, and `REPLACE` statements (plus many more). Basically, if your SQL statement does not begin with `SELECT`, it is an update statement.
|
||||
@ -77,14 +80,14 @@ In order to iterate through the results of your query, you use a `while()` loop.
|
||||
while ([s next]) {
|
||||
//retrieve values for each record
|
||||
}
|
||||
|
||||
|
||||
You must always invoke `-[FMResultSet next]` before attempting to access the values returned in a query, even if you're only expecting one:
|
||||
|
||||
FMResultSet *s = [db executeQuery:@"SELECT COUNT(*) FROM myTable"];
|
||||
if ([s next]) {
|
||||
int totalCount = [s intForColumnIndex:0];
|
||||
}
|
||||
|
||||
|
||||
`FMResultSet` has many methods to retrieve data in an appropriate format:
|
||||
|
||||
- `intForColumn:`
|
||||
@ -108,7 +111,7 @@ Typically, there's no need to `-close` an `FMResultSet` yourself, since that hap
|
||||
When you have finished executing queries and updates on the database, you should `-close` the `FMDatabase` connection so that SQLite will relinquish any resources it has acquired during the course of its operation.
|
||||
|
||||
[db close];
|
||||
|
||||
|
||||
### Transactions
|
||||
|
||||
`FMDatabase` can begin and commit a transaction by invoking one of the appropriate methods or executing a begin/end transaction statement.
|
||||
@ -136,7 +139,6 @@ success = [self.db executeStatements:sql withResultBlock:^int(NSDictionary *dict
|
||||
XCTAssertEqual(count, 1, @"expected one record for dictionary %@", dictionary);
|
||||
return 0;
|
||||
}];
|
||||
|
||||
```
|
||||
|
||||
### Data Sanitization
|
||||
@ -144,13 +146,13 @@ success = [self.db executeStatements:sql withResultBlock:^int(NSDictionary *dict
|
||||
When providing a SQL statement to FMDB, you should not attempt to "sanitize" any values before insertion. Instead, you should use the standard SQLite binding syntax:
|
||||
|
||||
INSERT INTO myTable VALUES (?, ?, ?)
|
||||
|
||||
|
||||
The `?` character is recognized by SQLite as a placeholder for a value to be inserted. The execution methods all accept a variable number of arguments (or a representation of those arguments, such as an `NSArray`, `NSDictionary`, or a `va_list`), which are properly escaped for you.
|
||||
|
||||
Alternatively, you may use named parameters syntax:
|
||||
|
||||
INSERT INTO myTable VALUES (:id, :name, :value)
|
||||
|
||||
|
||||
The parameters *must* start with a colon. SQLite itself supports other characters, but internally the Dictionary keys are prefixed with a colon, do **not** include the colon in your dictionary keys.
|
||||
|
||||
NSDictionary *argsDict = [NSDictionary dictionaryWithObjectsAndKeys:@"My Name", @"name", nil];
|
||||
@ -159,23 +161,23 @@ The parameters *must* start with a colon. SQLite itself supports other character
|
||||
Thus, you SHOULD NOT do this (or anything like this):
|
||||
|
||||
[db executeUpdate:[NSString stringWithFormat:@"INSERT INTO myTable VALUES (%@)", @"this has \" lots of ' bizarre \" quotes '"]];
|
||||
|
||||
|
||||
Instead, you SHOULD do:
|
||||
|
||||
[db executeUpdate:@"INSERT INTO myTable VALUES (?)", @"this has \" lots of ' bizarre \" quotes '"];
|
||||
|
||||
|
||||
All arguments provided to the `-executeUpdate:` method (or any of the variants that accept a `va_list` as a parameter) must be objects. The following will not work (and will result in a crash):
|
||||
|
||||
[db executeUpdate:@"INSERT INTO myTable VALUES (?)", 42];
|
||||
|
||||
|
||||
The proper way to insert a number is to box it in an `NSNumber` object:
|
||||
|
||||
[db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:42]];
|
||||
|
||||
|
||||
Alternatively, you can use the `-execute*WithFormat:` variant to use `NSString`-style substitution:
|
||||
|
||||
[db executeUpdateWithFormat:@"INSERT INTO myTable VALUES (%d)", 42];
|
||||
|
||||
|
||||
Internally, the `-execute*WithFormat:` methods are properly boxing things for you. The following percent modifiers are recognized: `%@`, `%c`, `%s`, `%d`, `%D`, `%i`, `%u`, `%U`, `%hi`, `%hu`, `%qi`, `%qu`, `%f`, `%g`, `%ld`, `%lu`, `%lld`, and `%llu`. Using a modifier other than those will have unpredictable results. If, for some reason, you need the `%` character to appear in your SQL statement, you should use `%%`.
|
||||
|
||||
|
||||
@ -197,7 +199,7 @@ Then use it like so:
|
||||
[db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:1]];
|
||||
[db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:2]];
|
||||
[db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:3]];
|
||||
|
||||
|
||||
FMResultSet *rs = [db executeQuery:@"select * from foo"];
|
||||
while ([rs next]) {
|
||||
…
|
||||
@ -210,7 +212,7 @@ An easy way to wrap things up in a transaction can be done like this:
|
||||
[db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:1]];
|
||||
[db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:2]];
|
||||
[db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:3]];
|
||||
|
||||
|
||||
if (whoopsSomethingWrongHappened) {
|
||||
*rollback = YES;
|
||||
return;
|
||||
@ -243,7 +245,7 @@ The contributors to FMDB are contained in the "Contributors.txt" file.
|
||||
|
||||
## Quick notes on FMDB's coding style
|
||||
|
||||
Spaces, not tabs. Square brackets, not dot notation. Look at what FMDB already does with curly brackets and such, and stick to that style.
|
||||
Spaces, not tabs. Square brackets, not dot notation. Look at what FMDB already does with curly brackets and such, and stick to that style.
|
||||
|
||||
## Reporting bugs
|
||||
|
||||
@ -256,7 +258,7 @@ And we've even added a template function to main.m (FMDBReportABugFunction) in t
|
||||
* Setup your table(s) in the code.
|
||||
* Make your query or update(s).
|
||||
* Add some assertions which demonstrate the bug.
|
||||
|
||||
|
||||
Then you can bring it up on the FMDB mailing list by showing your nice and compact FMDBReportABugFunction, or you can report the bug via the github FMDB bug reporter.
|
||||
|
||||
**Optional:**
|
||||
|
Loading…
x
Reference in New Issue
Block a user